Inicio rápido

Envíe eventos JSON a Telemetry y consúltelos con SQL. En esta guía enviará un evento, revisará la tabla que crea Telemetry y ejecutará una consulta.

Si está interesado en obtener más información sobre cómo funciona el Telemetry bajo el capó, consulte nuestro Documento de arquitectura Telemetry para obtener una descripción detallada. Para un caso de uso más detallado, como el seguimiento de los costos de OpenAI mediante la instrumentación de llamadas de API, consulte nuestra guía sobre Seguimiento de costos de OpenAI.

¿Prefieres avanzar con tareas breves? Sigue estos pasos:

1. Envíe su primer evento estructurado
2. Verificar la ingesta y el esquema de eventos
3. Escribe tu primera consulta SQL en Telemetry
4. Cree su primer panel y alerta
5. Lista de verificación de instrumentación en producción

Obtén tu clave API

Visita la página de inicio para obtener una clave anon_… en el prompt de configuración. Puedes enviar y consultar eventos sin una cuenta. Si ya tienes una, usa una clave read-and-write de Configuración del equipo → Claves API.

Las consultas anónimas funcionan durante 24 horas desde el primer evento. Crea una cuenta en un plazo de 7 días para conservar los eventos y la misma clave. El registro detecta la prueba en este navegador. 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, recupera la clave en Conservar mis datos e inicia sesión. Una prueba sin eventos caduca 7 días después de su creación.

Instalar Telemetry

Este tutorial utiliza JavaScript. También puede utilizar Python, Go, Rust, Ruby, PHP o cURL.

npm install telemetry-sh

Registra algunos datos

Telemetry crea tablas automáticamente cuando se registran datos. En el siguiente ejemplo, registramos datos de recorrido sintéticos en una tabla llamada uber_rides. Telemetry crea la tabla y su esquema con city y price; cada fila también recibe timestamp_utc.

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

telemetry.log("uber_rides", {
  city: "paris",
  price: 42
});

Explora datos con nuestra UI

Primero, consulta el evento sin registrarte:

const result = await telemetry.query("SELECT city, price FROM uber_rides LIMIT 10");
console.log(result);

Para usar gráficos, paneles y alertas, crea una cuenta y conserva tus datos. La clave seguirá funcionando y el registro abrirá el espacio que contiene tus eventos. Si ya tienes una cuenta, vincula tu prueba.

Vista Explorar

Use la pestaña Explorar para filtrar eventos y crear gráficos o tablas sin escribir SQL.

Explorar trabaja con una tabla a la vez. Para abrirla:

1. Abre tu equipo.
2. Abra Tablas.
3. Seleccione una tabla.
4. Abra la pestaña Explorar en la página de esa tabla.

Formato de la ruta:

/team/{team}/table/{table}?tab=explore

1. Elija un tipo de gráfico (Samples, Table, Line, Bar o Stacked Area).
2. Establece un rango de tiempo y agrega uno o más filtros.
3. Elija las columnas que desea incluir (incluidos campos anidados como data.toolName).
4. Haga clic en Ejecutar para ejecutar y generar resultados.

Consejo: los controles están en estado borrador. Los resultados se actualizan solo cuando haces clic en Ejecutar.

Conjunto de datos de ejemplo hipotético (ficticio)

Para los ejemplos de Explorar a continuación, suponga que registró eventos de prueba sintéticos (sin datos de usuario reales) con una estructura como esta:

{
  "timestamp_utc": "2026-02-27T12:00:00.000Z",
  "event": "tool_call",
  "status": "success",
  "data": {
    "toolName": "smart_avantis_buy",
    "args": {
      "symbol": "BTC-USD",
      "amountUsd": 2500
    }
  }
}

Puede registrar esto en una tabla como agent_demo_events y usar esa tabla en Explorar.

/team/{team}/table/agent_demo_events?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy

SELECT "timestamp_utc", "event", "data.toolName", "data.args.symbol"
FROM "your_table"
WHERE timestamp_utc >= now() - INTERVAL '7 days'
ORDER BY timestamp_utc DESC
LIMIT 200

Paneles de control

Los paneles le permiten anclar gráficos/tablas de Explore y consultar resultados en una vista compartida.

Para crear y utilizar paneles:

1. Abra cualquier tabla en Explorar o abra el resultado de una consulta guardada.
2. Haga clic en Agregar al panel.
3. Elija un panel existente o cree uno nuevo primero.
4. Asigne un título al widget y confirme.

Formato de la ruta del panel:

/team/{team}/dashboard/{dashboardSlug}

Utilice paneles para mantener las señales clave en un solo lugar para su equipo (latencia, tasas de error, costos y métricas de conversión).

Crear alertas

Una vez que tenga un gráfico o un resultado de consulta, puede convertirlo en una alerta en la interfaz de usuario Telemetry.

1. Abra una tabla en Exploraro ejecute una consulta en la vistaResultados/Gráfico.
2. Haga clic en Crear alerta.
3. Configure la condición (agregación, últimos N puntos, comparación y umbral).
4. Establezca un intervalo de verificación y uno o más destinatarios de correo electrónico.
5. Haga clic en Crear alerta para guardar. Serás redirigido a /team/{team}/alert/{alertSlug} para monitorear el estado y el historial.

Consejo: deje Ignorar el último punto de datos habilitado para series temporales agrupadas, ya que el segmento más nuevo suele estar incompleto.

Para obtener un tutorial completo, consulte guía de alertas.

Ejemplos interactivos en línea

/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d

Integre con su código base

Puede integrar Telemetry en su producto o paneles de control internos consultando sus datos con SQL a través de la consulta API.

const results =
  await telemetry.query(`
    SELECT
      city,
      AVG(price)
    FROM
      uber_rides
    GROUP BY
      city
  `);

Explore el Biblioteca de recetas SQL cuando esté listo para analizar errores de API, percentiles de latencia, reintentos de trabajo, costo de LLM, conversión, retención o latidos faltantes.

Para conocer la arquitectura y el modelo de análisis detrás de esas recetas, continúe con SQL para observabilidad y análisis de eventos. Para ejecutar un flujo de trabajo sintético completo desde la ingesta hasta un resultado SQL, utilice el Demostración de observabilidad de SaaS de un extremo a otro.