API Profissional

API TraceLog

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

Autenticação

Todos os pedidos devem incluir a sua chave de API no cabeçalho Authorization como token Bearer. Por motivos de segurança, as nossas chaves são armazenadas com hash SHA-256 e podem ser alvo de rotação a qualquer momento.

Authorization: Bearer YOUR_API_KEY

Escopo de Equipa

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

Faça a gestão das chaves em Definições da API.

URL Base

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

A 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 equipa atual. Permite identificar o estado 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 (devolvia sempre `null`) e que deixou de existir na resposta a partir de 2026-08. Para revelar a chave de uma sonda, utilize o ecrã de Sondas no painel.

Exemplos de Pedido

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 monitorização (destinos) registados na sua conta.

Exemplos de Pedido

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, estado 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 Pedido

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

Aceda ao 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 são hoje observações, não eventos. Os detalhes incluem status, confiança e evidência para diferenciar incidentes confirmados de comportamentos suspeitos ou observados. Por defeito 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 indique `?cursor=`): o envelope muda para cursor, com custo constante a qualquer profundidade da consulta, mas sem `total` nem `last_page` — calcular o total exigiria contar a tabela inteira a cada pedido.

Exemplos de Pedido

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 predefinição a resposta é paginada por página numerada, com `total` e `last_page` — use este modo para localizar uma página específica. Para percorrer um histórico longo ou exportar dados, use `?paginate=cursor` (ou indique `?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` neste envelope, que exigiria contar a tabela inteira a cada pedido.

Exemplos de Pedido

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 Pedido

Obter 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 a pesquisa.	24
days	Número de dias para a pesquisa.	-
per_page	Quantidade de registos 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 devolvido em `next_cursor`/`prev_cursor`. Indicá-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 nas suas consultas.