監視

Claude CodeはOpenTelemetry（OTel）メトリクスとイベントを監視と可観測性のためにサポートしています。

すべてのメトリクスはOpenTelemetryの標準メトリクスプロトコルを介してエクスポートされる時系列データであり、イベントはOpenTelemetryのログ/イベントプロトコルを介してエクスポートされます。メトリクスとログのバックエンドが適切に設定され、集約の粒度が監視要件を満たしていることを確認するのはユーザーの責任です。

​

クイックスタート

環境変数を使用してOpenTelemetryを設定します：

# 1. テレメトリを有効化
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. エクスポーターを選択（両方ともオプション - 必要なもののみ設定）
export OTEL_METRICS_EXPORTER=otlp       # オプション: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # オプション: otlp, console

# 3. OTLPエンドポイントを設定（OTLPエクスポーター用）
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. 認証を設定（必要な場合）
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. デバッグ用：エクスポート間隔を短縮
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10秒（デフォルト: 60000ms）
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5秒（デフォルト: 5000ms）

# 6. Claude Codeを実行
claude

完全な設定オプションについては、OpenTelemetry仕様を参照してください。

​

管理者設定

管理者は、管理設定ファイルを通じてすべてのユーザーのOpenTelemetry設定を構成できます。これにより、組織全体でテレメトリ設定を一元管理できます。設定の適用方法の詳細については、設定の優先順位を参照してください。

管理設定ファイルの場所：

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• LinuxおよびWSL: /etc/claude-code/managed-settings.json
• Windows: C:\ProgramData\ClaudeCode\managed-settings.json

管理設定の設定例：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

​

設定の詳細

​

共通設定変数

​

メトリクスカーディナリティ制御

以下の環境変数は、カーディナリティを管理するためにメトリクスに含まれる属性を制御します：

これらの変数は、メトリクスのカーディナリティを制御するのに役立ちます。これは、メトリクスバックエンドでのストレージ要件とクエリパフォーマンスに影響します。一般的に、カーディナリティが低いほどパフォーマンスが向上し、ストレージコストが削減されますが、分析用のデータの粒度は低くなります。

​

動的ヘッダー

動的認証が必要なエンタープライズ環境では、ヘッダーを動的に生成するスクリプトを設定できます：

​

設定の構成

.claude/settings.jsonに追加：

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​

スクリプト要件

スクリプトは、HTTPヘッダーを表す文字列のキー値ペアを含む有効なJSONを出力する必要があります：

#!/bin/bash
# 例：複数のヘッダー
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​

重要な制限事項

ヘッダーは起動時にのみ取得され、実行時には取得されません。 これは、OpenTelemetryエクスポーターアーキテクチャの制限によるものです。

頻繁なトークン更新が必要なシナリオでは、独自のヘッダーを更新できるプロキシとしてOpenTelemetry Collectorを使用してください。

​

マルチチーム組織サポート

複数のチームや部門を持つ組織は、OTEL_RESOURCE_ATTRIBUTES環境変数を使用して、異なるグループを区別するためのカスタム属性を追加できます：

# チーム識別用のカスタム属性を追加
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

これらのカスタム属性はすべてのメトリクスとイベントに含まれ、以下のことが可能になります：

• チームや部門でメトリクスをフィルタリング
• コストセンターごとのコスト追跡
• チーム固有のダッシュボード作成
• 特定のチーム向けのアラート設定

# ❌ 無効 - スペースを含む
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ 有効 - 代わりにアンダースコアやキャメルケースを使用
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ 有効 - 必要に応じて特殊文字をパーセントエンコード
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

設定例

# コンソールデバッグ（1秒間隔）
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# 複数のエクスポーター
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# メトリクスとログで異なるエンドポイント/バックエンド
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

# メトリクスのみ（イベント/ログなし）
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# イベント/ログのみ（メトリクスなし）
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

​

利用可能なメトリクスとイベント

​

標準属性

すべてのメトリクスとイベントは、これらの標準属性を共有します：

​

メトリクス

Claude Codeは以下のメトリクスをエクスポートします：

​

メトリクスの詳細

​

セッションカウンター

各セッション開始時に増加します。

属性：

• すべての標準属性

​

コード行数カウンター

コードが追加または削除されたときに増加します。

属性：

• すべての標準属性
• type: ("added", "removed")

​

プルリクエストカウンター

Claude Code経由でプルリクエストを作成したときに増加します。

属性：

• すべての標準属性

​

コミットカウンター

Claude Code経由でgitコミットを作成したときに増加します。

属性：

• すべての標準属性

​

コストカウンター

各APIリクエスト後に増加します。

属性：

• すべての標準属性
• model: モデル識別子（例：“claude-3-5-sonnet-20241022”）

​

トークンカウンター

各APIリクエスト後に増加します。

属性：

• すべての標準属性
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: モデル識別子（例：“claude-3-5-sonnet-20241022”）

​

コード編集ツール決定カウンター

ユーザーがEdit、MultiEdit、Write、またはNotebookEditツールの使用を承認または拒否したときに増加します。

属性：

• すべての標準属性
• tool: ツール名（"Edit", "MultiEdit", "Write", "NotebookEdit"）
• decision: ユーザーの決定（"accept", "reject"）
• language: 編集されたファイルのプログラミング言語（例："TypeScript", "Python", "JavaScript", "Markdown"）。認識されないファイル拡張子の場合は"unknown"を返します。

​

アクティブ時間カウンター

Claude Codeを実際にアクティブに使用した時間を追跡します（アイドル時間ではありません）。このメトリクスは、プロンプトの入力や応答の受信などのユーザーインタラクション中に増加します。

属性：

• すべての標準属性

​

イベント

Claude Codeは、OpenTelemetryログ/イベント（OTEL_LOGS_EXPORTERが設定されている場合）を介して以下のイベントをエクスポートします：

​

ユーザープロンプトイベント

ユーザーがプロンプトを送信したときにログに記録されます。

イベント名: claude_code.user_prompt

属性：

• すべての標準属性
• event.name: "user_prompt"
• event.timestamp: ISO 8601タイムスタンプ
• prompt_length: プロンプトの長さ
• prompt: プロンプト内容（デフォルトでは編集済み、OTEL_LOG_USER_PROMPTS=1で有効化）

​

ツール結果イベント

ツールの実行が完了したときにログに記録されます。

イベント名: claude_code.tool_result

属性：

• すべての標準属性
• event.name: "tool_result"
• event.timestamp: ISO 8601タイムスタンプ
• tool_name: ツールの名前
• success: "true"または"false"
• duration_ms: 実行時間（ミリ秒）
• error: エラーメッセージ（失敗した場合）
• decision: "accept"または"reject"
• source: 決定ソース - "config", "user_permanent", "user_temporary", "user_abort", または"user_reject"
• tool_parameters: ツール固有のパラメータを含むJSON文字列（利用可能な場合）
  • Bashツールの場合：bash_command, full_command, timeout, description,sandboxを含む

​

APIリクエストイベント

Claudeへの各APIリクエストでログに記録されます。

イベント名: claude_code.api_request

属性：

• すべての標準属性
• event.name: "api_request"
• event.timestamp: ISO 8601タイムスタンプ
• model: 使用されたモデル（例：“claude-3-5-sonnet-20241022”）
• cost_usd: 推定コスト（USD）
• duration_ms: リクエスト時間（ミリ秒）
• input_tokens: 入力トークン数
• output_tokens: 出力トークン数
• cache_read_tokens: キャッシュから読み取られたトークン数
• cache_creation_tokens: キャッシュ作成に使用されたトークン数

​

APIエラーイベント

ClaudeへのAPIリクエストが失敗したときにログに記録されます。

イベント名: claude_code.api_error

属性：

• すべての標準属性
• event.name: "api_error"
• event.timestamp: ISO 8601タイムスタンプ
• model: 使用されたモデル（例：“claude-3-5-sonnet-20241022”）
• error: エラーメッセージ
• status_code: HTTPステータスコード（該当する場合）
• duration_ms: リクエスト時間（ミリ秒）
• attempt: 試行回数（再試行されたリクエストの場合）

​

ツール決定イベント

ツール許可決定（承認/拒否）が行われたときにログに記録されます。

イベント名: claude_code.tool_decision

属性：

• すべての標準属性
• event.name: "tool_decision"
• event.timestamp: ISO 8601タイムスタンプ
• tool_name: ツールの名前（例：“Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit”など）
• decision: "accept"または"reject"
• source: 決定ソース - "config", "user_permanent", "user_temporary", "user_abort", または"user_reject"

​

メトリクスとイベントデータの解釈

Claude Codeによってエクスポートされるメトリクスは、使用パターンと生産性に関する貴重な洞察を提供します。作成できる一般的な可視化と分析は以下の通りです：

​

使用状況監視

​

コスト監視

claude_code.cost.usageメトリクスは以下に役立ちます：

• チームや個人間での使用傾向の追跡
• 最適化のための高使用セッションの特定

​

アラートとセグメンテーション

検討すべき一般的なアラート：

• コストの急増
• 異常なトークン消費
• 特定のユーザーからの高セッション量

すべてのメトリクスは、user.account_uuid、organization.id、session.id、model、app.versionでセグメント化できます。

​

イベント分析

イベントデータは、Claude Codeのインタラクションに関する詳細な洞察を提供します：

ツール使用パターン: ツール結果イベントを分析して以下を特定：

• 最も頻繁に使用されるツール
• ツールの成功率
• 平均ツール実行時間
• ツールタイプ別のエラーパターン

パフォーマンス監視: APIリクエスト時間とツール実行時間を追跡して、パフォーマンスのボトルネックを特定します。

​

バックエンドの考慮事項

メトリクスとログのバックエンドの選択により、実行できる分析のタイプが決まります：

​

メトリクス用：

• 時系列データベース（例：Prometheus）: レート計算、集約メトリクス
• 列指向ストア（例：ClickHouse）: 複雑なクエリ、ユニークユーザー分析
• フル機能可観測性プラットフォーム（例：Honeycomb、Datadog）: 高度なクエリ、可視化、アラート

​

イベント/ログ用：

• ログ集約システム（例：Elasticsearch、Loki）: 全文検索、ログ分析
• 列指向ストア（例：ClickHouse）: 構造化イベント分析
• フル機能可観測性プラットフォーム（例：Honeycomb、Datadog）: メトリクスとイベント間の相関

日次/週次/月次アクティブユーザー（DAU/WAU/MAU）メトリクスが必要な組織では、効率的なユニーク値クエリをサポートするバックエンドを検討してください。

​

サービス情報

すべてのメトリクスとイベントは、以下のリソース属性とともにエクスポートされます：

• service.name: claude-code
• service.version: 現在のClaude Codeバージョン
• os.type: オペレーティングシステムタイプ（例：linux, darwin, windows）
• os.version: オペレーティングシステムバージョン文字列
• host.arch: ホストアーキテクチャ（例：amd64, arm64）
• wsl.version: WSLバージョン番号（Windows Subsystem for Linux上で実行している場合のみ存在）
• メーター名: com.anthropic.claude_code

​

ROI測定リソース

テレメトリセットアップ、コスト分析、生産性メトリクス、自動レポートを含む、Claude CodeのROI（投資収益率）測定に関する包括的なガイドについては、Claude Code ROI測定ガイドを参照してください。このリポジトリは、すぐに使用できるDocker Compose設定、PrometheusとOpenTelemetryのセットアップ、およびLinearなどのツールと統合された生産性レポート生成用のテンプレートを提供します。

​

セキュリティ/プライバシーの考慮事項

• テレメトリはオプトインであり、明示的な設定が必要です
• APIキーやファイル内容などの機密情報は、メトリクスやイベントに含まれることはありません
• ユーザープロンプト内容はデフォルトで編集されます - プロンプトの長さのみが記録されます。ユーザープロンプトログを有効にするには、OTEL_LOG_USER_PROMPTS=1を設定してください