Envía tu primer evento estructurado

Esta guía envía a Telemetry el resultado ficticio de una solicitud a una API. Tras recibir una respuesta 200, comprobarás que el evento tiene campos útiles para consultas SQL, paneles, alertas y depuración. No incluyas el contenido de la solicitud.

Antes de empezar

¿Ya copiaste las instrucciones de la página de inicio? Usa la clave anon_… que aparece allí para enviar y consultar eventos sin crear una cuenta.

Si tienes una cuenta, crea una clave read-and-write en Configuración del equipo → Claves API para poder consultar el evento después. Una aplicación que solo envía eventos puede usar una clave ingest.

Guarda la clave en una variable de entorno local o un gestor de secretos:

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

Mantén privadas las claves anónimas, de solo lectura y de lectura y escritura. Para registrar eventos desde el navegador o una app móvil puedes usar una clave Ingest only, que no permite consultar ni administrar datos. Esa clave puede copiarse y usarse para enviar eventos no deseados; vigílala y revócala si se usa indebidamente. Consulta Claves de API y autenticación para elegir permisos y rotar claves.

Elige un flujo de trabajo terminado

Empieza donde la aplicación ya conoce el resultado de una operación. Algunos buenos primeros eventos son:

• api_request_completed
• background_job_completed
• webhook_processing_completed
• checkout_completed
• agent_run_completed

Prefiere el resultado de una operación terminada a un mensaje genérico como something_happened. Un nombre estable permite que todos los servicios y consultas cuenten la misma clase de evento.

Para este ejemplo, usa una solicitud ficticia a una API:

{
  "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 ruta es una plantilla, no una URL real que pueda contener identificadores. El evento incluye el resultado y un identificador para relacionarlo con otros registros; no incluye el cuerpo de la solicitud, cabeceras de autorización, cookies 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": "telemetry_quickstart",
    "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"
    }
  }'

Si tu versión del SDK o de la API difiere del ejemplo, consulta el formato de solicitud en la API de registro.

Enviar el mismo evento desde JavaScript

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

await telemetry.log("telemetry_quickstart", {
  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"
});

Inicializa el SDK en código de servidor de confianza. Mantén los mismos nombres de campo y unidades en todos los servicios: por ejemplo, guarda siempre la duración en milisegundos en latency_ms.

¿Qué significa el éxito?

Puedes hacer consultas anónimas durante 24 horas después del primer evento. Crea una cuenta en un plazo de 7 días para conservar los eventos y la misma clave. Si te registras en este navegador, el formulario detectará la prueba. En otro navegador, elige ¿Ya tienes una clave API anónima?, pega la clave y pulsa Buscar mis datos antes de registrarte. Si ya tienes una cuenta, usa Conservar mis datos e inicia sesión. Una prueba sin eventos caduca 7 días después de su creación.

Una respuesta de éxito solo prueba que la API aceptó el evento. Sigue con Verificar la ingesta de eventos para comprobar la tabla, los tipos inferidos, la marca de tiempo y la fila exacta. Antes de registrar más operaciones, comprueba que este primer evento se puede consultar sin exponer datos sensibles.

Este ejemplo es ficticio y solo comprueba la conexión con la API. Para completar la integración de tu aplicación, registra un evento al terminar una operación real, ejecuta esa operación y consulta el evento almacenado. Una fila en telemetry_quickstart por sí sola no completa la configuración.

Para ampliar el esquema, lee Diseñar un esquema de evento. Si hay campos sensibles, consulta Cómo ocultar datos sensibles.