software-instrumentation

ソフトウェアのインストルメンテーション

ソフトウェアの動作を可観測にするためにインストルメンテーションを行う際は、いつでもこの機能を使用してください。テレメトリー（ログ、エラー、トレース、プロダクトイベント）を出力するコードや、それらのシグナルの送信先となるツールを設定するコードを追加またはレビューします。適切なインストルメンテーションを行うことで、本番環境のインシデントは推測ではなく、検索で解決できるようになります。

このガイダンスは、意図的にツールに依存しない内容になっています。特定の SDK ではなく、構造化ロガー、エラートラッカー（エラー報告サービス）、アナリティクスツールといった役割を挙げており、コード例では logger.info(...)、reportError(...)、trackEvent(...) のようなプレースホルダー関数名を使っています。これらは、プロジェクトで採用しているものに対応させてください。ルールを適用する際は、具体的な名前に置き換え、形は保ってください。

ベンダー固有の機能が必要になるのは、この置き換えの部分です。どのパッケージに依存するか、何が収集されるかをどのオプションで制御するか、ソースマップをサービスにどう送るか、ビルド時のトークンがどこに現れるかはベンダーごとの事情であり、このスキルでは意図的に扱いません。それらは、導入済みのトラッカー固有のインストルメンテーション機能が担当します。両方を組み合わせて使用してください。このスキルは何をインストルメントするかを決め、ベンダー固有の機能はそれをどう実現するかを決めます。

可観測性の基盤となるシグナルは、ログ、メトリクス、トレースの3種類です。規律あるエラー処理と専用のエラートラッカーによって、これらを実用的なものにします。プロダクトイベントもこれらと並ぶシグナルです。システムの健全性ではなくユーザーの行動を対象にした同じ測定行為であり、独自の命名、識別、同意に関するルールがあります。以下の各リファレンスは、それぞれの懸念事項を担当します。変更に関係するものを読み込んでください。

この文書における「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119に記載された意味で解釈してください。

シグナルの選択

追加しやすいシグナルではなく、本番環境で尋ねることになる質問に答えられるシグナルを選んでください。以下のフローでは、必要な情報に応じて、該当するシグナルと、それを担当するリファレンスを案内します。トレースはエラートラッカーのトレーシング連携を通じてインストルメントするため、エラートラッキングとともに扱います。

flowchart TD
  Q{What do you need to answer?} --> R1[Record that a specific operation happened, and how far it got]
  Q --> R2[Count or aggregate a rate over time - request rate, latency, error rate]
  Q --> R3[Follow one request across service or module boundaries]
  Q --> R4[Measure user behavior - a feature used, a funnel step, a conversion]
  R1 --> S1[Log line - see Logging]
  R2 --> S2[Metric - see Metrics]
  R3 --> S3[Trace - see Error Tracking, trace/replay sampling]
  R4 --> S4[Product event - see Product Event Tracking]

予期しない障害は、これらの選択肢のいずれでもないため、このフローには含まれていません。エラートラッカーに報告し（「エラー処理」と「エラートラッキング」を参照）、規律あるロギングによって、障害に至るまでの手がかりを残してください。

エラー処理

error-handling.mdを参照してください。内容は以下のとおりです。

• try-catch ブロックを配置する場所と、エラーがルートの呼び出し元に伝播する仕組み
• 捕捉したエラーへの対応フロー。制御フローのシグナルは再スローし、予期しない障害は報告してから、復旧または再スローする
• 早期リターン、リダイレクト、フォールバックの経路に入る前に、捕捉したエラーを報告する方法
• トップレベルのエラーバウンダリーと、対処につながるエラーメッセージの書き方

エラートラッキング

error-tracking.mdを参照してください。内容は以下のとおりです。

• エラー報告サービスを、プロジェクト共通のラッパーまたは初期化・設定ファイルを介して統合する方法
• キャプチャ呼び出しを追加する方法、およびキャプチャする価値のある障害と通常の制御フローの見分け方
• ブレッドクラム、トレース／リプレイのサンプリング、インストルメンテーションの境界
• テレメトリーイベントのコンテキストにシークレットや PII を含めない方法

ロギング

logging.mdを参照してください。内容は以下のとおりです。

• ログに記録する価値のある操作と、ノイズとなる操作の見分け方
• ログレベルの選択フローと、レベル（info／warn／debug）の選び方。error はエラートラッカーがないプロジェクト向けです
• 共有のルートロガーを1つ設定し、そこからモジュール単位の子ロガーを派生させる方法
• 構造化コンテキストオブジェクトと、「開始／完了」メッセージの慣例

メトリクス

metrics.md では、以下について説明しています。

• ヘルスシグナルをログ行ではなくメトリクスとして記録する判断基準
• カウンター、ゲージ、分布の選び方と、単位の宣言方法
• ラベルのカーディナリティを低く保つ方法と、決してラベルにしてはならない識別子
• ゲート制御され、ノンブロッキングで、例外を発生させない単一のラッパーを通じた出力

プロダクトイベントのトラッキング

product-event-tracking.md では、以下について説明しています。

• 分析 SDK を管理する単一のモジュールと、その手前に置く型付きイベントスキーマ
• リデザイン後も通用するイベントの命名、追加、名前変更と、単一の境界で名前とキーを正規化する方法
• イベントプロパティとユーザープロパティの違い、カーディナリティ、ペイロードに決して含めてはならないもの
• 成功時のみの事実と意図イベントを配置する方法、必要な結果の診断、サーバー側での対応
• ID の設定、ログアウト時のリセット、セッションの定義、同意に基づく初期化
• テストでイベントを検証する方法と、グラフを空にせずにイベントを移行または廃止する方法