measure-instrumentation-spec

計測仕様

計測仕様では、追跡する分析イベント、その発火タイミング、含めるプロパティを定義します。プロダクトチームとエンジニアリングチームの間の契約として機能し、一貫したデータ収集を実現して、正確な測定を可能にします。優れた計測仕様があれば、「追跡していなかったため、その質問に答えられない」という問題を防げます。

使用する場面

• エンジニアリングチームが新機能の実装を始める前
• 実験の分析要件を定義するとき
• 既存のトラッキングを監査して、抜けや不整合を確認するとき
• 新しい分析ツールを導入するとき
• 測定の準備が整っていることを確認するため、ローンチ前に

使用しない場面

• イベントに基づいて構築するダッシュボードを仕様化する場合 → measure-dashboard-requirements を使用してください
• プロダクト全体のトラッキングではなく、実験固有の指標やバリアントが必要な場合 → measure-experiment-design を使用してください
• 機能自体がまだ仕様化されておらず、計測対象となるフローがない場合 → 先に deliver-prd を使用してください
• すでに収集しているデータを分析する場合 → measure-experiment-results または measure-survey-analysis を使用してください

手順

計測仕様の作成を依頼された場合は、次の手順に従ってください。

1. 分析目標を定義する まず、答える必要がある質問から始めます。何を測定しますか？このデータはどのような意思決定に役立ちますか？これにより、過剰な計測を防ぎつつ、重要な項目の見落としを防げます。

2. 追跡するイベントを特定する 追跡すべきユーザー操作またはシステムイベントをそれぞれ列挙します。一貫した命名規則（通常は noun_verb または verb_noun の snake_case）に従います。各イベントは、個別の意味のある操作を表す必要があります。

3. イベントの発火条件を指定する 各イベントについて、いつ発火するかを正確に記述します。「ユーザーが送信ボタンをクリックしたとき」と「フォームの送信が正常に完了したとき」では、意味の異なる別のイベントです。具体的に記述してください。

4. イベントプロパティを定義する 各イベントに付与するプロパティ（属性）を列挙します。プロパティ名、データ型、説明、値の例を含めます。プロパティによってイベントに有用なコンテキストが加わります。

5. ユーザープロパティを文書化する すべてのイベントに関連付けるべき、ユーザーレベルの永続的な属性（例：サブスクリプションのティア、アカウント作成日）を特定します。これにより、分析時のセグメンテーションが可能になります。

6. PII とプライバシーに対処する 個人を特定できる情報を含むプロパティに印を付けます。PII の取り扱い方法（ハッシュ化、暗号化、または除外）を文書化します。

   モデルへの入力、モデルからの出力、検索コンテキスト、またはツール呼び出しのいずれかを取得する場合は、このセクションの対象にトレースも含めます。トリガーとなるのは作成者ではなく取得です。つまり、機密テキストがユーザーによって入力された場合、テナントの文書から取得された場合、システムプロンプトに含まれていた場合、ツールに渡された場合やツールから返された場合、アップロードファイルやバッチジョブから読み取られた場合、あるいはモデル自体によって生成された場合でも発火します。ユーザーからの直接入力がない機能でも、顧客の契約書のテキストをトレースストアに書き込むことがあります。

   トレースはイベントではありません。イベントには事前に選択したプロパティが含まれる一方、トレースには自由記述のテキストが含まれ、プロパティのスキーマで想定していなかったデータも含まれる可能性があります。次の項目を決定し、記録してください。

   • 取得するデータクラス。 データクラス（ユーザーテキスト、検索で取得した文書、システムプロンプト、ツールの引数と結果、ファイルの内容、モデル出力）を明記します。「トレース」だけでは回答になりません。
   • 両方の境界での最小化。 トレースがプロセスの外に出る前に削除またはマスキングするデータと、保存前に別途削除するデータを明記します。ストレージ層でしか動作しないレダクターでは、生のテキストはすでにネットワーク経由で送信されています。
   • アクセス。 誰がトレースを読めるのか、また、読み取りがログに記録されるのかを明記します。トレースストアは、機能が扱う最も機密性の高いデータのコピーのうち、最もガバナンスが不十分なものになりがちです。
   • 保持と削除。 保持期間、削除の契機、評価セットにコピーされたトレースに削除リクエストをどのように反映するかを明記します。
   • 同意とオプトアウト。 対象者が同意したかどうか、また、同意しない場合に機能がどのように動作するかを明記します。
   • サンプリング。 取得する割合と、そのサンプルの選び方を明記します。一様なサンプリングは、まれな失敗を見つけるには不適切です。出力の不具合を診断するためにトレースを取得する場合は、フラグが付いたケースを多めにサンプリングし、そのことを明記してください。

7. テストチェックリストを作成する 計測が正しく実装されていることを QA がどのように検証すべきかを定義します。イベントが適切なタイミングで、正しいプロパティとともに発火することを検証する手順を含めます。

出力形式

出力の構成には references/TEMPLATE.md のテンプレートを使用してください。完全な仕様では、テンプレートのすべてのセクション（Overview、Event Inventory、User Properties、PII & Privacy Considerations、Implementation Notes、Testing Checklist）を埋めてください。

品質チェックリスト

最終確定する前に、以下を確認します。

• イベント名が一貫した命名規則に従っている
• 各イベントのトリガーが明確で曖昧さがない
• プロパティにデータ型と値の例が含まれている
• 個人を特定できる情報が特定され、その取り扱いが文書化されている
• イベントが、回答する必要のある分析上の問いに対応している
• テスト用チェックリストで QA の検証が可能である
• モデルへの入力、出力、検索コンテキスト、またはツール呼び出しを記録する場合、データクラスが明示され、エグレス境界とストレージ境界の両方でデータの最小化が決定され、アクセスと読み取りログ、保持と削除、同意、サンプリングについても、先送りせずすべて決定されている

例

完成例については、references/EXAMPLE.md を参照してください。