本文へ移動
Telemetry
データ品質 SQL レシピ

イベントスキーマバージョンの導入を追跡する

プロデューサごとにスキーマ バージョンのロールアウトを測定し、デプロイメント後にアクティブなままになっている古いイベント コントラクトを見つけます。

初心者product_eventsレビュー済み 2026-07-28テスト済み アパッチ DataFusion 45.2.0

レビュー者 Telemetry 製品チーム . SQL の互換性、イベント コントラクト、合成出力、および操作上の注意事項. 基準と所有権を確認する

質問に回答しました

重要なイベントの古いバージョンを依然として出力しているプロデューサーはどれですか?

新しいコードが出荷された時点では、スキーマの移行は完了していません。バージョン分布は、古いワーカー、クライアント、または再試行キューが、ダウンストリームの SQL がサポートする必要があるコントラクトをまだ発行しているかどうかを示します。

イベント契約

クエリが期待するフィールド

フィールド種類なぜ存在するのか
timestamp_utcTimestampイベント受信時間。
event_nameUtf8安定した論理イベント名。
schema_versionUtf8v2 などの明示的な契約バージョン。
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 キーを取得する