Telemetry
Data quality SQL recipe

Track Event Schema-Version Adoption

Measure schema-version rollout by producer and find old event contracts that remain active after a deployment.

Beginnerproduct_eventsReviewed 2026-07-28Tested with Apache DataFusion 45.2.0

Question answered

Which producers still emit old versions of a critical event?

A schema migration is not complete when new code ships. Version distribution shows whether old workers, clients, or retry queues are still emitting a contract that downstream SQL must support.

Event contract

Fields the query expects

FieldTypeWhy it exists
timestamp_utcTimestampEvent receive time.
event_nameUtf8Stable logical event name.
schema_versionUtf8Explicit contract version such as v2.
producer_versionUtf8Application build or worker release.
DataFusion SQL

Copy the query

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;

This read-only query is planned and executed against an empty typed table with Apache DataFusion 45.2.0. The deterministic sample output is synthetic and reviewed separately; validate field types, thresholds, and business definitions against your own data. Read the testing methodology.

Query result

Schema-version share by producer

The web deployment has converged on v2, while a worker release still emits a substantial v1 share.

event_nameproducer_versionschema_versioneventsversion_share_pct
checkout_completedweb-1848v29,84099.72
checkout_completedworker-411v174238.11

Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.

How the SQL works

  1. 1The first CTE counts every observed event contract by producer and schema version.
  2. 2Producer totals create the denominator needed to compare high- and low-volume releases fairly.
  3. 3Keeping both versions in the output makes a mixed rollout visible instead of reporting only the newest version.

Edge cases to decide

  • Unversioned historical events need an explicit legacy label rather than a silent NULL.
  • Mobile and desktop clients can have much longer rollout windows than server releases.
  • A version label is useful only when semantic changes are documented alongside it.

Recommended dashboard

  • Bars: version_share_pct by producer_version
  • Trend: legacy version share over deployment time
  • Table: event names with more than one active version

Alert guidance

Alert when a server-side producer keeps emitting a retired contract beyond the migration window; use longer review windows for client releases.

Read alert setup

Put the recipe to work

Related instrumentation and guides

Continue the analysis

Run it on real events

Create a table, adapt the fields, and save the result

Start free, send structured events, and use the query result as a chart, shared dashboard widget, or alert input.

Get an API key