Guía de registro estructurado
El registro estructurado registra un evento como campos con nombre en lugar de colocar cada detalle en una oración. Un mensaje como checkout failed for account 42 after 812 ms es legible, pero SQL tiene que analizarlo antes de poder agrupar fallas o calcular la latencia. Un evento estructurado almacena event_name, account_id, status, error_type y latency_ms por separado.
Comience con una pregunta
Anote la pregunta operativa o de producto antes de elegir campos. "¿Qué paso de pago falla con más frecuencia?" implica un nombre de paso estable, estado, categoría de error y marca de tiempo. "¿Qué clientes se vieron afectados?" También requiere un identificador de cuenta seguro. Un campo sin un uso probable de filtro, grupo, cálculo o depuración probablemente sea ruido.
Prefiera un evento en un límite significativo: una solicitud completada, un trabajo agotó sus reintentos, un webhook fue deduplicado o un usuario alcanzó un hito de activación. Evite emitir una tabla diferente para cada rama del mismo flujo de trabajo. Un campo status consistente hace que el éxito y el fracaso sean comparables.
await telemetry.log("checkout_completed", {
checkout_version: "v2",
account_id: account.id,
status: "failed",
error_type: "payment_declined",
latency_ms: 812,
attempt: 1,
});
Mantener el contrato estable
Utilice nombres snake_case, unidades explícitas como _ms y _bytes, y marcas de tiempo UTC. Almacene categorías como payment_declined, no el texto de excepción completo, cuando desee una dimensión de agrupación confiable. Mantenga los identificadores consistentes en todos los eventos para que una solicitud, cuenta, liberación o trabajo se pueda seguir a través del sistema.
No cambie silenciosamente un campo de un número a una cadena. Si su significado cambia, agregue un campo de versión o un nuevo contrato de evento. El guía de diseño de esquemas de eventos explica el nombre, la propiedad y la evolución con más detalle.
Proteger datos confidenciales
Trate cada campo nuevo como datos que pueden aparecer en el resultado de una consulta, panel o exportación. No envíe credenciales, cookies, encabezados de autorización, cuerpos de solicitud completos, detalles de pago ni solicitudes sin formato. Prefiera identificadores internos y categorías controladas a correos electrónicos y contenido de usuario de formato libre. Aplicar listas permitidas en el límite de construcción del evento; la redacción después de la ingestión es una alternativa, no el control principal.
Verificar el evento
Ejercite ramas de éxito, fracaso, tiempo de espera y reintento con datos sintéticos. Inspeccione la tabla resultante, confirme los tipos de campos y ejecute la consulta que motivó el evento. Luego cree una visualización o alerta solo después de que el resultado coincida con la definición empresarial.
Continúe con guía de gestión de registros estructurados, eventos canónicos amplios, eventos estructurados versus registros de texto, o copie una consulta completa de Biblioteca de recetas SQL.