Registro de eventos

El registro API es la forma de incorporar eventos en Telemetry. Úselo para eventos de aplicaciones, actividad de usuarios, métricas o registros estructurados.

Telemetry normaliza los nombres de las tablas, completa las marcas de tiempo y elimina valores nulos, objetos vacíos y matrices vacías antes de almacenar los datos.

ENVÍO https://api.telemetry.sh/log

Encabezados

Cuerpo

Formas de datos aceptadas

El API acepta:

• un único objeto JSON
• una matriz de objetos JSON
• una cadena JSON que a su vez se analiza en un objeto JSON
• una matriz que contiene objetos JSON y cadenas JSON que se analizan en objetos JSON

El API rechaza:

• números de nivel superior, booleanos y null
• Cadenas JSON que decodifican en valores que no son de objeto, como matrices, números, valores booleanos o null
• matrices que contienen elementos que no son objetos ni cadenas
• matrices que contienen cadenas JSON que decodifican en valores que no son de objeto
• Cargas útiles JSON anidadas a más de 64 niveles
• lotes de eventos vacíos, data: []

Normalización del lado del servidor

Cuando data contiene objetos JSON, Telemetry aplica estas reglas antes de la ingesta:

• agrega timestamp con la hora UTC actual si falta
• si timestamp es null, lo reemplaza con la hora UTC actual
• si timestamp es un entero de marca de tiempo de Unix o una cadena numérica, lo interpreta como segundos de Unix y lo convierte a RFC 3339.
• elimina timestamp_utc si está presente
• elimina de forma recursiva los valores null, los objetos vacíos y los arrays vacíos. Conserva "", 0 y false.

Ejemplos:

• Telemetry Events se convierte en telemetry_events
• timestamp: 1700000000 se convierte en una cadena de marca de tiempo RFC 3339
• { "user": "alice", "meta": null } se almacena sin meta

Ejemplo de uso con cURL

Para enviar datos de viajes de Uber a una tabla llamada uber_rides usando cURL, puede usar el siguiente comando:

curl -X POST https://api.telemetry.sh/log \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "uber_rides",
    "data": {
      "city": "paris",
      "price": 42
    }
  }'

Usando el JavaScript SDK

Recomendamos utilizar nuestros SDK para una mejor experiencia de desarrollador. A continuación se muestra un ejemplo de cómo utilizar nuestro JavaScript SDK:

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

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

Registro masivo

También puede pasar una serie de objetos para ingerir eventos de forma masiva. Esto es útil para limitar la cantidad de solicitudes al API. Por ejemplo, en lugar de:

telemetry.log("uber_rides", { a: 1 })

Puedes hacer:

telemetry.log("uber_rides", [{a: 1}, {a: 2}])

Esto ingerirá los datos como dos filas.

Errores comunes

• 400 Bad Request si el cuerpo JSON no es válido
• 400 Bad Request si el nombre de la tabla contiene caracteres no válidos después de la normalización
• 400 Bad Request si data no está en una forma compatible
• 400 Bad Request con el código empty_batch si data es un arreglo vacío. Envía al menos un evento. Reducir el tamaño de la carga no resuelve este error.
• 400 Bad Request si una cadena JSON en data se decodifica en un valor que no es de objeto
• 400 Bad Request si una marca de tiempo de Unix está fuera del rango admitido
• 401 Unauthorized si la clave API falta o no es válida
• 429 Too Many Requests si la clave API excede el límite de velocidad de la puerta de enlace