Diseñar un esquema de evento
Un esquema de evento es un contrato entre el código que emite datos y cada consulta, panel, alerta o exportación que los consume. Una pequeña cantidad de diseño antes de la instrumentación evita meses de datos ambiguos.
Nombra el resultado
Utilice un sustantivo estable y un resultado en tiempo pasado, como api_request_completed, job_failed o subscription_renewed. Evite la redacción de la interfaz de usuario que cambia con frecuencia. Cuando el éxito y el fracaso comparten los mismos campos útiles, un evento con un valor status controlado suele ser más fácil de comparar que tablas separadas.
Elija campos de preguntas
Para cada pregunta planificada, identifique la operación:
- Los filtros necesitan campos como entorno, característica, ruta o estado.
- Los grupos necesitan dimensiones controladas, como modelo, versión o tipo de error.
- Los cálculos necesitan medidas escritas con unidades explícitas.
- Las investigaciones necesitan identificadores seguros que conecten eventos relacionados.
Registre latency_ms, no latency. Almacene valores numéricos como números y booleanos como booleanos. Utilice marcas de tiempo UTC. Prefiera route_template a una URL sin formato y error_type a un mensaje de excepción ilimitado.
Documente si un identificador representa una persona, cuenta, solicitud o trabajo. Si un campo puede contener datos confidenciales, omítalo o transfórmelo antes de que se cree el evento.
Planificar el cambio
Los cambios adicionales suelen ser los más seguros: una consulta puede tolerar un nuevo campo que acepte valores NULL. Cambiar el nombre de un campo o cambiar su tipo puede arruinar a todos los consumidores. Cuando la semántica cambie materialmente, agregue un event_version, escriba consultas que manejen la ventana de migración y elimine la forma anterior solo después de que los consumidores se muden.
Mantenga una muestra representativa de éxito, fracaso, reintento y tiempo de espera para su validación. Ejecute el importante SQL antes de realizar un cambio de instrumentación. Un esquema está completo sólo cuando los valores producidos por las ramas reales coinciden con su significado documentado.
Revisar la lista de verificación
Pregunte si el evento tiene un propietario claro, un conjunto acotado de valores de estado, unidades explícitas, identificadores seguros y una necesidad de retención. Confirme que al menos una consulta real utilice cada campo. Elimine los valores incluidos simplemente porque están disponibles.
Consulte evolución del esquema, redactar datos confidenciales y Recetas SQL para obtener ejemplos completos de contratos de eventos.