Solución de problemas de ingesta de eventos

Cuando un evento no aparece donde se esperaba, separe la entrega de la solicitud, la autenticación, la validación de la carga útil, la compatibilidad del esquema y la actualización de la consulta. Una operación exitosa de la aplicación no prueba que la ingesta de telemetría se haya realizado correctamente, y una solicitud HTTP aceptada no prueba que la consulta posterior esté analizando la misma tabla y rango de tiempo.

Utilice un evento sintético con un identificador seguro único durante el diagnóstico. No copie una carga útil de producción en registros, tickets o historial de comandos.

1. Capture el resultado real del HTTP

Envíe temporalmente un evento con cURL para que pueda ver el estado y el cuerpo de la respuesta:

curl -i -X POST https://api.telemetry.sh/log \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "ingestion_diagnostics",
    "data": {
      "event_id": "diagnostic-2026-07-28-01",
      "source": "manual_check",
      "status": "expected"
    }
  }'

Mantenga la clave API en una variable de entorno. No lo pegue en la carga útil ni lo imprima mientras recopila diagnósticos.

Interprete el estado antes de volver a intentarlo:

• 400 significa que el JSON, el nombre de la tabla, la marca de tiempo, la forma de los datos o el tipo de campo deben cambiar. Volver a intentarlo con el mismo cuerpo no lo reparará.
• 401 significa que falta la clave, está mal formada, no es válida o está revocada.
• 403 significa que la clave no tiene alcance de escritura para la operación.
• 429 significa que se superó la tasa o cuota de solicitud actual. Respete Retry-After cuando se suministre y utilice un retroceso exponencial limitado con fluctuación.
• 5xx representa una falla del lado del servidor para una solicitud válida. Vuelva a intentarlo un número limitado de veces sin bloquear la aplicación principal indefinidamente.

Lea Límites de velocidad y errores API para conocer la política de cliente completa.

2. Confirmar la tabla de destino

El Log API normaliza el nombre de la tabla solicitada: los espacios se convierten en guiones bajos y las letras en minúsculas. Después de la normalización, solo son válidos las letras ASCII minúsculas, los números y los guiones bajos.

Por ejemplo, Checkout Events se convierte en checkout_events. Consultar un nombre adivinado como CheckoutEvents no inspeccionará el mismo destino.

Durante el diagnóstico, utilice un nombre explícito simple en la solicitud y luego inspeccione la lista de tablas o el esquema en Telemetry. Si dos servicios deben escribir en una tabla, asegúrese de que ambos utilicen el mismo nombre normalizado y tipos de campo.

3. Validar la forma de datos aceptada.

La propiedad data puede ser:

• un objeto JSON
• una matriz de objetos JSON
• una cadena JSON que decodifica a un objeto
• una matriz que contiene objetos y cadenas JSON que cada una decodifica en objetos

Se rechazan los números de nivel superior, valores booleanos, null y cadenas que decodifican esos valores. Las matrices no pueden contener valores escalares arbitrarios. También se rechazan las cargas útiles profundamente anidadas que superen el límite documentado.

Reduzca un evento fallido a tres campos inofensivos. Vuelva a agregar campos en grupos pequeños hasta que la solicitud vuelva a fallar. Esto aísla la forma no válida sin exponer la carga útil original del cliente.

4. Verifique el comportamiento de la marca de tiempo

Telemetry agrega un UTC timestamp cuando falta o es nulo. Los enteros y las cadenas numéricas de marca de tiempo de Unix se interpretan como segundos de Unix y se normalizan según RFC 3339 cuando están dentro del rango admitido. Se elimina un timestamp_utc proporcionado por el cliente porque ese campo lo administra la capa de consulta.

Si aparece un evento nuevo fuera de la ventana de consulta:

1. eliminar el timestamp personalizado y enviar un nuevo evento sintético
2. consulta por el timestamp_utc generado
3. comparar el reloj de la aplicación, la marca de tiempo de origen y la zona horaria de consulta
4. comprobar si la marca de tiempo original era accidentalmente milisegundos en lugar de segundos

Utilice Trabajar con marcas de tiempo cuando la hora del evento de origen deba conservarse por separado de la hora de recepción.

5. Inspeccionar la compatibilidad del esquema

Los primeros eventos aceptados establecen tipos de campos. Agregar un nuevo campo opcional es diferente a cambiar un campo existente de un número a una cadena, booleano, marca de tiempo u objeto anidado.

Inspeccione el esquema de la tabla y compare la carga útil fallida campo por campo. La deriva común incluye:

• un identificador enviado como un número entero por un productor y una cadena por otro
• una duración enviada como un número en una versión y "842ms" en otra
• un objeto anidado reemplazado por un escalar
• un valor monetario que cambia entre centavos enteros y unidades monetarias decimales
• un tipo de cambio de estado porque un SDK serializa una enumeración de manera diferente

Cuando un concepto realmente cambia de tipo o unidad, agregue un nombre de campo versionado y migre las consultas deliberadamente. Lea Tipos de datos de eventos y valores nulos y Evolución del esquema.

6. Aislar fallas masivas

Para un lote rechazado, reproduzca con un pequeño subconjunto sintético. Si es necesario, divida el lote hasta que se identifique el artículo incompatible. Conserve un event_id estable mientras vuelve a intentar el mismo evento lógico para poder medir la entrega duplicada.

No asigne silenciosamente un nuevo identificador a cada intento de red. Esto convierte un resultado en varias filas y hace que los reintentos de recuperación, los totales de facturación y los embudos no sean confiables. Audite duplicados con el ID de evento duplicado receta SQL.

7. Verificar el evento con SQL

Consulta el identificador de diagnóstico exacto y un generoso rango UTC:

SELECT
  event_id,
  source,
  status,
  timestamp_utc
FROM ingestion_diagnostics
WHERE event_id = 'diagnostic-2026-07-28-01'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC;

Si la fila está presente pero un panel está vacío, compare la tabla, los filtros, el rango de tiempo y los tipos de campos esperados del panel. Si no aparecen filas nuevas de una fuente completa, use el receta de frescura de ingestión para hacer visible el espacio.

Lista de verificación de prevención

• mantenga las claves del lado del servidor fuera de los paquetes del navegador y ajústelas a las operaciones requeridas
• capturar el estado seguro, el punto final, el ID de solicitud y la categoría de error para fallas de ingesta
• use nombres de tablas estables, nombres de eventos, tipos de campos y unidades explícitas
• enviar cambios de esquema a través de una verificación sintética o de preparación antes de la producción
• Limitar los reintentos para que la telemetría no pueda agotar a los trabajadores ni alterar una respuesta completa del cliente.
• monitorear la actualización y duplicar identificadores por separado desde el panel comercial

Consulte Registro API para conocer las reglas de normalización exactas y guía de registro estructurado para un diseño de contrato de evento más seguro.