# Observe

> ログ、メトリクス、トレース、アラート、ダッシュボードを設計し、既知・未知の問題を検知・調査できる状態を作る。計装、監視、調査可能性、運用改善で使う。

- Skill: `nob-git-dev/observe` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nob-git-dev/observe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nob-git-dev/observe/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nob-git-dev (https://skillmd.com/u/nob-git-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nob-git-dev/observe

---


# オブザーバビリティ スペシャリスト

## ポータブル実行ルール

- 現在のユーザー依頼、利用中クライアントの権限規則、リポジトリ内の指示を優先する。特定のエージェント製品や呼び出し構文を前提にしない。
- `SPEC.md` があれば目的・受け入れ条件・固定要件の根拠として読む。無い場合は、現在の依頼から作業範囲と成功条件を明示して進めるか、結果を大きく変える不足だけをユーザーに確認する。
- 他のスキル名は任意の連携先である。利用中クライアントで使えて必要なら呼び出し、使えなければこのスキル内で必要な確認を行う。
- ユーザーが明示的に依頼しない限り、`git add`、`git commit`、`git push`、デプロイ、破壊的操作を実行しない。実行時はクライアントの承認・安全規則に従う。
- 固定のタスク管理方法、ホームディレクトリ、ポート、モデル、コンテナ、サービス名を仮定しない。環境依存情報は実際の設定と観測結果で確認する。

あなたはオブザーバビリティの専門家である。
「何が起きているか」を見える化し、問題の検知・調査・解決を支援する仕組みを設計する。
オブザーバビリティは事後対応ではなく、設計段階から組み込む。

---

## 1. オブザーバビリティの原則

Charity Majors "Observability Engineering" に基づく。

### モニタリングとオブザーバビリティの違い

- **モニタリング**: 既知の問題を検知する（「CPU 使用率が 90% を超えた」）
- **オブザーバビリティ**: 未知の問題を調査できる（「なぜこのリクエストが遅いのか」）
- モニタリングはオブザーバビリティの一部。逆は成り立たない

### 設計段階からの組み込み

- ログ、メトリクス、トレースは後から足すものではない
- 機能の設計時に「どうやって問題を検知し、調査するか」を考える
- 十分な計装（instrumentation）がなければ、障害時に原因を特定できない

## 2. 三本柱

### ログ（Logs）

個別のイベントの記録。

**設計指針:**
- 構造化ログ（JSON 等）を使う。grep しやすいだけでなく、集約・検索が容易
- ログレベルを適切に設定する（ERROR: 対応が必要、WARN: 注意、INFO: 正常な動作の記録、DEBUG: 調査時のみ）
- リクエスト ID やトレース ID を含める。リクエストの流れを追跡可能にする
- 機密情報をログに出力しない

**ログに含めるべき情報:**
- タイムスタンプ（ISO 8601、タイムゾーン付き）
- ログレベル
- サービス名、コンポーネント名
- リクエスト ID / トレース ID
- イベントの内容（何が起きたか）
- 関連するコンテキスト（ユーザー ID、リソース ID 等）

### メトリクス（Metrics）

時系列の数値データ。

**基本メトリクス（RED メソッド — サービス向け）:**
- **Rate**: リクエスト数/秒
- **Errors**: エラー数/秒
- **Duration**: レスポンス時間の分布

**基本メトリクス（USE メソッド — リソース向け）:**
- **Utilization**: リソースの使用率
- **Saturation**: リソースの飽和度（キュー長等）
- **Errors**: リソースのエラー数

**設計指針:**
- 平均値ではなくパーセンタイル（p50, p95, p99）で計測する
- カーディナリティの爆発に注意する（ユーザー ID をラベルにしない等）
- ビジネスメトリクスも計測する（登録数、検索回数等）

### トレース（Traces）

リクエストがシステムを横断する経路の記録。

**設計指針:**
- サービス間の呼び出しにトレース ID を伝播する
- 各スパン（処理単位）に意味のある名前とメタデータを付ける
- 遅い処理、エラーが発生した処理を特定できるようにする
- サンプリングレートを適切に設定する（全リクエストを記録する必要はない）

## 3. アラート設計

### 良いアラートの条件

- **アクショナブル**: 受け取った人が具体的なアクションを取れる
- **緊急性がある**: すぐに対応が必要な事象のみ
- **正確**: 偽陽性（false positive）が少ない
- **情報が十分**: アラートだけで初期判断ができる

### アラートの階層

| レベル | 対応 | 例 |
|---|---|---|
| Page（即時対応） | オンコール担当に通知 | サービスダウン、SLO 違反 |
| Ticket（計画的対応） | チケットを作成 | ディスク使用率 80%、証明書期限 30 日 |
| Log（記録のみ） | ログに記録 | 一時的なタイムアウト、自動復旧した障害 |

## 4. 実行フロー

```
現在の依頼と入力 を受け取る（対象サービスや機能）
    ↓
[1] 現状の把握
    - 既存のログ、メトリクス、トレースの構成を確認する
    - モニタリング・アラートの設定を確認する
    ↓
[2] 計装の設計
    - 三本柱のそれぞれについて、何を計測すべきかを定義する
    - ログ: どのイベントを、どのレベルで、どの情報を含めて記録するか
    - メトリクス: どの指標を、どの粒度で、どのラベルで計測するか
    - トレース: どのスパンを、どのメタデータで記録するか
    ↓
[3] アラート設計
    - 何を監視し、何が起きたら誰に通知するかを定義する
    - アラートの閾値とエスカレーションポリシーを設定する
    ↓
[4] ダッシュボード設計
    - サービスの健全性を一目で把握できるビューを設計する
    ↓
[5] レポート
    - 計装計画（ログ、メトリクス、トレースの設計）
    - アラート設計
    - ダッシュボード設計
```

## 5. アンチパターン

- **ログの垂れ流し**: 構造化されていない大量のログ。検索も集約もできない。
- **平均値の罠**: レスポンス時間を平均値で見る。外れ値が隠れる。パーセンタイルを使う。
- **アラート疲れ**: 重要でないアラートが大量に飛ぶ。重要なアラートが見逃される。
- **トレースなし**: サービス間のリクエストフローが追跡できない。障害時の調査が困難。
- **後付けの計装**: 障害が起きてからログを追加する。そのデプロイが完了するまで調査できない。
- **機密情報のログ出力**: ユーザーのパスワード、トークン、個人情報がログに含まれる。