| name | observability |
| description | ロギング、メトリクス、分散トレーシングのオブザーバビリティパターン。以下の場合に使用:
- 構造化ロギングの実装
- メトリクスとモニタリングのセットアップ
- 分散トレーシングの追加
- ヘルスチェック（liveness、readiness）の実装
- アラートや SLO ベースのモニタリングの設計
Trigger phrases: logging, metrics, tracing, monitoring, health check, alerting, SLO, structured logs, observability
|
| allowed-tools | Read, Glob, Grep, Write, Edit, Bash, WebSearch, WebFetch |
| model | sonnet |
| user-invocable | true |
オブザーバビリティ
ロギング、メトリクス、トレーシングを通じてオブザーバブルなシステムを構築するためのスタック非依存パターン。このスキルはコンセプトとパターンを定義するものであり、特定のライブラリ実装を定義するものではない。
設計原則
- ライブラリよりコンセプト: 任意のスタックで動作するパターンを教える
- プロジェクトのツールを発見: プロジェクトが使用するオブザーバビリティツールを確認
- 実装時にリサーチ: WebSearch で最新のライブラリ推奨を調査
- プロジェクトの慣例に従う: 既存のロギング/メトリクスパターンに合わせる
オブザーバビリティの 3 本柱
1. ロギング
デバッグと監査のための構造化されたコンテキスト付きログ。
2. メトリクス
モニタリングとアラートのための数値測定。
3. トレーシング
サービス間の分散リクエスト追跡。
構造化ロギング
ログフォーマットの原則
適切に構造化されたログエントリは以下を含むべき:
{
"timestamp": "ISO 8601 形式",
"level": "INFO/WARN/ERROR/DEBUG",
"service": "サービス識別子",
"trace_id": "リクエスト追跡用の相関 ID",
"message": "人間が読める説明",
"context": {
"relevant": "コンテキストデータ"
}
}
ログレベル
| レベル | 使用場面 | 例 |
|---|
| DEBUG | 開発の詳細 | クエリパラメータ、キャッシュヒット |
| INFO | 通常の操作 | ユーザー作成、リクエスト完了 |
| WARN | 潜在的な問題 | リトライが必要、非推奨 API の使用 |
| ERROR | 操作失敗 | データベース接続失敗 |
| FATAL | アプリケーションクラッシュ | 回復不能なエラー |
ベストプラクティス
すべきこと:
- 構造化ロギングを使用（JSON または類似形式）
- 相関/トレース ID を含める
- サービス境界でログ出力
- 関連コンテキストを含める
- サービス間で一貫したフィールド名を使用
すべきでないこと:
- 機密データをログに記録しない（パスワード、トークン、PII）
- ループ内で高頻度にログ出力しない
- ログメッセージに文字列連結を使用しない
- リクエスト/レスポンス本文全体をログに記録しない
- 本番環境で print 文を使用しない
実装
ロギングを実装する際:
- 既存のパターンを発見: プロジェクトの現在のロギング方法を確認
- 最新ライブラリをリサーチ:
WebSearch: "[言語] structured logging library [year]"
- プロジェクトの慣例に従う: 既存のログ形式とスタイルに合わせる
メトリクス
メトリクスタイプ
| タイプ | 使用場面 | 例 |
|---|
| Counter | 累積値（増加のみ） | リクエスト数、エラー数 |
| Gauge | ポイントインタイム値（増減あり） | アクティブ接続数、キューサイズ |
| Histogram | 値の分布 | リクエストレイテンシー、レスポンスサイズ |
| Summary | 事前計算されたパーセンタイル | p50、p99 レイテンシー |
命名規則
形式: <namespace>_<name>_<unit>
良い例:
- http_requests_total
- http_request_duration_seconds
- database_connections_active
- queue_messages_waiting
悪い例:
- requests (名前空間なし、単位なし)
- httpRequestDuration (camelCase、不統一)
- request-latency (ハイフン、単位なし)
主要メトリクスフレームワーク
RED メソッド（リクエスト指向）:
- Rate: 1 秒あたりのリクエスト数
- Errors: エラー率
- Duration: レイテンシーパーセンタイル
USE メソッド（リソース指向）:
- Utilization: ビジー状態の割合
- Saturation: キュー長/バックログ
- Errors: エラー件数
Four Golden Signals:
- レイテンシー: リクエスト処理時間
- トラフィック: システムへの需要
- エラー: 失敗リクエストの割合
- サチュレーション: システムの「飽和度」
実装
メトリクスを実装する際:
- 測定対象を特定: RED/USE/Golden Signals をガイドとして使用
- 既存のセットアップを発見: プロジェクトにメトリクス基盤があるか確認
- 最新ツールをリサーチ:
WebSearch: "[言語] metrics library [year]"
WebSearch: "metrics collection [インフラストラクチャ] [year]"
分散トレーシング
トレースの概念
Trace（リクエスト全体の旅程）
├── Span A: API Gateway（親）
│ ├── Span B: Auth Service
│ └── Span C: User Service
│ └── Span D: Database Query
- Trace: サービス間のエンドツーエンドのリクエスト旅程
- Span: トレース内の単一操作
- Context: 伝播されるトレース/スパン ID
トレースコンテキスト伝播
コンテキスト伝播の標準ヘッダー:
| 標準 | 説明 |
|---|
| W3C Trace Context | モダンな標準（traceparent、tracestate） |
| B3 | Zipkin 形式（X-B3-* ヘッダー） |
ベストプラクティス
- 全サービス境界でトレースコンテキストを伝播
- 相関のためにログにトレース ID を含める
- 高トラフィック環境ではトレースをサンプリング
- 意味のあるスパン名と属性を追加
実装
トレーシングを実装する際:
- 既存のセットアップを確認: プロジェクトに既にトレーシングがあるか
- 最新の標準をリサーチ:
WebSearch: "distributed tracing [言語] [year]"
WebSearch: "[トレーシングプラットフォーム] integration guide"
ヘルスチェック
エンドポイント設計
{
"status": "healthy|degraded|unhealthy",
"version": "アプリバージョン",
"uptime_seconds": 3600,
"checks": {
"database": {
"status": "healthy",
"latency_ms": 5
},
"cache": {
"status": "healthy",
"latency_ms": 2
},
"external_api": {
"status": "degraded",
"message": "High latency"
}
}
}
Kubernetes ヘルスチェック
| チェック | 目的 | 失敗時のアクション |
|---|
| Liveness | アプリは動作しているか？ | コンテナを再起動 |
| Readiness | リクエストを処理できるか？ | ロードバランサーから除外 |
| Startup | アプリは起動したか？ | まだ liveness をチェックしない |
アラート
アラート設計原則
良いアラートに含まれるもの:
- 明確でアクション可能な名前
- 持続時間付き閾値（フラッピング防止）
- 重大度レベル
- ランブックへのリンク
- 関連ラベル/コンテキスト
避けるべきこと:
- フラッピングアラート（過敏すぎる閾値）
- 症状だけのアラート（根本原因を掘り下げる）
- 多すぎるアラート（アラート疲れ）
- ランブックなしのアラート
SLO ベースのアラート
SLI: 99.9% のリクエストが 200ms 以内に完了
SLO: 30 日間で 99.9% の成功率
エラーバジェット: 0.1% = 約 43 分/月
アラート条件:
- バーンレート > 1x: スローバーン、低重大度
- バーンレート > 10x: ファストバーン、高重大度
実装チェックリスト
Rules (L1 - Hard)
セキュリティと運用の安全性に不可欠。
- NEVER: 機密データをログに記録しない（PII、トークン、パスワード） - セキュリティ要件
- ALWAYS: サービス間でトレースコンテキストを伝播する（デバッグを可能にする）
- ALWAYS: ログに相関 ID を含める（リクエストトレーシング）
Defaults (L2 - Soft)
運用品質に重要。適切な理由がある場合はオーバーライド可。
- 構造化ロギングを使用する（print/console.log ではなく）
- オーケストレーション用のヘルスチェックエンドポイントを公開する
- 実装前に既存のプロジェクトパターンを発見する
- 最新ライブラリの推奨には WebSearch を使用する
- アラートにランブックをリンクする
Guidelines (L3)
包括的なオブザーバビリティのための推奨事項。
- consider: メトリクスに RED/USE/Golden Signals フレームワークの使用を検討
- prefer: 高トラフィック環境ではトレースのサンプリングを推奨
- consider: 閾値ベースより SLO ベースのアラートを検討
