sentry-instrumentation-guide

すべてのスキル > 機能のセットアップ > 計装ガイド

Sentry 計装ガイド：どのシグナルを使うべきか

エラー、トレース、ログ、メトリクスは、ほとんどのアプリが使用する4種類のテレメトリであり、互いに重なる部分も多いため、どれを選ぶべきかは簡単には判断できません。ログに記録する代わりに、スパン属性にコンテキストを詰め込むこともできます。メトリクスを出力する代わりに、ログ行を数えることもできます。ログに処理時間を加えて、スパンと呼ぶこともできます。

しかし、それぞれのシグナルが存在するのは、異なる問いに答え、取り込まれた後に異なるワークフローに活用されるからです。誤ったシグナルを選ぶと、データは技術的には存在していても、後で実際に必要となる用途には役立ちません。このスキルは、目の前にある値やイベントをどのシグナルで記録すべきか、そしてその理由を判断するためのフレームワークです。

このスキルでは、何を出力するかを判断します。スタックごとに各要素をどのように有効にするかについては、sentry-*-sdk スキルと sentry-setup-ai-monitoring に引き継いでください。

このスキルを使う場面

• コードを計装する際、ある情報をログ、スパン、スパン属性、メトリクスのどれにすべきか判断できないとき
• サービスやリクエストハンドラー全体で「何をどこに計装するか」を決めるとき
• 既存の計装に不足がないか確認するとき（例：ユーザーから問題の報告があるのに、エラーフィードが空の場合）
• コーディングエージェントが、エラー、トレース、ログ、メトリクスの中から一貫した基準で選ぶ必要があるとき

重要： ここに記載されている SDK API とコード例は説明用です。実装する前に、正確なシグネチャと最小バージョンを docs.sentry.io および該当する sentry-*-sdk スキルで確認してください。

4つのシグナル、それぞれが答える1つの問い

シグナル	答える問い	ドキュメント
エラー	「たった今、何が壊れたのか？」— スタックトレースと例外の種類を、重複が排除された Issue にまとめ、担当者を割り当てて解決まで追跡します。コードが例外をスローしたなら、それはエラーです。	Issue
トレース	「リクエストは想定どおりに流れたか？」— 時間計測されたスパンをウォーターフォール形式で表示します。ほとんどは自動計装されます。	トレースエクスプローラー
ログ	「この時点でコードの状態はどうなっていて、その理由は何か？」— 設定、フラグ、入力／出力、行われた判断など、ある時点でのシステムの状態を構造化イベントとして記録します。	ログ
メトリクス	「時間の経過とともに、どう推移しているか？」— 属性で絞り込み、グラフ化したり、アラートを設定したり、デプロイ間で比較したりできるカウンター、ゲージ、分布です。	メトリクス

役立つ考え方としては、ログは1件のリクエストの物語（針）、メトリクスはその集計結果（干し草の山が正常かどうか）、トレースは時間の使われ方、そしてエラーはスタックトレースと担当者が必要なものです。

判断表

判断に迷ったら、次の表を参考にしてください。

知りたいこと	選ぶシグナル
何かがクラッシュした。スタックトレースを表示したい	エラー
どれくらい時間がかかったか？どのステップが遅いか？	トレース／スパン
リクエストは想定したステップを通過したか？	トレース／スパン
コードがこの判断をしたとき、状態はどうだったか？	ログ
この関数が受け取った値と返した値は何か？	ログ
X はどのくらいの頻度で発生するか？発生率は正常か？	メトリクス
デプロイ後に何か変化したか？	メトリクス

重複の解消

同じ値が複数のシグナルに正当に含まれることがあります。次の4つの判断基準で、実際のほとんどのケースに対応できます。（詳しい根拠、注意点、「すべてをログに記録する／1つの幅広いイベントを出力するだけではだめなのか」という議論については、references/choosing-signals.md をご覧ください。）

• スパン属性かメトリクスか？ そのトレースを読みながら確認したい、1つのリクエストの流れに関する情報 → スパン属性（ウォーターフォール上でスパンに付随します）。単独の値としてグラフ化、アラート、またはすべてのリクエストを対象とした経時的な分類に使いたい → メトリクス。同じ数値を両方に記録する価値がある場合もあります。1つのリクエストを確認するためにスパンに candidate_count を、発生率を監視するために recommendations.served をメトリクスとして記録します。
• ログかスパンか？ スパンはフロー内の時間を計測するノードです（主に自動計装されるため、自分で記述することはほとんどありません）。ログはそのノード内の判断時点の状態です（目的を持って必ず自分で記述します）。スパンは「どこで」「どれくらい時間がかかったか」に答え、ログは「何が起きていたか、なぜか」に答えます。
• ログかメトリクスか？ ログは問題が発生した特定のリクエストを見つけるためのものです（干し草の山から針を探します）。メトリクスは問題が発生したリクエストの件数を把握するためのものです（干し草の山全体を見ます）。ログ行を数えて発生率を算出しないでください。メトリクスを直接出力します。
• エラーかログか？ スタックトレースが必要で、Issue として追跡すべき場合 → エラー。想定外だが処理済みで、記録する価値がある状況 → ログ。トレースバックがあるものの、本当に重大ではない場合は、logger.warning(exc_info=True) を使うと、エラーフィードに不要なノイズを増やさずログにトレースを残せます。

（お使いの言語でのサンプリングとフィルタリングの正確な設定については、該当する SDK スキルの references/tracing.md と references/metrics.md をご覧ください。）

4つのシグナルはすべて1つの SDK から出力されるため、trace_id を共有し、自動的に相関付けられます。つまり、すべてのログとメトリクスがそれぞれのトレースに関連付けられるため、メトリクスの急増箇所から、その背後にあるサンプルを直接詳しく調べられます。

意図的な計装とは

スパンのおよそ80％は、フレームワークやデータベースのインテグレーションによって自動計装されるため、自分で記述するものはほとんどありません。意図的に行う作業は残りの20％です。コードが後で検証する価値のある判断を下す箇所に、フローを補足するスパン属性を1つか2つ、判断時点のログ、そしてメトリクスを追加します。

references/instrumentation-examples.md では、単一のリクエストハンドラーをエンドツーエンドで計装する方法を、Python と JavaScript/TypeScript の両方で解説します。同じ判断について、スパン属性、ログ、メトリクスを並べて確認できます。

セットアップへの引き継ぎ

このスキルでは、何を出力するかを説明します。各要素を実際に設定するには、次の手順を行います。

• SDK をインストールし、トレーシング、ログ、メトリクスを有効にする → 該当する sentry-<platform>-sdk スキル（例：sentry-python-sdk、sentry-nextjs-sdk、sentry-node-sdk）。各スキルには、トレーシング、ログ記録、メトリクスなどの機能ごとのリファレンスファイルがあります。
• LLM／エージェントの呼び出しを計装する → sentry-setup-ai-monitoring。

ログとメトリクスは、まだ有効にしていないプロジェクトが最も多い2つの要素であり、どちらもすべてのプランに含まれています。有効になっていない場合は、まず SDK スキルを案内し、その後ここに戻って、各情報をどこに記録するかを決めてください。