イベント追跡計画とガバナンス
イベント追跡計画は、アプリケーション コードとテレメトリを使用する人々の間のレビュー可能な契約です。 1 行の意味、イベントが存在する理由、許可されるフィールド、変更の所有者、およびイベントがどのように検証されるかについて説明します。その契約がなければ、技術的に有効な JSON ペイロードは依然として誤解を招くレート、壊れたファネル、プライバシー リスク、または誰も所有していないダッシュボードを生成する可能性があります。
イベント コントラクトごとに 1 行を使用します。
| フィールド | 例 |
|---|---|
| イベント名 | checkout_completed |
| 穀物 | すべての内部試行後に 1 回の論理チェックアウト |
| 決定 | 端末障害の増加を伴うチェックアウト手順を特定する |
| オーナー | 決済エンジニアリング |
| トリガー | 成功または端末の失敗 |
| 必須フィールド | event_id, status, checkout_step, duration_ms, timestamp_utc |
| オプションのフィールド | account_id, plan, release, error_type |
| 禁止されているコンテンツ | 支払いの詳細、電子メール、リクエスト本文、生のエラー メッセージ |
| 保持 | 製品認定の操作窓口 |
| スキーマのバージョン | 1 |
| 消費者 | チェックアウト信頼性ダッシュボードと端末障害アラート |
| 検証 | 合成の成功、拒否、タイムアウト、再試行、およびフィクスチャの重複 |
フィールドの前に意味を定義する
まずは決断と粒から始めましょう。 「チェックアウトイベント」は曖昧です。 「すべての内部試行後の 1 回の論理チェックアウト」により、レビュー担当者は次のことを知ることができます。 COUNT(*) を表し、再試行で追加の行を作成する必要があるかどうかを示します。
最終的な結果と除外事項を書きます。放棄されたチェックアウトが観察できない場合は、その制限を明記してください。非同期フルフィルメント ステップの前に成功イベントが発行された場合は、それにラベルを付けないでください checkout_completed.
分野ごとに分類する
各フィールドについて、次のことを文書化します。
- 種類と単位
- 必須、オプション、または条件付き必須のステータス
- 許可される値または最大長
- 真実の情報源
- それが個人的なもの、匿名のもの、機密性の高いもの、または無制限のものであるかどうか
- 目的: フィルター、グループ化、結合、計算、相関付け、またはデバッグ
- 値が利用できない場合の動作
管理された分類法を使用して、 status, error_type, feature、およびその他のグループ化ディメンション。高カーディナリティの識別子は、承認された調査または結合で使用される場合にのみ保持します。任意のネストされたペイロードと無制限の文字列を禁止します。
下流の依存関係を記録する
イベントに依存する保存済みのクエリ、ダッシュボード、アラート、エクスポート、実験、レポートを一覧表示します。フィールド名の変更は、それらのコンシューマが更新されるか意図的にバージョン管理されるまで完了しません。
操作クエリごとに、その分母、タイムゾーン、遅延到着ポリシー、再試行処理、最小ボリューム、および予想されるフィクスチャの結果を記録します。計画はクエリまたは関連するものにリンクしている必要があります。 SQL レシピ文書化されていないメトリクス名を再記述しないでください。
契約変更に応じて変更を確認する
通常、追加のオプション フィールドは、既存の意味を変更するより安全です。タイプ、単位、粒度、またはカテゴリの意味が変更された場合は、新しいフィールドまたはスキーマ バージョンを使用します。ロールアウト中:
- 追跡計画を更新し、必要なレビューを取得します。
- 確定的フィクスチャを追加または更新します。
- 下位互換性のあるフィールドを持つプロデューサーをデプロイします。
- スキーマと null レートを検査します。
- 消費者を更新します。
- 互換性ロジックは、履歴ウィンドウと展開ウィンドウで許可された後にのみ削除してください。
すべてのランタイムが準備され、フォールバック計画が文書化されるまでは、新しく導入された構成値を必須にしないでください。
動作ケイデンスの割り当て
重要な計画をスケジュール上およびインシデント後にレビューします。未使用のフィールド、所有されていないダッシュボード、カテゴリの急増、NULL 率の上昇、予期しないスキーマ バージョン、正当な目的を持たなくなった識別子を探します。コストとリスクが生じなくなったデータは削除するか、保存期間を短縮します。
から始めてください イベント追跡計画テンプレート、次に使用します イベントスキーマの設計, 正規のワイドイベント、そして CI でのインストルメンテーション テスト 契約を履行および執行するため。