Plan de seguimiento de eventos y gobernanza
Un plan de eventos explica qué significa una fila, por qué se recopila, qué campos están permitidos, quién se encarga de los cambios y cómo se prueba. Escríbalo antes de agregar instrumentación. Un JSON válido aún puede generar una tasa de conversión incorrecta o exponer datos privados en un panel compartido.
Utilice una fila por contrato de evento:
| campo | Ejemplo |
|---|---|
| Nombre del evento | checkout_completed |
| grano | Un pago lógico después de todos los intentos internos |
| decisión | Identificar los pasos de pago con falla terminal elevada |
| propietario | Ingeniería de pagos |
| gatillo | Éxito o fracaso terminal |
| Campos obligatorios | event_id, status, checkout_step, duration_ms, timestamp_utc |
| Campos opcionales | account_id, plan, release, error_type |
| Contenido prohibido | Detalles de pago, correo electrónico, cuerpo de la solicitud, mensaje de error sin formato |
| Retención | Ventana operativa aprobada por el producto |
| Versión del esquema | 1 |
| Consumidores | Panel de confiabilidad de pago y alerta de falla de terminal |
| Validación | Éxito sintético, rechazo, tiempo de espera, reintento y partidos duplicados |
Definir significado antes de los campos
Comience con la decisión y el grano. El "evento de pago" es ambiguo. "Una verificación lógica después de todos los intentos internos" le dice a un revisor qué representa COUNT(*) y si los reintentos deberían crear filas adicionales.
Escriba los resultados terminales y las exclusiones. Si no se pueden observar los pagos abandonados, indique esa limitación. Si se emite un evento de éxito antes de un paso de cumplimiento asincrónico, no lo etiquete como checkout_completed.
Clasificar cada campo
Para cada campo, documente:
- tipo y unidad
- estado requerido, opcional o condicionalmente requerido
- valores permitidos o longitud máxima
- fuente de verdad
- ya sea personal, seudónimo, sensible o sin restricciones
- Propósito: filtrar, agrupar, unir, calcular, correlacionar o depurar
- comportamiento cuando el valor no está disponible
Utilice taxonomías controladas para status, error_type, feature y otras dimensiones agrupadas. Mantenga identificadores de alta cardinalidad solo cuando una investigación o unión aprobada los utilice. Prohibir cargas útiles anidadas arbitrarias y cadenas ilimitadas.
Registrar dependencias posteriores
Enumere consultas guardadas, paneles, alertas, exportaciones, experimentos e informes que dependen del evento. Un cambio de nombre de campo no está completo hasta que esos consumidores se actualicen o versionen deliberadamente.
Para cada consulta operativa, registre su denominador, zona horaria, política de llegada tardía, tratamiento de reintento, volumen mínimo y resultado esperado del acuerdo. El plan debe vincularse a la consulta o al Receta SQL relevante, no reformular un nombre de métrica no documentado.
Revisar los cambios a medida que cambia el contrato.
Los campos opcionales adicionales suelen ser más seguros que cambiar el significado existente. Utilice una nueva versión de campo o esquema cuando cambie el significado de un tipo, unidad, grano o categoría. Durante el lanzamiento:
- Actualizar el plan de seguimiento y obtener la revisión requerida.
- Agregue o actualice accesorios deterministas.
- Implemente productores con campos compatibles con versiones anteriores.
- Inspeccionar esquema y tarifas nulas.
- Actualizar a los consumidores.
- Elimine la lógica de compatibilidad solo después de que las ventanas histórica y de implementación lo permitan.
Nunca haga obligatorio un valor de configuración recién introducido hasta que cada tiempo de ejecución esté preparado y se documente un plan alternativo.
Asignar una cadencia operativa
Revisar los planes críticos en un cronograma y después de incidentes. Busque campos no utilizados, paneles sin propietario, explosión de categorías, tasas de nulos en aumento, versiones de esquema inesperadas e identificadores que ya no tienen un propósito justificado. Elimine o acorte la retención de datos que ya no generen su costo y riesgo.
Comience con Plantilla de plan de seguimiento de eventos, luego use Diseñar un esquema de evento, Eventos amplios canónicos y Pruebas de instrumentación en CI para implementar y hacer cumplir el contrato.