Envíe su primer evento estructurado

Este tutorial envía un resultado sintético API a Telemetry. El objetivo no es sólo recibir una respuesta 200. Para comenzar, se trata de un contrato de evento que puede admitir SQL, paneles, alertas y, posteriormente, depuración sin recopilar una carga útil de solicitud sin procesar.

Antes de empezar

Cree un equipo y una clave con alcance write en Configuración del equipo → Claves API. Mantenga el valor en una variable de entorno local o administrador secreto:

export TELEMETRY_API_KEY="replace-with-your-key"

No exponga una clave de equipo en el navegador JavaScript, una aplicación móvil, un repositorio público o una captura de pantalla. Consulte Claves de API y autenticación para obtener orientación sobre el alcance y la rotación.

Elija un flujo de trabajo completo

Comience en un límite donde la aplicación conozca el resultado. Los buenos primeros eventos incluyen:

• api_request_completed
• background_job_completed
• webhook_processing_completed
• checkout_completed
• agent_run_completed

Prefiere un resultado completo a un mensaje genérico como something_happened. Un nombre de evento estable le da a cada productor y consulta el mismo grano.

Para este ejemplo, utilice una solicitud API sintética:

{
  "route_template": "/api/reports/:report_id",
  "method": "POST",
  "status": "success",
  "status_code": 200,
  "latency_ms": 184,
  "release": "local-demo",
  "environment": "development",
  "request_id": "req_demo_001"
}

La URL es una plantilla de ruta en lugar de una URL sin formato que contiene identificadores. El evento incluye campos de resultados categorizados y un identificador de correlación seguro, pero no incluye cuerpo de solicitud, encabezado de autorización, cookie ni contenido del cliente.

Enviar el evento con cURL

curl https://api.telemetry.sh/log \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "api_request_completed",
    "data": {
      "route_template": "/api/reports/:report_id",
      "method": "POST",
      "status": "success",
      "status_code": 200,
      "latency_ms": 184,
      "release": "local-demo",
      "environment": "development",
      "request_id": "req_demo_001"
    }
  }'

Utilice la forma de solicitud exacta documentada por Registro API si su versión SDK o API difiere de este ejemplo.

Enviar el mismo evento desde JavaScript

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

await telemetry.log("api_request_completed", {
  route_template: "/api/reports/:report_id",
  method: "POST",
  status: "success",
  status_code: 200,
  latency_ms: 184,
  release: "local-demo",
  environment: "development",
  request_id: "req_demo_001"
});

Inicialice el SDK en un código del lado del servidor confiable. Mantenga los nombres de los campos y las unidades coherentes en todos los servicios; por ejemplo, almacene siempre la duración en latency_ms en lugar de mezclar segundos y milisegundos.

¿Qué significa el éxito?

Un envío exitoso sólo prueba que el API aceptó el evento. Continúe con Verificar la ingesta de eventos para verificar el nombre de la tabla, los tipos inferidos, la marca de tiempo generada y la fila exacta. No instrumente más flujos de trabajo hasta que el primer contrato de evento sea consultable y seguro.

Para obtener un esquema más amplio, lea Diseñar un esquema de evento. Para campos sensibles, utilice Eliminación de datos sensibles confidenciales.