跳转到内容
Telemetry
数据质量 SQL查询示例

跟踪事件架构版本采用情况

衡量生产者的模式版本部署,并查找部署后仍保持活动状态的旧事件合约。

入门product_events已审核 2026-07-28测试用 阿帕奇 DataFusion 45.2.0

审阅者 Telemetry产品团队 . SQL 兼容性、事件契约、合成输出和操作注意事项. 审查标准和所有权

问题已回答

哪些生产者仍然发布关键事件的旧版本?

当新代码发布时,架构迁移尚未完成。版本分布显示旧的工作线程、客户端或重试队列是否仍在发出下游 SQL 必须支持的协定。

活动合约

查询期望的字段

字段类型为什么存在
timestamp_utcTimestamp事件接收时间。
event_nameUtf8稳定的逻辑事件名称。
schema_versionUtf8显式合约版本,例如 v2。
producer_versionUtf8应用程序构建或工作人员发布。
DataFusion SQL

复制查询

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;

此只读查询是针对空类型表计划和执行的 阿帕奇 DataFusion 45.2.0。确定性样本输出是综合的并单独审查;根据您自己的数据验证字段类型、阈值和业务定义。 阅读测试方法。

查询结果

生产者的架构版本共享

Web 部署已收敛于 v2,而工作版本仍占据大量 v1 份额。

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

综合示例输出。在将其用于操作决策之前,针对您自己的事件架构和阈值运行查询。

Schema-version share by producer:来自 Track Event Schema-Version Adoption 示例结果的合成 version_share_pct 值的静态图表
确定性示例输出的可索引 SVG。下载它以获取带有归属的文章、操作手册或设计评论。

重现示例

下载公共装置

JSON 包包含类型化事件契约, illustrative 输入行、确切的 SQL、预期输出、审阅注释和引擎版本。 CSV 包含显示的结果。

SQL 是如何工作的

  1. 1第一个 CTE 按生产者和模式版本对每个观察到的事件合约进行计数。
  2. 2生产者总数创建了公平比较高容量和低容量版本所需的分母。
  3. 3在输出中保留两个版本可以使混合部署可见,而不是仅报告最新版本。

需要决定的边缘情况

  • 无版本化的历史事件需要显式的遗留标签,而不是静默的 NULL。
  • 移动和桌面客户端的推出窗口可能比服务器版本更长。
  • 仅当语义更改与版本标签一起记录时,版本标签才有用。

推荐仪表板

  • 酒吧:version_share_pct by producer_version
  • 趋势:旧版本在部署时间内的份额
  • 表:具有多个活动版本的事件名称

警报指导

当服务器端生产者在迁移窗口之外不断发出退休合约时发出警报;对客户端版本使用更长的审查窗口。

读取警报设置

让查询示例发挥作用

相关埋点和指南

继续分析

在真实事件中运行它

创建表,调整字段并保存结果

免费开始,发送结构化事件,并将查询结果用作图表、共享仪表板小部件或警报输入。

获取 API 密钥