sentry-integration

Sentry 統合

固定された運用手順と明確な判断ルールに基づいて、Sentry 統合を実装します。スキルのエージェント間での移植性を維持するため、プロジェクト固有の詳細はリファレンスに記載してください。

トリガー条件

以下のいずれかに関するリクエストでは、このスキルを読み込みます。

• Sentry SDK のセットアップまたは移行
• エラー追跡、例外の捕捉、または想定内エラーの分類
• インストルメンテーションとスパンの設計
• パフォーマンスの問題、遅いリクエスト、トレース分析、またはサンプリング戦略
• TRPC、HTTP ハンドラー、またはサーバー関数向けのミドルウェアの組み込み
• issue／プロジェクト／アラートに関する Sentry API の利用

運用ワークフロー（順序必須）

1. SDK を設定します（サーバーを先に、クライアントを後に）。
2. フレームワークの境界にミドルウェアを組み込みます。
3. 捕捉処理と beforeSend の前に、想定内エラーを分類します。
4. 標準のインテグレーションでは不十分な箇所に限り、トレーシングを追加します。
5. まず非本番環境で、イベント、スパン、タグ、ノイズのフィルタリングを検証します。

テレメトリーのノイズやトレースコンテキストの破損を防ぐため、この順序で手順を実行してください。

1) SDK を設定する

環境、リリース、サンプリングを明示的に定義します。ヘルスチェックと合成トラフィックはトレースから除外してください。

サーバー／クライアントの初期化例は references/sentry-code-samples.md を参照してください。

2) ミドルウェアを組み込む

Sentry ミドルウェアは、単一のプロシージャエクスポートだけではなく、共通の境界に組み込みます。

すべてのプロシージャチェーンに同じミドルウェアのルールを適用します。

• publicProcedure
• 認証済み／保護されたプロシージャ
• 管理者向けまたは組織スコープ付きプロシージャ
• カスタムで構成されたチェーン

TRPC とサーバー関数の例は references/sentry-code-samples.md を参照してください。

3) 想定内エラーを分類する

アラートのノイズを減らしつつ可観測性を維持するため、想定内のビジネスエラーを処理済みとしてマークします。

想定内エラーは、次の 2 か所で分類します。

• カスタムの captureException ラッパー
• SDK の beforeSend

beforeSend では、必ず hint.originalException（または同等のヘルパー）からスローされた例外を取得してください。未定義の error 変数を参照しないでください。

固定の beforeSend の例とヘルパー関数は references/sentry-code-samples.md を参照してください。

4) トレーシングを追加する

まず組み込みのインテグレーションを優先し、カバーされていない経路に限り手動トレーシングを追加します。

データベーストレーシングの判断ルール

• サポート対象の PostgreSQL ドライバーと標準的なクエリ経路を使用する場合は、postgresIntegration を使用します。
• クエリがサポート対象のインテグレーションを迂回する場合、Drizzle／カスタムビルダーをラップする場合、またはオペレーションレベルの名前付けが必要な場合は、手動またはプロキシによるトレーシングを使用します。
• スパンの重複を防ぐため、同じクエリ経路で両方の方法を実行しないでください。

手動トレーシングとプロキシトレーシングの例は references/sentry-code-samples.md を参照してください。

5) 検証する

各統合の変更を、次の短いチェックリストで検証します。

1. 想定内エラーを 1 件発生させ、警告レベルの処理済みイベントであることを確認します。
2. 想定外エラーを 1 件発生させ、エラーレベルのアラート経路を確認します。
3. インストルメント済みのリクエストを 1 件実行し、トレースの連続性を確認します。
4. ヘルスチェックのルートが除外されていることを確認します。
5. DB スパンが重複していないことを確認します。

Sentry API サービスの対象範囲

Sentry API サービスの作業（issue／プロジェクト／トークン検証）は、任意の上級者向けモジュールとして扱います。実装が Sentry 統合の範囲内に収まる場合に限り、同じスキルに含めてください。それ以外の場合は、専用の運用スキルに分割します。

Effect 指向の API サービスの例は references/sentry-code-samples.md を参照してください。

基本ルール

1. ワークフローの順序に従います。SDK の設定 → ミドルウェアの組み込み → 想定内エラーの分類 → トレーシングの追加 → 検証。
2. 想定内エラーは可観測な状態を保ちつつ、処理済みとしてマークします。
3. すべてのプロシージャチェーンで、ミドルウェアの適用範囲を一貫させます。
4. 手動またはプロキシによるトレーシングよりも、組み込みの DB インテグレーションを優先します。
5. ロールアウト前に、非本番環境で統合の動作を検証します。
6. 大きなコード例はリファレンスファイルに置き、判断ルールは SKILL.md に記載します。