監視

​

クイックスタート

# 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

​

管理者設定

{
  "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.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

​

設定の詳細

​

一般的な設定変数

​

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

​

動的ヘッダー

​

設定ファイルの設定

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

​

スクリプト要件

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

​

リフレッシュ動作

​

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

# チーム識別用のカスタム属性を追加する
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.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.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

​

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

​

標準属性

• prompt.id: ユーザープロンプトを次のプロンプトまでのすべての後続イベントと相関させる UUID。イベント相関属性を参照してください。
• workspace.host_paths: デスクトップアプリで選択されたホストワークスペースディレクトリ (文字列配列として)

​

メトリクス

​

メトリクスの詳細

​

セッションカウンター

• すべての標準属性

​

コード行カウンター

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

​

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

• すべての標準属性

​

コミットカウンター

• すべての標準属性

​

コストカウンター

• すべての標準属性
• model: モデル識別子 (例: “claude-sonnet-4-6”)

​

トークンカウンター

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

​

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

• すべての標準属性
• tool_name: ツール名 ("Edit", "Write", "NotebookEdit")
• decision: ユーザーの決定 ("accept", "reject")
• source: 決定ソース - "config", "hook", "user_permanent", "user_temporary", "user_abort", または "user_reject"
• language: 編集されたファイルのプログラミング言語。例: "TypeScript", "Python", "JavaScript", "Markdown"。認識されないファイル拡張子の場合は "unknown" を返します。

​

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

• すべての標準属性
• type: キーボードインタラクションの場合は "user"、ツール実行と AI 応答の場合は "cli"

​

イベント

​

イベント相関属性

​

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

• すべての標準属性
• event.name: "user_prompt"
• event.timestamp: ISO 8601 タイムスタンプ
• event.sequence: セッション内のイベントを順序付けするための単調増加カウンター
• prompt_length: プロンプトの長さ
• prompt: プロンプトコンテンツ (デフォルトではマスク、OTEL_LOG_USER_PROMPTS=1 で有効化)

​

ツール結果イベント

• すべての標準属性
• event.name: "tool_result"
• event.timestamp: ISO 8601 タイムスタンプ
• event.sequence: セッション内のイベントを順序付けするための単調増加カウンター
• tool_name: ツールの名前
• success: "true" または "false"
• duration_ms: 実行時間 (ミリ秒単位)
• error: エラーメッセージ (失敗した場合)
• decision_type: "accept" または "reject"
• decision_source: 決定ソース - "config", "hook", "user_permanent", "user_temporary", "user_abort", または "user_reject"
• tool_result_size_bytes: ツール結果のサイズ (バイト単位)
• mcp_server_scope: MCP サーバースコープ識別子 (MCP ツール用)
• tool_parameters: ツール固有のパラメーターを含む JSON 文字列 (利用可能な場合)
  • Bash ツールの場合: bash_command, full_command, timeout, description, dangerouslyDisableSandbox, および git_commit_id (git commit コマンドが成功した場合のコミット SHA) を含む
  • MCP ツール (OTEL_LOG_TOOL_DETAILS=1 の場合): mcp_server_name, mcp_tool_name を含む
  • Skill ツール (OTEL_LOG_TOOL_DETAILS=1 の場合): skill_name を含む
• tool_input (OTEL_LOG_TOOL_DETAILS=1 の場合): JSON シリアル化されたツール引数。512 文字を超える個別の値は切り詰められ、全体のペイロードは約 4 K 文字に制限されます。すべてのツール (MCP ツールを含む) に適用されます。

​

API リクエストイベント

• すべての標準属性
• event.name: "api_request"
• event.timestamp: ISO 8601 タイムスタンプ
• event.sequence: セッション内のイベントを順序付けするための単調増加カウンター
• model: 使用されたモデル (例: “claude-sonnet-4-6”)
• cost_usd: 推定コスト (USD)
• duration_ms: リクエスト期間 (ミリ秒単位)
• input_tokens: 入力トークンの数
• output_tokens: 出力トークンの数
• cache_read_tokens: キャッシュから読み取られたトークンの数
• cache_creation_tokens: キャッシュ作成に使用されたトークンの数
• speed: "fast" または "normal"、高速モードがアクティブであったかどうかを示します

​

API エラーイベント

• すべての標準属性
• event.name: "api_error"
• event.timestamp: ISO 8601 タイムスタンプ
• event.sequence: セッション内のイベントを順序付けするための単調増加カウンター
• model: 使用されたモデル (例: “claude-sonnet-4-6”)
• error: エラーメッセージ
• status_code: HTTP ステータスコード (文字列)、または非 HTTP エラーの場合は "undefined"
• duration_ms: リクエスト期間 (ミリ秒単位)
• attempt: 試行番号 (再試行されたリクエストの場合)
• speed: "fast" または "normal"、高速モードがアクティブであったかどうかを示します

​

ツール決定イベント

• すべての標準属性
• event.name: "tool_decision"
• event.timestamp: ISO 8601 タイムスタンプ
• event.sequence: セッション内のイベントを順序付けするための単調増加カウンター
• tool_name: ツールの名前 (例: “Read”, “Edit”, “Write”, “NotebookEdit”)
• decision: "accept" または "reject"
• source: 決定ソース - "config", "hook", "user_permanent", "user_temporary", "user_abort", または "user_reject"

​

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

​

使用状況監視

​

コスト監視

• チームまたは個人全体の使用トレンドを追跡する
• 最適化のための高使用セッションを特定する

​

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

• コストスパイク
• 異常なトークン消費
• 特定のユーザーからの高いセッションボリューム

​

イベント分析

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

​

バックエンドに関する考慮事項

​

メトリクスの場合

• 時系列データベース (例: Prometheus): レート計算、集約メトリクス
• カラムナーストア (例: ClickHouse): 複雑なクエリ、一意のユーザー分析
• フル機能の可観測性プラットフォーム (例: Honeycomb、Datadog): 高度なクエリ、可視化、アラート

​

イベント/ログの場合

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

​

サービス情報

• 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 測定リソース

​

セキュリティとプライバシー

• テレメトリはオプトインであり、明示的な設定が必要です
• 生のファイルコンテンツとコードスニペットはメトリクスやイベントに含まれません。ツール実行イベントには bash コマンドとファイルパスが tool_parameters フィールドに含まれ、機密値を含む可能性があります。コマンドにシークレットが含まれる可能性がある場合は、テレメトリバックエンドを設定して tool_parameters をフィルタリングまたはマスクしてください
• OAuth 経由で認証された場合、user.email はテレメトリ属性に含まれます。これが組織にとって懸念事項である場合は、テレメトリバックエンドと協力してこのフィールドをフィルタリングまたはマスクしてください
• ユーザープロンプトコンテンツはデフォルトでは収集されません。プロンプト長のみが記録されます。プロンプトコンテンツを含めるには、OTEL_LOG_USER_PROMPTS=1 を設定します
• ツール入力引数はデフォルトではログされません。これらを含めるには、OTEL_LOG_TOOL_DETAILS=1 を設定します。有効にすると、tool_result イベントには MCP サーバー/ツール名とスキル名、およびファイルパス、URL、検索パターン、その他の引数を含む tool_input 属性が含まれます。512 文字を超える個別の値は切り詰められ、合計は約 4 K 文字に制限されますが、引数には機密値が含まれる可能性があります。必要に応じて tool_input をフィルタリングまたはマスクするようにテレメトリバックエンドを設定してください

​

Amazon Bedrock での Claude Code の監視