| name | operability-observation |
| context | fork |
| description | 運用観測性の確保。ログ、メトリクス、ヘルスチェック、設定検証でバグを扱う能力を担保。Use when: デプロイ前チェック、障害調査が困難、原因不明、ログ設計、メトリクス設計、設定管理実装。 |
Operability Observation（運用観測性）
目的
運用不能は「バグそのもの」ではなく、バグや障害を扱う能力の欠如。
このスキルは、MTTR（復旧時間）を下げ、フィードバックループを閉じる。
観測の恩恵
- MTTR（復旧時間）を下げる
- 失敗が起きたときの"次の一手"が見える
- 本番でのフィードバックが仕様・テストへ戻り、精度向上ループが閉じる
Procedure
Step 1: 起動時設定検証（Fail Fast）
設定が検証されず起動後に壊れるのを防ぐ。必須設定の欠落、型・範囲・形式の不正を起動時に検知し、検証に失敗したら即座に終了する。
Step 2: ヘルスチェックの実装
オーケストレータが正しく扱えるようにする：
@app.get("/health/live")
def liveness():
return {"status": "ok"}
@app.get("/health/ready")
async def readiness():
checks = {
"database": await check_db_connection(),
"cache": await check_cache_connection(),
"external_api": await check_external_api(),
}
all_healthy = all(checks.values())
status_code = 200 if all_healthy else 503
return JSONResponse(
status_code=status_code,
content={"status": "ready" if all_healthy else "not_ready", "checks": checks}
)
Step 3: 構造化ログの実装
相関ID、操作名、結果、エラー分類を含めた構造化ログ（JSON形式）を出力する。エラーログにはエラー分類（validation_error / policy_violation / invariant_broken 等）を含める。
Step 4: 基本メトリクスの設定
最低限必要なメトリクス：
| メトリクス | 種別 | 説明 |
|---|
| request_latency_seconds | Histogram | リクエスト処理時間 |
| request_total | Counter | リクエスト数（status, endpoint別） |
| error_total | Counter | エラー数（error_type別） |
| active_connections | Gauge | アクティブ接続数 |
| queue_depth | Gauge | キュー深度（飽和の兆候） |
Step 5: エラー分類の設計
エラーを適切に分類し、対処可能にする：
| エラー分類 | 説明 | 対処 |
|---|
| validation_error | 入力検証失敗 | クライアント修正 |
| policy_violation | ビジネスルール違反 | 操作変更 |
| invariant_broken | 内部整合性違反 | 調査必要 |
| external_error | 外部システム障害 | リトライ/待機 |
| internal_error | 内部エラー | 即座に調査 |
最小セット
- (F1) 起動時設定検証（fail fast）
- (F2) ヘルスチェック（liveness/readiness）
- (F3) 構造化ログ ＋ 相関ID ＋ エラー分類
- (F4) 最低限のメトリクス（エラー率・レイテンシ・飽和のどれか2つでも）
運用チェックリスト
詳細は references/operability-checklist.md を参照。
Outputs
- 設定スキーマ（Pydantic / Zod / JSON Schema等）
- ヘルスチェックエンドポイント実装
- 構造化ログ設定
- メトリクス設定
- エラー分類定義
Examples
Kubernetes ヘルスチェック設定
Liveness/Readinessプローブの設定例は references/operability-checklist.md を参照。
