Telemetría de aplicaciones: guía práctica

La telemetría de aplicación es la evidencia estructurada que produce el software sobre lo que sucedió, para quién, cuánto tiempo tomó y si el resultado fue útil. Una buena telemetría permite que productos, ingeniería, soporte y operaciones respondan una pregunta del mismo contrato de evento en lugar de reconstruir la realidad a partir de texto ilimitado.

Esta guía muestra cómo elegir la señal correcta, diseñar eventos de resultados seguros, entregarlos, validarlos con SQL y convertirlos en paneles y alertas.

Qué incluye la telemetría de aplicaciones

Los registros, métricas, seguimientos y eventos estructurados se superponen, pero cada uno tiene un centro de gravedad útil:

No fuerces que una señal reemplace a todas las demás. Un evento de terminal api_request_completed puede contener la ruta, la cuenta, el estado, la duración y la liberación necesarios para un panel de tasa de errores. Un rastro puede explicar qué dependencia consumió esa duración. Un registro de diagnóstico puede conservar un mensaje técnico revisado. Una métrica de infraestructura puede mostrar si el servicio tenía recursos limitados.

Los identificadores compartidos entre esas señales suelen ser más valiosos que duplicar sus cargas útiles completas.

Comience con una decisión

La instrumentación debe comenzar con una pregunta y una acción:

• Pregunta: ¿Qué rutas API fallan en la mayoría de las cuentas después de un lanzamiento?
• Decisión: revertir, deshabilitar una función o investigar una dependencia.
• Evento: api_request_completed.
• Grano: Una solicitud completa.
• Dimensiones: plantilla de ruta, método, código de estado, categoría de error, versión.
• Medidas: latencia en milisegundos.
• Correlación segura: identificadores de solicitud y cuenta.

Si un campo no será utilizado por un filtro, grupo, cálculo, unión, investigación o política conocida, omítalo. "Podría ser útil más adelante" genera costos, riesgos para la privacidad y esquemas inestables sin garantizar una respuesta útil.

Diseñar un contrato de evento

Un evento de solicitud de terminal podría verse así:

{
  "event_id": "evt_api_01",
  "request_id": "req_2f71",
  "account_id": "acct_8f31",
  "route": "/v1/query/:id",
  "method": "POST",
  "status_code": 200,
  "latency_ms": 184,
  "error_type": null,
  "release": "2026.07.3"
}

El contrato debe indicar:

Utilice plantillas de ruta como /v1/query/:id, no URL sin formato que convierten cada identificador en una nueva dimensión. Utilice un error_type limitado, no un seguimiento de pila. Mantenga las medidas numéricas numéricas y los identificadores estables escritos en cadenas.

Emitir en el límite del resultado

Registre un resultado sólo cuando se conozca. Para una solicitud HTTP, esto suele ocurrir después de que el estado final y la duración estén disponibles:

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

async function recordRequest(context, response, startedAtMs) {
  await telemetry.log("api_request_completed", {
    event_id: crypto.randomUUID(),
    request_id: context.requestId,
    account_id: context.accountId,
    route: context.routeTemplate,
    method: context.method,
    status_code: response.status,
    latency_ms: Date.now() - startedAtMs,
    error_type: response.error
      ? classifyRequestError(response.error)
      : null,
    release: process.env.APP_RELEASE ?? "unknown"
  });
}

Telemetry elimina valores nulos durante la normalización, por lo que una fila exitosa no almacena ningún error_type. La capa de consulta proporciona timestamp_utc; se elimina un campo proporcionado por el cliente con ese nombre. Consulte Registro API para conocer las formas exactas aceptadas y las reglas de normalización.

No permita que una falla en la entrega de telemetría cambie un resultado comercial completado en un pago, correo electrónico, trabajo o solicitud duplicados. Decida si almacenar en búfer, reintentar, muestrear o descartar según el riesgo del flujo de trabajo. Reutilice el mismo event_id cuando vuelva a intentar la entrega del mismo evento lógico.

Elija identificadores para la correlación

Utilice identificadores que coincidan con la entidad que se investiga:

• event_id deduplica un evento de telemetría;
• request_id vincula la evidencia de la solicitud para una solicitud;
• job_id conecta eventos del ciclo de vida y reintentos;
• account_id mide el impacto en el cliente;
• user_id admite el análisis de productos a nivel de actor cuando se aprueba;
• trace_id se vincula a un seguimiento distribuido.

Mantenga los identificadores como seudónimos. Una dirección de correo electrónico, un token de acceso, una cookie de sesión, un mensaje, un documento o una URL completa no son un identificador conveniente; Son datos confidenciales de carga útil.

Controlar la cardinalidad y el tamaño de la carga útil

La cardinalidad es el número de valores distintos que produce un campo. Los ID de alta cardinalidad son útiles para la investigación y las uniones, pero los grupos de panel predeterminados son deficientes. El texto ilimitado rara vez es una dimensión analítica segura.

Uso:

• route: "/v1/query/:id" en lugar de /v1/query/9be1...;
• error_type: "upstream_timeout" en lugar del mensaje de excepción;
• un identificador de modelo de proveedor aprobado en lugar de una etiqueta de visualización ad hoc;
• release: "2026.07.3" en lugar de un manifiesto de implementación completo.

Grupo en campos acotados. Seleccione identificadores solo en resultados de investigación restringidos. Omita los cuerpos de solicitud y respuesta en lugar de intentar redactar todos los valores confidenciales posibles después de la ingesta.

Mantenga estables los tipos y significados

La flexibilidad de eventos no es motivo para enviar tipos mixtos. latency_ms no debe alternar entre 184, "184 ms" y "slow". account_id no debe hacer referencia a un usuario en un servicio ni a una organización en otro.

Los campos opcionales adicionales suelen ser la evolución más segura. Un cambio de nombre, cambio de unidad, cambio de tipo o nuevo grano de fila necesita una migración o una nueva versión del evento. Siga el guía de evolución del esquema y mida la adopción de campo por versión antes de cambiar un panel o una alerta.

Los objetos anidados pueden crear espacios de nombres útiles, pero cada ruta de puntos sigue siendo un contrato. Ver consultando JSON anidado.

Separe el tiempo del evento y el tiempo de ingesta

Defina cuándo ocurrió el resultado del negocio o de la aplicación. Los clientes móviles retrasados, las colas, los agentes fuera de línea y los buffers de reintento pueden entregarse más tarde de ese momento.

Para eventos en línea generados por el servidor, el timestamp_utc administrado de Telemetry suele ser el momento de consulta operativa correcto. Si su flujo de trabajo necesita una hora de evento de origen, envíe una marca de tiempo calificada para zona horaria con nombre separado y documente cómo las llegadas tardías afectan los informes. No compare depósitos actuales parciales con depósitos históricos completos.

El guía para trabajar con marcas de tiempo cubre UTC, ventanas y datos que llegan tarde.

Consulta la primera pregunta útil.

Comience con una muestra acotada:

SELECT
  timestamp_utc,
  route,
  status_code,
  latency_ms,
  release
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '1 hour'
ORDER BY timestamp_utc DESC
LIMIT 100;

Luego calcule el volumen, la tasa de error, las cuentas afectadas y la latencia final:

SELECT
  route,
  COUNT(*) AS requests,
  SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
  COUNT(DISTINCT CASE
    WHEN status_code >= 500 THEN account_id
  END) AS affected_accounts,
  100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS error_rate_pct,
  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route
HAVING COUNT(*) >= 20
ORDER BY affected_accounts DESC, error_rate_pct DESC;

La regla del volumen mínimo evita que una sola falla silenciosa supere automáticamente a una regresión ocupada. Un flujo de trabajo crítico de bajo volumen puede necesitar su propia alerta en lugar de una tabla de clasificación genérica.

Cree un panel listo para tomar decisiones

Un panel de confiabilidad de la aplicación debería permitir al lector pasar de la detección al alcance y la evidencia:

1. volumen de solicitudes o flujo de trabajo;
2. tasa de éxito o error en períodos de tiempo completos;
3. latencia p50 y p95;
4. cuentas afectadas;
5. desglose por ruta, categoría de error y versión;
6. una tabla restringida con ID de solicitud para investigación.

Anote unidades, rango de tiempo, denominador, volumen mínimo, actualidad de los datos y contrato del evento. Mantenga un resultado sintético o un elemento conocido junto al SQL importante para que un revisor pueda saber qué se pretende devolver con la consulta.

Utilice Ejemplo de panel de confiabilidad API y Receta de latencia API como puntos de partida completos.

Alerta solo cuando un propietario puede responder

Una definición de alerta necesita la consulta, el denominador exacto, la ventana de tiempo completa, el umbral o línea de base, el volumen mínimo, el equipo propietario, el runbook, el primer desglose del diagnóstico y el comportamiento de los datos faltantes.

Por ejemplo: notificar al propietario de API cuando la latencia p95 exceda el objetivo de ruta para tres depósitos completos y se observaron al menos 100 solicitudes. La respuesta comienza comparando la versión, la categoría de error y el recuento de cuentas afectadas.

Supervise el canal de telemetría en sí. Un cero plano puede significar una aplicación silenciosa, un productor roto, un error de entrega o un error de consulta. Los modelos esquema de evento de entrega de telemetría y receta de frescura de ingestión hacen visible la evidencia faltante.

Proteger la privacidad y la seguridad

Reunir las pruebas mínimas requeridas para la decisión. Antes del lanzamiento:

• clasificar cada identificador y campo de texto libre;
• eliminar secretos, credenciales, cookies, cuerpos de solicitud, mensajes y contenido generado;
• utilizar identificaciones internas seudónimas;
• restringir las vistas de investigación que exponen identificadores de actores o recursos;
• establecer la retención a partir de una necesidad operativa o de producto documentada;
• probar la redacción y las ramas fallidas, no solo las solicitudes exitosas;
• revisar los requisitos de eliminación y acceso para la jurisdicción y el uso de los datos.

Lea redactar datos confidenciales y descripción general de seguridad antes de ampliar la carga útil.

Validar todo el camino

Una prueba unitaria de productor es necesaria pero no suficiente. Validar:

1. las ramas de éxito, fracaso, tiempo de espera, reintento y duplicación;
2. nombres de campos, tipos, unidades y valores controlados;
3. Aceptación de API y manejo de errores;
4. una fila sin formato reciente en la tabla de destino;
5. el agregado SQL contra un accesorio conocido;
6. la ventana de tiempo y el denominador del tablero;
7. el umbral de la alerta, el propietario y el comportamiento de datos faltantes;
8. la ruta de reversión con la versión anterior del productor.

Realice un seguimiento de la cobertura de campo y el volumen de eventos por lanzamiento después de la implementación. Una ruta de código existente en el código fuente no prueba que la producción esté emitiendo eventos completos.

Controle el coste sin perder el resultado

Estimar el volumen antes del lanzamiento generalizado:

events per day
  = requests per day
  × events per request
  × retained sample fraction

Prefiera un evento de resultado terminal a varios eventos de progreso redundantes cuando no se utilizan los estados intermedios. Muestre diagnósticos exitosos de gran volumen solo después de preservar el denominador necesario para las tasas. Mantenga las fallas y los resultados críticos poco comunes cuando la política lo permita, pero no utilice el muestreo como sustituto de la eliminación de datos confidenciales.

Alinear la retención con la ventana de comparación o investigación más larga que tenga un propietario documentado. Un campo o evento que nadie consulta debe eliminarse del plan antes de que se convierta en un costo permanente.

Lista de verificación de implementación de telemetría de aplicaciones

1. Escriba la pregunta, la decisión, el propietario y la respuesta esperada.
2. Defina la veta de una fila y el límite exacto del resultado.
3. Elija campos obligatorios, valores controlados, unidades e identificadores seguros.
4. Clasifique privacidad, cardinalidad, retención y volumen.
5. Agregue accesorios representativos de éxito, fracaso, reintento, duplicación y reversión.
6. Entrega de instrumentos sin cambiar la semántica de las operaciones comerciales.
7. Verifique las filas aceptadas y la cobertura de los campos obligatorios por versión.
8. Pruebe SQL con un resultado conocido.
9. Publique la definición, la actualización y el denominador del panel.
10. Agregue una alerta solo cuando el propietario y la respuesta sean claros.
11. Supervise el canal de telemetría en sí.
12. Revise los campos después de la primera ventana de retención y elimine los datos no utilizados.

Continúe con diseñar un esquema de evento, registro estructurado, catálogo de esquemas de eventos y Demostración de observabilidad de SaaS de un extremo a otro.