observability

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 既知のエラーを区別
  - リリースバージョンとの相関

レビューチェックリスト

• 構造化ログが JSON 形式で出力されている
• リクエスト ID がすべてのログに含まれている
• 機密情報がログに含まれていない
• ログレベルが適切に使い分けられている
• ヘルスチェックエンドポイントが実装されている
• エラー率・レイテンシのメトリクスが計測されている
• アクション可能なアラートが設定されている

リファレンス

• references/logging-design.md - ログ設計パターン詳細
• references/metrics-design.md - メトリクス設計詳細