API Profissional

API TraceLog

Integre dados reais do TraceLog em seus próprios sistemas, painéis e automações via nossa API RESTful segura.

Autenticação

Todas as requisições devem incluir sua chave de API no cabeçalho Authorization como um token Bearer. Para segurança, nossas chaves são armazenadas com hash SHA-256 e podem ser rotacionadas a qualquer momento.

Authorization: Bearer YOUR_API_KEY

Escopo de Equipe

A API retorna apenas recursos vinculados à sua Equipe atual. Se você faz parte de múltiplas equipes, os dados serão filtrados pela equipe selecionada no momento da geração da chave.

Gerencie chaves em Configurações da API.

URL Base

https://tracelog.evocode.ia.br/api/v1

Nossa API segue padrões REST e utiliza JSON para todas as comunicações de dados.

Endpoints Disponíveis

GET/sensors

Lista todas as sondas vinculadas à sua equipe atual. Permite identificar o status de conectividade e a última sincronização de cada agente. Atenção: versões anteriores desta documentação anunciavam um campo `visible_api_key`, que este endpoint nunca chegou a preencher (sempre retornava `null`) e que deixou de existir na resposta a partir de 2026-08. Para revelar a chave de uma sonda, use a tela de Sondas no painel.

Exemplos de Requisição

Listar Sondas

curl -X GET "https://tracelog.evocode.ia.br/api/v1/sensors" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Exemplo de Resposta

[
  {
    "id": 1,
    "name": "São Paulo DataCenter",
    "status": "online",
    "city": "São Paulo",
    "country_code": "BR",
    "last_checkin_at": "2024-01-16T15:00:00Z"
  },
  {
    "id": 2,
    "name": "US-East Lambda Probe",
    "status": "offline",
    "city": "Ashburn",
    "country_code": "US",
    "last_checkin_at": "2024-01-15T10:22:00Z"
  }
]

GET/targets

Retorna a lista de alvos de monitoramento (destinos) registrados em sua conta.

Exemplos de Requisição

Listar Alvos

curl -X GET "https://tracelog.evocode.ia.br/api/v1/targets" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplo de Resposta

[
  {
    "id": 101,
    "name": "Gateway Principal",
    "host": "200.150.10.1",
    "status": "stable",
    "frequency": 5,
    "tags": [
      "infra",
      "core"
    ],
    "health_check_settings": [
      {
        "key": "dns_resolve",
        "type": "dns_resolve",
        "enabled": true,
        "timeout_ms": 3000
      }
    ]
  },
  {
    "id": 102,
    "name": "Google DNS",
    "host": "8.8.8.8",
    "status": "warning",
    "frequency": 1,
    "tags": [
      "external"
    ],
    "trigger_settings": {
      "monitor_performance_degradation": true,
      "latency_threshold_ms": 50,
      "loss_threshold_percentage": 10,
      "condition_duration_minutes": 5,
      "max_hops": 20
    },
    "monitor_load_balancing": true
  }
]

POST/sensor/report-health

Endpoint exclusivo da sonda para health checks reais por protocolo. As sondas podem reportar TCP connect, status HTTP, handshake TLS, resolução DNS, UDP e resultados ICMP/MTR. Essas verificações criam observações técnicas e alimentam o score de saúde do alvo antes de um evento ser promovido a incidente.

Exemplos de Requisição

Reportar saúde HTTPS

curl -X POST "https://tracelog.evocode.ia.br/api/v1/sensor/report-health" \
  -H "X-Sensor-Key: SENSOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_id":101,"check_type":"http_status","protocol":"ipv4","transport_protocol":"tcp","status":"up","success":true,"duration_ms":58,"status_code":200}'

Exemplo de Resposta

{
  "status": "ok",
  "id": 9001
}

GET/events

Acesse o histórico de eventos e anomalias de rota. São 6 tipos em 3 famílias — disponibilidade: target_offline e target_online (por sonda e protocolo); qualidade: performance_degradation (único evento de qualidade; details.metric é latency, loss ou both, e status percorre suspected → confirmed → recovered); caminho: route_change (com old_hop_count, new_hop_count, hop_count_delta e, quando a severidade sobe a aviso, correlated_event_id), final_host_change e routing_loop. Linhas históricas ainda podem trazer os tipos retirados high_latency, packet_loss, hop_count_exceeded e load_balancing; balanceamento e excesso de saltos hoje são observações, não eventos. Os detalhes incluem status, confiança e evidência para diferenciar incidentes confirmados de comportamentos suspeitos ou observados. Por padrão a resposta é paginada por página numerada, com `total` e `last_page` — use esse modo para localizar ou saltar para uma página específica. Para percorrer um histórico longo ou exportar dados, use `?paginate=cursor` (ou informe `?cursor=`): o envelope troca para cursor, com custo constante em qualquer profundidade da consulta, mas sem `total` nem `last_page` — calcular o total exigiria contar a tabela inteira a cada requisição.

Exemplos de Requisição

Eventos das últimas 24h

curl -X GET "https://tracelog.evocode.ia.br/api/v1/events?hours=24" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtrar por Alvo

curl -X GET "https://tracelog.evocode.ia.br/api/v1/events?target_id=101" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginação por cursor (histórico longo)

curl -X GET "https://tracelog.evocode.ia.br/api/v1/events?hours=24&paginate=cursor" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplo de Resposta

Página numerada (padrão)

{
  "current_page": 1,
  "data": [
    {
      "id": 5002,
      "type": "route_change",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "old_hop_count": 12,
        "new_hop_count": 14,
        "hop_count_delta": 2,
        "correlated_event_id": 5003,
        "correlated_event_type": "performance_degradation",
        "status": "confirmed",
        "confidence": 82,
        "evidence": [
          {
            "source": "route_diff",
            "label": "Comparação de rota anterior e atual",
            "observed": {
              "diff_type": "asn_path_change"
            }
          }
        ]
      },
      "created_at": "2024-01-16T14:30:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    },
    {
      "id": 5003,
      "type": "performance_degradation",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "metric": "latency",
        "latency": 150.5,
        "loss": 0,
        "thresholds": {
          "latency": 100,
          "loss": 10
        },
        "duration": 5,
        "protocol": "ipv4",
        "status": "confirmed",
        "affected_hops": [
          7,
          8
        ],
        "confidence": 88,
        "evidence": [
          {
            "source": "sample_metrics",
            "label": "Latência acima do limiar durante toda a janela"
          }
        ]
      },
      "created_at": "2024-01-16T14:35:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    },
    {
      "id": 5004,
      "type": "target_offline",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "loss_percentage": 100,
        "protocol": "ipv4",
        "consecutive_count": 3,
        "status": "confirmed",
        "confidence": 95,
        "evidence": [
          {
            "source": "sample_metrics",
            "label": "Perda de 100% em 3 amostras consecutivas"
          }
        ]
      },
      "created_at": "2024-01-16T14:40:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "offline"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "total": 1250,
  "per_page": 50
}

Cursor (paginate=cursor)

{
  "data": [
    {
      "id": 5002,
      "type": "route_change",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "old_hop_count": 12,
        "new_hop_count": 14,
        "hop_count_delta": 2,
        "correlated_event_id": 5003,
        "correlated_event_type": "performance_degradation",
        "status": "confirmed",
        "confidence": 82
      },
      "created_at": "2024-01-16T14:30:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "path": "https://tracelog.evocode.ia.br/api/v1/events",
  "per_page": 50,
  "next_cursor": "eyJpZCI6NTAwMiwiY3JlYXRlZF9hdCI6IjIwMjQtMDEtMTZUMTQ6MzA6MDBaIn0",
  "next_page_url": "https://tracelog.evocode.ia.br/api/v1/events?cursor=eyJpZCI6NTAwMiwiY3JlYXRlZF9hdCI6IjIwMjQtMDEtMTZUMTQ6MzA6MDBaIn0",
  "prev_cursor": null,
  "prev_page_url": null
}

GET/latency

Endpoint de alta frequência para obter dados brutos de desempenho (latência, jitter e perda). Por padrão a resposta é paginada por página numerada, com `total` e `last_page` — use esse modo para localizar uma página específica. Para percorrer um histórico longo ou exportar dados, use `?paginate=cursor` (ou informe `?cursor=`): medido com 2.000.000 de linhas e lotes de 50, o custo por página cresce de ~111 ms no primeiro lote a ~1437 ms no último, enquanto o cursor mantém ~25 ms em qualquer profundidade — porque não há `total`/`last_page` nesse envelope, que exigiria contar a tabela inteira a cada requisição.

Exemplos de Requisição

Desempenho Recente

curl -X GET "https://tracelog.evocode.ia.br/api/v1/latency?hours=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginação por cursor (histórico longo)

curl -X GET "https://tracelog.evocode.ia.br/api/v1/latency?hours=24&paginate=cursor" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplo de Resposta

Página numerada (padrão)

{
  "current_page": 1,
  "data": [
    {
      "id": 100450,
      "target_id": 101,
      "sensor_id": 1,
      "avg_latency": 12.45,
      "jitter": 1.2,
      "loss_percentage": 0,
      "created_at": "2024-01-16T15:05:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "total": 450000,
  "per_page": 10
}

Cursor (paginate=cursor)

{
  "data": [
    {
      "id": 100450,
      "target_id": 101,
      "sensor_id": 1,
      "avg_latency": 12.45,
      "jitter": 1.2,
      "loss_percentage": 0,
      "created_at": "2024-01-16T15:05:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "path": "https://tracelog.evocode.ia.br/api/v1/latency",
  "per_page": 10,
  "next_cursor": "eyJpZCI6MTAwNDUwLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNlQxNTowNTowMFoifQ",
  "next_page_url": "https://tracelog.evocode.ia.br/api/v1/latency?cursor=eyJpZCI6MTAwNDUwLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNlQxNTowNTowMFoifQ",
  "prev_cursor": null,
  "prev_page_url": null
}

GET/latency-history

Recuperar métricas históricas de latência para um alvo específico dentro de um intervalo de tempo definido. Ideal para análise detalhada de eventos passados.

Exemplos de Requisição

Obtenha o histórico da janela

curl -X GET "https://tracelog.evocode.ia.br/api/v1/latency-history?target_id=101&from=2024-01-16T12:00:00Z&to=2024-01-16T18:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplo de Resposta

[
  {
    "id": 100451,
    "target_id": 101,
    "sensor_id": 1,
    "avg_latency": 12.5,
    "jitter": 1.1,
    "loss_percentage": 0,
    "created_at": "2024-01-16T12:01:00Z"
  },
  {
    "id": 100452,
    "target_id": 101,
    "sensor_id": 1,
    "avg_latency": 12.8,
    "jitter": 1.3,
    "loss_percentage": 0,
    "created_at": "2024-01-16T12:02:00Z"
  }
]

Parâmetros de Consulta

Parâmetro	Descrição	Padrão
target_id	ID único do alvo para filtrar os resultados.	-
sensor_id	ID único da sonda para filtrar os resultados.	-
hours	Número de horas para busca.	24
days	Número de dias para busca.	-
per_page	Quantidade de registros por página.	50
paginate	Use `cursor` para trocar o envelope de página numerada pelo envelope de cursor (keyset) em /events e /latency.	-
cursor	Valor do cursor retornado em `next_cursor`/`prev_cursor`. Informá-lo também ativa a paginação por cursor em /events e /latency.	-
from	Data de início (ISO 8601) para intervalo histórico.	-
to	Data final (ISO 8601) para intervalo histórico.	-

Dica Pro

Complemente suas integrações cruzando dados de eventos e latência. Utilize os IDs obtidos nos endpoints /targets e /sensors para criar filtros granulares em suas consultas.