Saltar al contenido
Telemetry
Calidad de datos receta SQL

Seguimiento de la adopción de la versión del esquema del evento

Mida la implementación de la versión del esquema por productor y encuentre contratos de eventos antiguos que permanezcan activos después de una implementación.

Principianteproduct_eventsRevisado 2026-07-28Probado con Apache DataFusion 45.2.0

Revisado por el equipo de producto Telemetry en . Compatibilidad con SQL, contrato de eventos, resultados sintéticos y advertencias operativas. Revisar los estándares y la propiedad

Pregunta respondida

¿Qué productores siguen emitiendo versiones antiguas de un evento crítico?

Una migración de esquema no se completa cuando se envía un código nuevo. La distribución de versiones muestra si los trabajadores, clientes o colas de reintento antiguos todavía emiten un contrato que el SQL posterior debe admitir.

Contrato de evento

Campos que espera la consulta

CampoTipoPor que existe
timestamp_utcTimestampHora de recepción del evento.
event_nameUtf8Nombre de evento lógico estable.
schema_versionUtf8Versión de contrato explícita como v2.
producer_versionUtf8Creación de aplicaciones o lanzamiento de trabajadores.
DataFusionSQL

Copiar la consulta

sql
WITH version_counts AS (
  SELECT
    event_name,
    producer_version,
    schema_version,
    COUNT(*) AS events
  FROM product_events
  WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  GROUP BY event_name, producer_version, schema_version
),
producer_totals AS (
  SELECT
    event_name,
    producer_version,
    SUM(events) AS producer_events
  FROM version_counts
  GROUP BY event_name, producer_version
)
SELECT
  counts.event_name,
  counts.producer_version,
  counts.schema_version,
  counts.events,
  100.0 * counts.events / NULLIF(totals.producer_events, 0)
    AS version_share_pct
FROM version_counts AS counts
JOIN producer_totals AS totals
  ON totals.event_name = counts.event_name
  AND totals.producer_version = counts.producer_version
ORDER BY counts.event_name, counts.producer_version, counts.events DESC;

Esta consulta de solo lectura se planifica y ejecuta en una tabla escrita vacía con Apache DataFusion 45.2.0. El resultado de la muestra determinista es sintético y se revisa por separado; valide tipos de campos, umbrales y definiciones comerciales con sus propios datos. Lea la metodología de prueba.

Resultado de la consulta

Cuota de versión de esquema por productor

La implementación web ha convergido en la versión 2, mientras que una versión de trabajo todavía emite una parte sustancial de la versión 1.

event_nameproducer_versionschema_versioneventsversion_share_pct
checkout_completedweb-1848v2984099,72
checkout_completedworker-411v174238,11

Salida de ejemplo sintético. Ejecute la consulta con su propio esquema de eventos y umbrales antes de utilizarla para decisiones operativas.

Schema-version share by producer: gráfico estático de valores sintéticos de version_share_pct del resultado del ejemplo Track Event Schema-Version Adoption
SVG indexable de la salida del ejemplo determinista. Descárguelo para ver un artículo, un runbook o una revisión de diseño con atribución.

Reproducir el ejemplo

Descargar el accesorio público

El paquete JSON incluye el contrato de evento escrito, illustrative filas de entrada, SQL exacto, resultado esperado, notas de revisión y versión del motor. El CSV contiene el resultado mostrado.

Cómo funciona el SQL

  1. 1El primer CTE cuenta cada contrato de evento observado por productor y versión de esquema.
  2. 2Los totales de los productores crean el denominador necesario para comparar de manera justa las emisiones de alto y bajo volumen.
  3. 3Mantener ambas versiones en el resultado hace visible una implementación mixta en lugar de informar solo la versión más reciente.

Casos extremos para decidir

  • Los eventos históricos no versionados necesitan una etiqueta heredada explícita en lugar de un NULL silencioso.
  • Los clientes móviles y de escritorio pueden tener ventanas de implementación mucho más largas que las versiones de servidor.
  • Una etiqueta de versión es útil sólo cuando se documentan cambios semánticos junto a ella.

Panel recomendado

  • Barras: version_share_pct por producer_version
  • Tendencia: participación de la versión heredada durante el tiempo de implementación
  • Tabla: nombres de eventos con más de una versión activa

Guía de alerta

Alerta cuando un productor del lado del servidor sigue emitiendo un contrato retirado más allá de la ventana de migración; Utilice ventanas de revisión más largas para los lanzamientos de clientes.

Leer configuración de alerta

Pon la receta a trabajar

Instrumentación y guías relacionadas.

Continuar el análisis

Ejecútelo en eventos reales.

Crea una tabla, adapta los campos y guarda el resultado.

Comience gratis, envíe eventos estructurados y utilice el resultado de la consulta como un gráfico, un widget de panel compartido o una entrada de alerta.

Obtén una clave API