sentry-instrument-logging

Sentry ログを計装する

このスキルは、計装ガイダンスに沿って、アプリケーションに構造化された Sentry ログを追加します。

目的は、本番環境での動作をより簡単に把握し、デバッグできるようにする、価値の高いログメッセージを少数追加することです。

このスキルで追加するログメッセージは、アプリケーションの残りの部分を計装する際にユーザーが参考にできる、明確で繰り返し使える例としても役立ちます。

前提条件

リポジトリには、すでに基本的な Sentry の設定が必要です。

Sentry がまだ設定されていない場合は、適切なスキルを使ってセットアップすることを提案してください。

手順

1. リポジトリ内のすべてのアプリケーションを一覧化します。 言語／ランタイムのマニフェスト（composer.json、package.json、go.mod、Gemfile、pyproject.toml、Cargo.toml など）を探します。通常、各マニフェストは個別にデプロイされるアプリケーションを示しています。次の表を明示的に作成し、このスキルの残りの作業リストとして扱います。

   アプリ	パス	言語	Sentry SDK？	ロギング抽象化	ステータス

   リポジトリにアプリケーションが約 2 つを超えて含まれる場合は、作業を始める前に対象範囲をユーザーに確認します。今回はどのアプリケーションに、どの程度の深さで計装するかを確認してください。

2. アプリケーションに手を加える前に、共通の規約を一度に確立します。 属性の名前空間（例：myapp.<domain>.<field>）、イベント名の表現、ログレベルに一貫性を持たせ、すべての言語のログを一緒に検索・関連付けできるようにします。これらを記録し、各アプリケーションの作業で従うようにします。トレースヘッダー（baggage / sentry-trace）を伝播するサービス境界を記録します。そのような呼び出しの両側のログで属性名を共通にすれば、言語をまたいでも単一のトレースを一貫して読み取れます。

3. 一覧にあるアプリケーションごとに、次の作業をすべて完了してから次に進みます。 作業の進捗に応じてステータスを更新します（not started → configured → instrumented → verified）。

   a. skills にある該当言語のスキルを読み、Sentry のロギングが設定されていることを確認します。 b. アプリケーションのロギング抽象化（Monolog/PHP、slog/Go、Rails logger/Ruby、Pino または console/JS）を特定します。Sentry が対応している場合はその統合を設定し、対応していない場合は Sentry のロギング SDK を直接使用します。 c. 実行時の判断、重要なアルゴリズム、監査イベント、復旧可能な障害に関するコンテキストを優先し、価値の高いログメッセージを少数特定します。計装する価値のあるログエントリーに従ってください。 d. ステップ 2 の共通規約と計装ガイダンスに従って、構造化ログを追加します。 e. 検証します。利用可能であれば、アプリケーションの lint／型チェック／テストツールを実行し、ログが出力されることを確認します。ツールチェーンをローカルで利用できない場合は、成功したかのように示さず、その旨を明記してください。

4. 価値の高いログの検証を行います。 追加または変更したすべてのログ行を確認し、この検証を通過しないものは削除するか修正します。

   チェック	確認事項
   本番環境での疑問	このログは、本番環境に関する具体的にどのような疑問に答えますか？
   有用性	数百回、数千回出力されても有用ですか？
   テレメトリーとしての適合性	トレース、メトリクス、Sentry エラーとして記録するほうが適切ではありませんか？
   既存の記録	例外、既存のログ、共通 API／クライアントラッパーによって、すでに記録されていませんか？
   構造	イベント名と属性は共通規約に沿っていますか？
   安全性	PII、秘密情報、生のペイロード、不安定な例外メッセージが含まれていませんか？
   対応可能性	このログを見ることで、調査や対応の仕方が変わりますか？

   定型的な UI 操作を確認するだけのログ、一般的な API 障害と重複するログ、意味のあるコンテキストを加えずに予想される検証エラーを記録するログは、削除することを優先します。

   重要な実行時の判断を説明するログ、複数ステップのワークフローを要約するログ、重要な監査／ビジネスイベントを記録するログ、復旧可能な障害に関するコンテキストを示すログは残します。

   残すログについては、次のような一文で価値を説明できるようにします。 「このログは、 への回答に役立つため価値があります。」

5. 一覧と照合します。 対象範囲内のすべてのアプリケーションが verified に達したこと（または明示的に延期されたこと）を確認します。アプリケーションごとのステータスを報告し、一部のみの対応を全体の対応と誤認させないようにします。

計装ガイダンス

ロギングとその他のテレメトリーを使い分ける場面

ログは、アプリケーションの実行中に何が起きたかを説明するコンテキストや判断を記録するのに適しています。

• リクエストのパフォーマンスや流れを測定するには、トレーシングを使用します。
• 予期しない重大な障害には、エラーを使用します。

計測する価値のあるログ項目

アプリケーションが実行時に行う重要な判断

リクエストの処理中にアプリケーションが行う判断は、本番環境での挙動を説明するために必要なコンテキストとして、しばしば欠けているものです。

例：

• ユーザーでフィーチャーフラグが有効になっているため、異なるコードパスが実行される。
• モバイルユーザーが別のエクスペリエンスにリダイレクトされる。
• 有料ユーザーと無料ユーザーで異なる機能が提供される。

こうした情報は、たとえばフィーチャーフラグの評価時に単独のログ項目として記録する場合にも、その後のログメッセージに構造化コンテキストとして含める場合にも役立ちます。

機能やアルゴリズムが想定どおりに動作しているかどうか

機能が複数の手順を実行する場合、ログが役立ちます。途中の結果を記録することで、プロセスのどこで問題が起きているのか、なぜ起きているのかを把握できます。

別のサービスからユーザーがログブックをインポートできるサイトの例を紹介します。

Sentry.logger.info("Aurora import started", {
  "import.source": "aurora",
  "import.entries_received": body.ascents.length,
});

// Algorithm runs here...

Sentry.logger.info("Aurora import finished", {
  "import.source": "aurora",
  "import.entries_received": body.ascents.length,
  "import.imported": imported,
  "import.climbs_created": climbsCreated,
  "import.skipped": skipped,
  "import.skipped.missing_name": skipDetails.missingName,
  "import.skipped.unknown_grade": skipDetails.unknownGrade,
  "import.skipped.invalid_angle": skipDetails.invalidAngle,
  "import.skipped.already_imported": skipDetails.alreadyImported,
});

重要な段階がログに記録され、最終結果では実行された処理の概要が示されます。これにより、インポートが成功した箇所、失敗した箇所、または予期しない結果が生じた箇所を把握しやすくなります。

監査イベントとアクセスイベント（作成、更新、削除、アクセス、権限）

監査ログは、「誰が変更したのか」「いつ発生したのか」「この操作は想定されたものか」といった質問に答えるのに役立ちます。

エンティティの作成、更新、削除、表示、権限の変更など、アプリケーションの状態に対する重要な変更を記録します。

適切に判断してください。ほとんどのアプリケーションでは、データベース操作をすべてログに記録する必要はありませんが、セキュリティ上重要な操作や重要なビジネスイベントを記録すると役立つことがよくあります。

エラーや障害に伴うコンテキスト

例外については、ログ行を追加するよりもエラーを使用したほうが適切なことがよくあります。

すべての障害を Sentry のイシューにする必要はありません。

次のような障害は、ログメッセージとして記録するほうが適切な場合がよくあります。

• 重要ではない任意の上流サービスで発生した障害。
• 最終試行より前のリトライループ中に発生した障害。

この種の error ログメッセージには、次の情報を含めることを検討してください。

• リトライ回数。
• 外部 API 呼び出しのレスポンスステータスコードと、機密情報ではない重要なリクエストまたはレスポンスのフィールド。
• 障害に至るまでの実行時の判断。

ログメッセージの構成方法

構造化ログメッセージを使用する

一貫したキーと値のペアで情報を記録する構造化ログを使用します。

アプリケーション全体で一貫したフィールド名を使用すると、類似するイベントを検索、集計、比較できます。

適切なログメッセージでは、通常、次の3つの質問に答えます。

• 誰が操作を実行したか（たとえば、認証済みユーザー）。
• 何が起きたか（人が読めるメッセージと補足的なメタデータ）。
• いつ起きたか（通常はロギングシステムによって自動的に追加されます）。

適切な場合は、Sentry の SDK を使用してコンテキストをグローバルに設定します。たとえば、多くの SDK では set_user を使用して、認証済みユーザーの情報を1か所で設定し、すべてのイベントに付加できます。

リクエストの進行に合わせてコンテキストを追加する

リクエストがアプリケーション内を進むにつれて、ログにコンテキストを蓄積していきます。

初期のログメッセージにはリクエスト情報のみが含まれる場合があります。その後のメッセージでは、認証済みユーザーの情報、フィーチャーフラグ、実行時の判断、イベント固有のメタデータを追加できます。

Sentry はログメッセージにトレース ID を自動的に付加するため、トレースと関連付けることができます。

適切なログレベルを選ぶ

適切なログレベルを使うことで、ログメッセージにさらなる意味を持たせることができます。

一時的な診断情報には debug を使います。

通常のアプリケーションイベントや状況を示す情報には info を使います。

アプリケーションの正常な動作を妨げないものの、注意が必要な回復可能な状況には warn を使います。

適切に処理される予期しない失敗には error を使います。Sentry の課題として扱うべき例外には、優先してエラーを使います。

オブジェクトのログ記録方法

オブジェクト全体をログに記録するのは避けます。代わりに、イベントに関連するフィールドだけを、ネストした値を名前空間で区切るドット記法を使って記録します。

任意属性が存在しない場合は、空文字列、null、プレースホルダー値を記録するのではなく、省略します。

ログに記録してはいけないもの

コードの各行や関数呼び出しをすべてログに記録しない

すべての関数呼び出しやサービス呼び出しの計測には、トレーシングやプロファイリングを使うほうが適しています。

PII やその他の機密情報をログに記録しない

ログに書き込まれた内容は、いずれ別の人が見る可能性があると考えてください。

• 可能な限り、メールアドレス、ユーザー名、氏名ではなく、不透明なユーザー ID を使います。set_user などを使ってグローバルなユーザーコンテキストを設定する場合も同様です。
• パスワード、アクセストークン、API キーなどの秘密情報は、決してログに記録してはいけません。
• 年齢、性別、郵便番号など、その他の個人情報も、管轄区域によっては規制対象となる場合があります。
• ログに記録する内容、保持する内容、公開する内容を決める際は、PCI、GDPR、CCPA、HIPAA などの法律や規格に注意してください。

ログに記録する内容は慎重に選んでください。アプリケーションのデバッグと運用に必要な最小限の情報だけを記録します。

大量のデータ（特定の目的がない場合）

構造化されていない大量のデータをログに記録する正当な理由もあります。

• LLM のプロンプトと応答全体を見ることで、製品が想定どおりに動作しているか理解しやすくなる場合があります。
• Webhook の本文をログに記録することで、外部連携の問題をデバッグしやすくなる場合があります。

ただし、この種のデータをログに記録すると、コストとリスクの両方が生じます。

• ユーザーが LLM のプロンプトに個人情報や機密情報を含める場合があります。
• HTTP リクエストやレスポンス全体に、アクセストークン、秘密情報、その他の機密データが含まれる場合があります。

可能な場合は、ペイロード全体ではなく、クエリ対象として想定する特定のフィールドをログに記録してください。

スキル固有のガイダンス

このスキルの目的は、ログの網羅性を最大化することではなく、優れたログ記録の実践例を示すことです。

考えられるすべてのコードパスを計測するよりも、価値の高いログメッセージをいくつか追加することを優先してください。

各ログメッセージは、次の条件を満たす必要があります。

• 本番環境のデバッグですぐに役立つ。
• 構造化ログを効果的に活用している。
• ユーザーがコードベースのほかの場所でも参考にできる実用的な例となっている。

小規模なコードベースでは、今後の計測の実用的な手本となるよう、代表的なログを十分に追加してください。

大規模なコードベースでは、すべてを計測しようとするのではなく、代表的な箇所をいくつか重点的に扱ってください。

ユーザー識別子をログ属性として繰り返し記録するよりも、SDK の setUser 機能を使って、ログを認証済みユーザーに関連付けることを強く推奨します。ユーザー識別子は、認証済みユーザー以外の何かを示す場合に限り、ログ属性として含めてください。

コードベースにすでにログがある場合

新しいログ行を追加する前に、既存のログを調べ、不足している点を特定してください。

次の対応を優先してください。

• 既存のログを構造化して改善する。
• 重要な既存ログに不足しているコンテキストを追加する。
• 重要な本番環境の疑問に、現時点で答えられない箇所だけにログを追加する。特に、失敗が未捕捉の例外としてすでに表現されており、そのため Sentry のエラーとして捕捉される可能性が高いかどうかを確認してください。