跳至主要內容
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 金鑰