API Profesional

API TraceLog

Integra los datos reales de TraceLog en tus propios sistemas, paneles y automatizaciones a través de nuestra API RESTful segura.

Autenticación

Todas las solicitudes deben incluir tu clave de API en el encabezado Authorization como un token Bearer. Por seguridad, nuestras claves se almacenan con hash SHA-256 y pueden rotarse en cualquier momento.

Authorization: Bearer YOUR_API_KEY

Alcance por Equipo

La API solo devuelve recursos vinculados a tu Equipo actual. Si formas parte de varios equipos, los datos se filtrarán según el equipo seleccionado al momento de generar la clave.

Gestiona claves en Configuración de API.

URL Base

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

Nuestra API sigue los estándares REST y usa JSON para todas las comunicaciones de datos.

Endpoints Disponibles

GET/sensors

Lista todas las sondas vinculadas a tu equipo actual. Permite identificar el estado de conectividad y la última sincronización de cada agente. Atención: versiones anteriores de esta documentación anunciaban un campo `visible_api_key` que este endpoint nunca llegó a completar (siempre devolvía `null`) y que dejó de aparecer en la respuesta a partir de 2026-08. Para revelar la clave de una sonda, usa la pantalla de Sondas del panel.

Ejemplos de Solicitud

Listar Sondas

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

Ejemplo de Respuesta

[
  {
    "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

Devuelve la lista de objetivos de monitoreo (destinos) registrados en tu cuenta.

Ejemplos de Solicitud

Listar Objetivos

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

Ejemplo de Respuesta

[
  {
    "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 para sensores para comprobaciones reales de salud de protocolo. Las sondas pueden reportar resultados de conexión TCP, estado HTTP, handshake TLS, resolución DNS, y salud UDP e ICMP/MTR. Estas comprobaciones crean observaciones técnicas y alimentan las puntuaciones de salud del objetivo antes de que un evento se promueva a incidente.

Ejemplos de Solicitud

Reportar salud 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}'

Ejemplo de Respuesta

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

GET/events

Accede al historial de eventos y anomalías de ruta. Son 6 tipos en 3 familias — disponibilidad: target_offline y target_online (por sonda y protocolo); calidad: performance_degradation (único evento de calidad; details.metric es latency, loss o both, y status recorre suspected → confirmed → recovered); ruta: route_change (con old_hop_count, new_hop_count, hop_count_delta y, cuando la severidad sube a aviso, correlated_event_id), final_host_change y routing_loop. Las filas históricas aún pueden traer los tipos retirados high_latency, packet_loss, hop_count_exceeded y load_balancing; el balanceo y el exceso de saltos hoy son observaciones, no eventos. Los detalles incluyen status, confianza y evidencia para diferenciar incidentes confirmados de comportamientos sospechosos u observados. Por defecto la respuesta se pagina por número de página, con `total` y `last_page` — usa ese modo para localizar o saltar a una página específica. Para recorrer un historial largo o exportar datos, usa `?paginate=cursor` (o indica `?cursor=`): el sobre cambia a cursor, con costo constante a cualquier profundidad de la consulta, pero sin `total` ni `last_page` — calcular el total exigiría contar la tabla entera en cada solicitud.

Ejemplos de Solicitud

Eventos de las últimas 24h

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

Filtrar por Objetivo

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

Paginación por cursor (historial largo)

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

Ejemplo de Respuesta

Página numerada (predeterminado)

{
  "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 frecuencia para obtener datos de rendimiento sin procesar (latencia, jitter y pérdida). Por defecto la respuesta se pagina por página numerada, con `total` y `last_page` — usa este modo para localizar una página específica. Para recorrer un historial largo o exportar datos, usa `?paginate=cursor` (o indica `?cursor=`): medido con 2.000.000 de filas y lotes de 50, el costo por página crece de ~111 ms en el primer lote a ~1437 ms en el último, mientras que el cursor se mantiene en ~25 ms a cualquier profundidad — porque este envelope no tiene `total`/`last_page`, que requeriría contar toda la tabla en cada solicitud.

Ejemplos de Solicitud

Rendimiento Reciente

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

Paginación por cursor (historial largo)

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

Ejemplo de Respuesta

Página numerada (predeterminado)

{
  "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

Recupera métricas históricas de latencia de un objetivo específico dentro de una ventana de tiempo definida. Ideal para el análisis detallado de eventos pasados.

Ejemplos de Solicitud

Obtener historial para ventana

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"

Ejemplo de Respuesta

[
  {
    "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	Descripción	Predeterminado
target_id	ID único del objetivo para filtrar los resultados.	-
sensor_id	ID único de la sonda para filtrar los resultados.	-
hours	Número de horas hacia atrás para la búsqueda.	24
days	Número de días hacia atrás para la búsqueda.	-
per_page	Cantidad de registros por página.	50
paginate	Usa `cursor` para cambiar el envelope de página numerada por el envelope de cursor (keyset) en /events y /latency.	-
cursor	Valor del cursor devuelto en `next_cursor`/`prev_cursor`. Indicarlo también activa la paginación por cursor en /events y /latency.	-
from	Fecha de inicio (ISO 8601) para el rango del historial.	-
to	Fecha de finalización (ISO 8601) para el rango del historial.	-

Consejo Pro

Complementa tus integraciones cruzando datos de eventos y latencia. Usa los IDs obtenidos de los endpoints /targets y /sensors para crear filtros granulares en tus consultas.