Claude Code を組織で運用する際、「何を監視すれば良いか」「どの時点でアラートを出すべきか」という判断に迷う場面は少なくありません。私がこれまで複数の企業で SRE チームと導入を進めてきた中でも、最初は開発者個人のツールとして扱い、可観測性基盤への組み込みが後回しになるケースをたびたび目にしてきました。しかし Claude Code が日常的なコーディング業務の一部となり、チーム全体の開発速度やコスト構造に影響を与えるようになると、メトリクス・ログ・トレースの三本柱を統合的に監視する体制が欠かせません。本記事では、可観測性基盤の設計原則から具体的なダッシュボード構成、アラート設計のしきい値設定までを実務的に解説します。

i

本記事の結論: Claude Code の可観測性は、メトリクス（ゴールデンシグナル）・ログ（構造化 JSON）・トレース（リクエスト単位の文脈）を OpenTelemetry で統合し、P95 レイテンシと成功率を主要 SLI として監視することで、異常の早期発見とコスト最適化を両立できる

なぜ Claude Code に可観測性基盤が必要か

Claude Code は API 経由で外部サービスと連携するため、ネットワーク遅延・レート制限・モデル応答時間の変動が開発者の待機時間に直結します。可観測性が不足していると、以下のような課題が顕在化します。

  • パフォーマンス劣化の原因特定が遅れる: 開発者が「遅い」と感じても、ネットワークの問題なのか、リクエストペイロードが大きすぎるのか、モデル側の混雑なのかを切り分けられない
  • コスト超過に気づくのが月次請求後: トークン消費量の急増をリアルタイムで検知できず、予算オーバーが発覚するのが請求書到着時になる
  • 障害時のエスカレーションパスが不明確: アラートが鳴っても、誰がどの順序で対応するか定義されておらず、復旧に時間がかかる

可観測性基盤は、これらの問題を「データが見える」「異常を自動検知できる」「対応者が明確」の 3 層で解決します。

三本柱の設計原則

可観測性の三本柱（メトリクス・ログ・トレース）は、それぞれ異なる視点で Claude Code の健全性を評価します。

メトリクス: 時系列の集約指標

メトリクスは、一定期間内の 集約値 を数値として記録します。多くの組織では以下の観点を主要指標とする傾向があります。

  • レイテンシ: P50 / P95 / P99。条件によっては P95 を主要 SLI とする組織が多い
  • 成功率: HTTP 200 系レスポンスの割合。95% 以上を目標とするケースが一般的
  • スループット: 分あたりのリクエスト数（RPM）。急激な増加はトークン消費の兆候
  • トークン消費量: プロンプト＋補完トークンの合算。予算管理に直結

ログ: 事象の詳細記録

ログは 個別の事象 を構造化 JSON で記録し、後から検索・分析可能にします。

  • 構造化必須: timestamp, user_id, request_id, model, tokens, latency_ms, status_code などのフィールドを統一
  • PII 除外: ユーザーのプロンプト内容は記録せず、メタデータのみ保持（監査ログ との使い分けが重要）
  • 検索性: Elasticsearch や Splunk などで時刻範囲・ユーザー・エラーコード別に絞り込めるようにする

トレース: リクエスト単位の文脈

トレースは、単一のリクエストが システム全体をどう流れたか を可視化します。

  • 分散トレーシング: VS Code 拡張 → プロキシ → Claude API と複数コンポーネントをまたぐ場合、各区間のレイテンシを分離
  • 因果関係の特定: 遅いリクエストがどのステップで遅延したかをスパン単位で把握
  • サンプリング: 全リクエストを記録すると負荷が大きいため、エラー時は全量、正常時は 1〜10% をサンプリングする組織が多い

OpenTelemetry による標準化

可観測性データの収集には、OpenTelemetry（OTel）という標準プロトコルが広く採用されています。

3種類
信号（メトリクス・ログ・トレース）
統一SDK
ベンダー非依存の実装
多様
バックエンド選択（Prometheus/Grafana/Datadog等）

実装の流れ

1. SDK の導入 — Python や Node.js の OpenTelemetry SDK をプロキシ層に組み込む。公式リポジトリ（github.com/open-telemetry）からインストール

2. 計装（Instrumentation） — HTTP リクエストの送受信時にスパンを開始・終了し、属性（http.method, http.status_code, claude.model, claude.tokens）を付与

3. エクスポーター設定 — メトリクスは Prometheus 形式で /metrics エンドポイント公開、ログは Fluentd や Logstash 経由で転送、トレースは Jaeger や Zipkin へ送信

4. バックエンド統合 — Grafana で Prometheus データソースと Loki（ログ）、Tempo（トレース）を同一ダッシュボードに統合

メリット

  • ベンダーロックイン回避: Datadog から Grafana Cloud への移行時も計装コードを変更せずにエクスポーターだけ差し替え
  • 一貫性: メトリクス・ログ・トレースの request_id を共通キーとして紐付け、クリック 1 つでログからトレースへジャンプ可能
  • コミュニティ資産: 主要な APM ベンダーが OTel をサポートしており、将来的な拡張性が高い

ダッシュボード構成例: ゴールデンシグナル

Google SRE の「ゴールデンシグナル」（Latency / Traffic / Errors / Saturation）を Claude Code に適用すると、以下のパネル構成が有効です。

シグナル メトリクス名 表示形式 目安のしきい値
Latency claude_request_duration_seconds (P95) 時系列グラフ 3秒以上で警告
Traffic claude_requests_per_minute カウンター 急増時に通知（前週比+50%など）
Errors claude_requests_total{status="error"} 積み上げ面グラフ 成功率95%未満で警告
Saturation claude_tokens_consumed_total ゲージ 月次予算の80%到達で警告

画面レイアウトの例

┌─────────────────────────────────────────────┐
│ P95 Latency (過去24h)          │ 成功率 (%)│
├─────────────────────────────────────────────┤
│ RPM (Requests Per Minute)                   │
├─────────────────────────────────────────────┤
│ トークン消費量 (日次累積)                    │
├─────────────────────────────────────────────┤
│ エラー内訳 (rate_limit / timeout / other)   │
└─────────────────────────────────────────────┘

各パネルには ドリルダウンリンク を設定し、異常値をクリックするとログクエリや Trace ID へジャンプできるようにします。詳細な利用状況の分析は 使用状況分析 も参照してください。

異常検知のしきい値設定方法

しきい値は組織の要件により異なりますが、以下のステップで段階的に調整する方法が現実的です。

1. ベースライン計測 — 2〜4週間の通常運用時のデータを収集し、P50 / P95 / P99 の分布を把握

2. 初期しきい値の仮設定 — P95 レイテンシがベースラインの 1.5〜2倍、成功率が 95% を下回った場合に警告アラート

3. 誤検知の調整 — 週次でアラート履歴をレビューし、誤検知が多ければしきい値を緩和、見逃しが多ければ厳格化

4. 複合条件の追加 — 単一メトリクスだけでなく「P95 が 5秒以上 かつ エラー率 10% 以上」のように AND 条件で精度向上

条件によって異なる例

  • 本番環境: P95 が 3秒以上で Slack 通知、5秒以上で PagerDuty ページ
  • 開発環境: P95 が 10秒以上で Slack のみ（ページ不要）
  • 夜間バッチ: レイテンシは許容するがエラー率 5% 以上で即通知
⚠

注意: しきい値を厳しくしすぎると「常にアラートが鳴る」状態となり、オンコール担当者が疲弊します。初期は「明らかな異常のみ」を検知する設定から始め、運用成熟度に応じて段階的に拡充してください。

アラート設計とエスカレーションパス

アラートは「誰が」「いつ」「どう対応するか」まで定義して初めて機能します。

アラートレベルの分類

レベル 条件例 通知先 応答時間
Info トークン消費 80% 到達 Slack #claude-ops 翌営業日
Warning P95 が 5秒以上、3分継続 Slack + Email 30分以内
Critical 成功率 90% 未満、5分継続 PagerDuty → オンコール担当 15分以内

エスカレーションパスの例

1次対応（5分以内） — プラットフォームチームのオンコール担当が PagerDuty で受信。ダッシュボードでメトリクス確認

2次対応（15分以内に未解決） — SRE リードへエスカレート。ログとトレースから根本原因を調査

3次対応（30分以内に未解決） — DevOps マネージャーと CTO へエスカレート。外部ベンダー（Anthropic）へのサポートチケット起票を判断

オンコール運用全般の設計は オンコール運用 で詳述しています。

アラート疲れ対策

  • サイレント期間（Mute）: 定期メンテナンス中は一時的にアラート停止
  • アノマリー検知: 機械学習ベースの異常検知（Datadog Anomaly Monitor など）で動的にしきい値を調整
  • アラートのグルーピング: 同一 incident で複数のメトリクスが同時異常を示した場合、1つの通知にまとめる

ログとトレースの相関分析

メトリクスで異常を検知した後、ログとトレース を横断的に分析することで根本原因を特定します。

分析シナリオ例

  1. P95 レイテンシが急上昇 — Grafana でメトリクスのスパイクを確認
  2. 該当時刻のログを抽出 — Loki で latency_ms > 5000 のログ一覧を表示
  3. request_id からトレースへジャンプ — Tempo で該当リクエストのスパン詳細を確認し、「Claude API 呼び出し」のスパンが 4.8秒を占めていることを特定
  4. 根本原因の仮説 — モデル側の混雑またはリクエストペイロードが大きすぎる可能性。ペイロードサイズのメトリクスを追加監視対象に

相関キーの設計

すべてのメトリクス・ログ・トレースに共通の request_id を付与し、以下のフィールドを統一します。

  • timestamp: ISO 8601 形式（UTC）
  • user_id: 匿名化 ID
  • model: 使用モデル名（例: claude-3-5-sonnet-20241022）
  • tokens: プロンプト＋補完トークン合算
  • latency_ms: リクエスト送信〜レスポンス受信までのミリ秒

トークン消費の予測とキャパシティプランニング

可観測性基盤は、過去のトレンドから 将来のトークン消費量 を予測し、予算超過を未然に防ぐ役割も担います。

予測手法の例

  • 線形回帰: 過去 4週間の日次トークン消費量から週次増加率を算出し、月次予算到達日を予測
  • 季節性補正: 月末や四半期末にトークン消費が増える傾向がある場合、移動平均で補正
  • 異常値除外: 実験的な大量リクエストが単発で発生した日はデータから除外
i

参考: Prometheus の predict_linear() 関数を使うと、過去の時系列データから数日後の値を予測できます。予測値が予算の 90% に達する日が 7日以内なら早期警告を出す、といった運用が可能です。

まとめ

Claude Code の可観測性基盤は、メトリクス・ログ・トレースを OpenTelemetry で統合し、ゴールデンシグナルを主軸としたダッシュボードで監視することで、異常の早期発見とコスト最適化を両立できます。多くの組織では P95 レイテンシと成功率を主要 SLI とし、しきい値を段階的に調整しながら運用成熟度を高めています。アラート設計ではエスカレーションパスを明確化し、アラート疲れを防ぐためのサイレント期間やアノマリー検知を活用することが重要です。

3本柱
メトリクス・ログ・トレース
4シグナル
Latency/Traffic/Errors/Saturation
3段階
エスカレーションパス

デジライズ では、Claude Code の可観測性基盤設計から構築・運用まで一貫して支援しています。OpenTelemetry のベストプラクティス共有やダッシュボードテンプレート提供、オンコールプレイブック策定など、組織の成熟度に応じた伴走型コンサルティングを提供しています。「どのメトリクスを監視すべきか分からない」「アラートが多すぎて対応しきれない」といった課題をお持ちの場合は、無料相談 でまずは現状をお聞かせください。実運用で蓄積したノウハウをもとに、具体的な改善提案をいたします。

関連記事