| name | observability |
| description | アプリケーションの可観測性設計ガイド（フレームワーク非依存）。ログ・メトリクス・トレースの3本柱、構造化ログ設計、リクエストトレーシング、メトリクス設計（RED/USE）、ヘルスチェック、アラート設計、エラートラッキングをカバー。可観測性の設計、ログ設計、モニタリング設計時に使用。 |
可観測性（Observability）設計ガイド
アプリケーションの可観測性に関するフレームワーク非依存の設計ガイド。
可観測性の 3 本柱
| 柱 | 目的 | 答える問い |
|---|
| ログ | 個別イベントの記録 | 「何が起きたか？」 |
| メトリクス | 数値的な計測 | 「どのくらい起きているか？」 |
| トレース | リクエストの流れの追跡 | 「どこで時間がかかっているか？」 |
優先順位:
1. 構造化ログ（最低限これは必須）
2. メトリクス（パフォーマンス監視に）
3. 分散トレース（マイクロサービスで特に重要）
構造化ログ設計
ログレベル
| レベル | 用途 | 例 |
|---|
| ERROR | 即座に対応が必要 | DB 接続失敗、外部 API エラー |
| WARN | 潜在的な問題 | レート制限接近、非推奨 API 使用 |
| INFO | 正常な業務イベント | ユーザーログイン、注文確定 |
| DEBUG | 開発時の詳細情報 | SQL クエリ、変数の値 |
構造化ログの原則
必須フィールド:
- timestamp: ISO 8601 / UTC
- level: ログレベル
- message: 人間が読めるメッセージ
- service: サービス名
- request_id: リクエスト追跡用 ID
推奨フィールド:
- user_id: 操作ユーザー（認証後）
- method: HTTP メソッド
- path: リクエストパス
- status_code: レスポンスステータス
- duration_ms: 処理時間
- error: エラー情報（スタックトレース含む）
出力形式: JSON（機械解析可能）
ログ設計の原則
DO:
- ビジネスイベントをログに記録する
- エラーにはコンテキスト情報を含める
- リクエスト ID で関連ログを紐付ける
- 本番では INFO 以上、開発では DEBUG 以上
DON'T:
- パスワード、トークン、個人情報をログに出力しない
- ループ内で大量のログを出力しない
- ログレベルを不適切に使わない（正常処理を ERROR にしない）
- スタックトレースを本番のレスポンスに含めない
詳細: references/logging-design.md
リクエストトレーシング
相関 ID（Correlation ID）
設計:
1. リクエスト受信時に一意の ID を生成（または受信）
2. すべてのログにこの ID を付与
3. 下流サービスへのリクエストにも ID を伝播
4. レスポンスヘッダーにも ID を含める
ヘッダー規約:
- X-Request-ID（一般的）
- traceparent（W3C Trace Context 標準）
用途:
- エラー調査時にリクエスト全体の流れを追跡
- サポート問い合わせ時にユーザーから ID を取得
分散トレーシング
構成要素:
- Trace: リクエスト全体の追跡単位
- Span: 個別の操作単位（DB クエリ、外部 API 呼び出し等）
- Context Propagation: サービス間でのトレース情報の伝播
計装対象（優先度順）:
1. HTTP リクエスト/レスポンス
2. データベースクエリ
3. 外部 API 呼び出し
4. キューのメッセージ処理
5. 重要なビジネスロジック
メトリクス設計
RED メソッド（リクエスト指向 - API/サービス向け）
| 指標 | 意味 | 例 |
|---|
| Rate | リクエスト数/秒 | HTTP リクエスト数 |
| Errors | エラー率 | 5xx レスポンスの割合 |
| Duration | レスポンス時間 | p50, p95, p99 レイテンシ |
USE メソッド（リソース指向 - インフラ向け）
| 指標 | 意味 | 例 |
|---|
| Utilization | 使用率 | CPU 使用率、メモリ使用率 |
| Saturation | 飽和度 | キュー長、待ちスレッド数 |
| Errors | エラー数 | ディスク I/O エラー |
カスタムメトリクス
ビジネスメトリクス:
- アクティブユーザー数
- 注文数 / 売上
- 機能の利用率
技術メトリクス:
- DB コネクションプール使用率
- キャッシュヒット率
- 外部 API レスポンス時間
詳細: references/metrics-design.md
ヘルスチェック
エンドポイント設計
GET /health → 基本的な稼働確認（200 OK）
GET /ready → 依存サービスを含めた準備完了確認
/health レスポンス:
- status: "ok" | "degraded" | "unhealthy"
- version: アプリバージョン
- uptime: 稼働時間
/ready レスポンス:
- 各依存サービスのステータス
- DB 接続: ok/ng
- キャッシュ: ok/ng
- 外部 API: ok/ng
設計原則
- /health は軽量に（依存チェックなし、即座に応答）
- /ready は起動完了の判断に使用
- 認証不要にする（ロードバランサーから呼ばれる）
- タイムアウトを設定する（ヘルスチェック自体がハングしない）
アラート設計
アラートの原則
1. アクション可能なアラートのみ設定
→ 「見たけど何もしない」アラートは削除
2. 症状ベース > 原因ベース
→ ❌ "CPU 使用率が 80% 超過"
→ ✅ "レスポンス時間の p95 が 2秒 超過"
3. 適切な閾値設定
→ 過敏すぎない（アラート疲れの防止）
→ 遅すぎない（障害の早期検知）
4. 段階的なエスカレーション
→ Warning → Critical → Page
重要アラート例
| 対象 | 条件 | 重要度 |
|---|
| エラー率 | 5xx が 5% 超過 | Critical |
| レイテンシ | p95 が SLA 超過 | Critical |
| ヘルスチェック | 3回連続失敗 | Critical |
| ディスク容量 | 90% 超過 | Warning |
| 証明書期限 | 30日以内に期限切れ | Warning |
エラートラッキング
記録すべき情報:
- エラーメッセージとスタックトレース
- 発生環境（本番/ステージング）
- リクエスト情報（URL, メソッド, ヘッダー）
- ユーザー情報（匿名化）
- 発生頻度と影響範囲
グルーピング:
- 同一スタックトレースのエラーを集約
- 新規 vs 既知のエラーを区別
- リリースバージョンとの相関
レビューチェックリスト
リファレンス
