api-observability-axiom-pino-sentry

可観測性のパターン（ロギング、トレーシング、エラーハンドリング）

クイックガイド： Pino による構造化ロギング（debug/info/warn/error）。リクエストトレーシングのための相関 ID。React での Sentry エラーバウンダリー。認証後にユーザーコンテキストを追加。想定されるエラー（404）をフィルタリング。アラート用の Axiom モニターを作成します。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードはプロジェクトの CLAUDE.md の規約に従う必要があります（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）

（リクエストトレーシングのため、すべてのログステートメントに相関 ID を必ず含めてください）

（必須フィールド（level、message、correlationId、timestamp）を含む構造化ロギングを必ず使用してください）

（クォータの浪費を避けるため、想定されるエラー（404、バリデーション）を Sentry から必ずフィルタリングしてください）

（認証の完了後に、必ずユーザーコンテキストを Sentry に追加してください）

（すべてのログ呼び出しでフィールドを繰り返す代わりに、コンテキストを持つ子ロガーを必ず使用してください）

</critical_requirements>

---

自動検出： log、logger、pino、Sentry、エラーバウンダリー、相関 ID、trace、span、可観測性、監視、アラート

使用する場合：

• 新機能のコードにロギングを追加する
• エラーハンドリングのパターンを実装する
• 相関 ID を使ったリクエストトレーシングを設定する
• パフォーマンスのデバッグ用にカスタムトレースやスパンを作成する
• React コンポーネントで Sentry エラーバウンダリーを設定する
• Axiom モニターとアラートを作成する

使用しない場合：

• プロジェクトの初期セットアップと依存関係のインストール（1 回限りの設定です。公式ドキュメントに従ってください）
• フレームワーク固有の設定ファイル（フレームワーク SDK のドキュメントに従ってください）

対象となる主なパターン：

• ログレベルの判断ツリー（debug/info/warn/error の使い分け）
• 必須フィールドを含む構造化ロギング
• 相関 ID：生成、伝播、ログへの付加
• OpenTelemetry を使ったカスタムトレース／スパン
• React での Sentry エラーバウンダリー
• 認証後のユーザーコンテキストの Sentry への追加
• Axiom モニターとアラートの作成
• ノイズのフィルタリング（404 などの想定されるエラー）
• パフォーマンス監視のパターン
• デバッグガイド：システム内のリクエストを追跡する

詳細リソース：

• コード例については、examples/core.md を参照してください（必須パターンは常に読み込まれます）
• 判断のフレームワークとアンチパターンについては、reference.md を参照してください

拡張例：

• examples/correlation-ids.md - リクエストトレーシング用のミドルウェア
• examples/tracing.md - OpenTelemetry のスパンとカスタム計装
• examples/error-boundaries.md - Sentry を使った React エラーバウンダリー
• examples/sentry-config.md - ユーザーコンテキストとエラーフィルタリング
• examples/axiom.md - モニター、アラート、デバッグクエリ
• examples/performance.md - クエリと API 呼び出しの追跡

---

基本理念

優れた可観測性は、次の 3 つの問いに答えます：

1. 何が起きましたか？（コンテキストを含む構造化ログ）
2. なぜ起きましたか？（スタックトレースを使ったエラー追跡）
3. どうすれば見つけられますか？（関連イベントを結び付ける相関 ID）

ロギングは意図的に行うものであり、念のために行うものではありません。すべてのログステートメントは、デバッグ時に尋ねる可能性のある具体的な問いに答えるべきです。「念のため」のロギングは避けてください。ノイズが増え、実際の問題を見つけにくくなります。

---

基本パターン

パターン 1：ログレベルの判断基準

状況に応じて適切なログレベルを選択します。

What are you logging?
├─ Development-only debugging info?
│   └─ debug (filtered in production)
├─ Normal operation events?
│   ├─ Request started/completed → info
│   ├─ User action completed → info
│   └─ Background job finished → info
├─ Something unexpected but recoverable?
│   ├─ Retry attempt → warn
│   ├─ Fallback used → warn
│   └─ Deprecation notice → warn
└─ Something that needs attention?
    ├─ Unhandled exception → error
    ├─ External service failure → error
    └─ Data integrity issue → error

レベルのガイドライン：

レベル	本番環境	使用する場面
debug	フィルタリング対象	開発時のデバッグ、詳細なトレース
info	表示	通常の操作、リクエストのライフサイクル、ユーザー操作
warn	表示	復旧可能な問題、再試行、フォールバック
error	表示＋アラート	復旧不可能な問題、失敗、例外

コード例については、examples/core.md を参照してください。

---

パターン 2：必須フィールドを含む構造化ログ

検索しやすくするため、すべてのログに構造化コンテキストを含めてください。

必須フィールド：

フィールド	型	用途
correlationId	string	同一リクエストのすべてのログを関連付けます
service	string	サービスを識別します（api、web、worker）
operation	string	実行中のアクションを示します
userId	string?	アクションを実行するユーザー（認証済みの場合）
duration	number?	所要時間（ミリ秒）（完了した操作の場合）

コード例については、examples/core.md を参照してください。

---

パターン 3：リクエストトレース用の相関 ID

相関 ID を生成して伝播させ、サービス間でリクエストを追跡します。

主なコンポーネント：

1. 相関 ID ミドルウェア - ヘッダーから相関 ID を生成または抽出します
2. リクエストロガーミドルウェア - 相関コンテキストを持つリクエストスコープのロガーを作成します
3. ルートハンドラーでの使用 - 子ロガーは相関 ID を自動的に継承します

最新の代替方法：AsyncLocalStorage + Mixin

大規模なアプリケーションでは、AsyncLocalStorage と Pino の mixin オプションを使用すると、各ハンドラーで子ロガーを手動で作成せずにコンテキストを自動的に挿入できます。

両方の方法の実装例については、examples/correlation-ids.md を参照してください。

---

パターン 4：OpenTelemetry によるカスタムトレースとスパン

パフォーマンスのデバッグ用にカスタム計装を追加します。

主なユーティリティ：

• withSpan() - 非同期処理をトレース対象のスパンでラップします
• createSpan() - 同期処理用のシンプルなスパンを作成します

コード例については、examples/tracing.md を参照してください。

---

パターン 5：React の Sentry エラーバウンダリー

React コンポーネントのエラーを捕捉して報告し、復旧できるようにします。

主なコンポーネント：

1. ErrorBoundary - レンダリングエラーを捕捉するクラスコンポーネント
2. global-error.tsx - SSR フレームワークのグローバルエラーハンドラー
3. 機能レベルのバウンダリー - 機能セクションをカスタムのフォールバックでラップします

実装例については、examples/error-boundaries.md を参照してください。

---

パターン 6：Sentry へのユーザーコンテキストの追加

デバッグを容易にするため、認証後にユーザー情報を Sentry に追加します。

主な関数：

• setSentryUser() - 認証成功後に呼び出します
• clearSentryUser() - ログアウト時に呼び出します
• setSentryContext() - 機能ごとに追加のコンテキストを追加します

コード例については、examples/sentry-config.md を参照してください。

---

パターン 7：想定内のエラーのフィルタリング

想定内のエラーによる Sentry のクォータ消費やアラート発生を防ぎます。

フィルタリング戦略：

1. beforeSend フック - エラーメッセージのパターンに基づいてフィルタリングします
2. HTTP ステータスのフィルタリング - 404、401、403 を除外します
3. beforeBreadcrumb フック - ノイズとなる console.log のブレッドクラムを削除します

設定例については、examples/sentry-config.md を参照してください。

---

パターン 8：Axiom のモニターとアラートの作成

本番環境の問題をプロアクティブに監視できるように設定します。

モニターの種類：

1. エラー率モニター - エラー率が 1% を超えた場合にアラートを送信します
2. レイテンシモニター - P95 が 2 秒を超えた場合にアラートを送信します
3. 特定のエラーモニター - データベース接続エラーが発生した場合にアラートを送信します

APL クエリの例については、examples/axiom.md を参照してください。

---

パターン 9：パフォーマンス監視のパターン

時間のかかる操作を追跡し、最適化します。

追跡ユーティリティ：

• trackedQuery() - データベースクエリをパフォーマンス追跡でラップします
• trackedApiCall() - 外部 API 呼び出しをパフォーマンス追跡でラップします

実装例については、examples/performance.md を参照してください。

---

パターン 10：デバッグガイド - リクエストの追跡

デバッグ時に、システム内のリクエストを追跡する方法です。

手順：

1. レスポンスヘッダー、Sentry、またはユーザーからの報告から相関 ID を取得します
2. Axiom でその相関 ID を含むすべてのログを検索します
3. タイムラインビューでリクエストの流れを分析します
4. 関連するエラーとスタックトレースを見つけます
5. 追加のコンテキストがないか Sentry を確認します

詳細な APL クエリとチェックリストについては、examples/axiom.md を参照してください。

---

<red_flags>

重大な注意事項

アンチパターンと重大な注意事項の詳細については、reference.md を参照してください。

クイックリファレンス - 優先度の高い問題：

• ログに相関 ID がない - リクエストを追跡できません
• 構造化ロガーではなく console.log を使用している - 検索できず、ログレベルもありません
• 機密データをログに記録している - セキュリティ上の脆弱性です
• Sentry で想定内のエラーをフィルタリングしていない - クォータを無駄にし、実際の問題が埋もれます
• スタックトレースのないエラーログ - エラーが発生した場所がわからず、デバッグできません

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md に記載されたプロジェクトの規約に従う必要があります

（リクエストを追跡できるよう、すべてのログステートメントに相関 ID を必ず含めてください）

（必須フィールド（level、message、correlationId、timestamp）を含む構造化ログを必ず使用してください）

（クォータの浪費を防ぐため、想定内のエラー（404、検証エラー）を Sentry から必ず除外してください）

（認証完了後に、必ずユーザーコンテキストを Sentry に追加してください）

（すべてのログ呼び出しでフィールドを繰り返すのではなく、コンテキストを含む子ロガーを必ず使用してください）

これらのルールに従わないと、追跡できないリクエスト、Sentry クォータの浪費、デバッグの困難を招きます。

</critical_reminders>