監視

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: /etc/claude-code/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"
  }
}

​

設定の詳細

​

一般的な設定変数

​

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

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

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

​

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

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

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

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

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

​

設定例

# コンソールデバッグ（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は、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タイムスタンプ
• name: ツールの名前
• success: "true"または"false"
• duration_ms: 実行時間（ミリ秒）
• error: エラーメッセージ（失敗した場合）

​

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）メトリクスが必要な組織の場合、効率的なユニーク値クエリをサポートするバックエンドを検討してください。

​

サービス情報

すべてのメトリクスは以下でエクスポートされます：

• サービス名: claude-code
• サービスバージョン: 現在のClaude Codeバージョン
• メーター名: com.anthropic.claude_code

​

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

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