モニタリング

​

クイックスタート

# 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

​

管理者設定

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux and 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"
  }
}

​

設定の詳細

​

一般的な設定変数

​

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

​

動的ヘッダー

​

設定の設定

{
  "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.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

​

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

​

標準属性

​

メトリクス

​

メトリクスの詳細

​

セッションカウンター

• すべての標準属性

​

コード行カウンター

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

​

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

• すべての標準属性

​

コミットカウンター

• すべての標準属性

​

コストカウンター

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

​

トークンカウンター

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

​

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

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

​

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

• すべての標準属性

​

イベント

​

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

• すべての標準属性
• event.name: "user_prompt"
• event.timestamp: ISO 8601タイムスタンプ
• prompt_length: プロンプトの長さ
• prompt: プロンプトコンテンツ (デフォルトではマスクされています。OTEL_LOG_USER_PROMPTS=1で有効にします)

​

ツール結果イベント

• すべての標準属性
• 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リクエストイベント

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

​

APIエラーイベント

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

​

ツール決定イベント

• すべての標準属性
• event.name: "tool_decision"
• event.timestamp: ISO 8601タイムスタンプ
• tool_name: ツールの名前 (例: “Read”, “Edit”, “Write”, “NotebookEdit”など)
• decision: "accept" または "reject"
• source: 決定ソース - "config", "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測定リソース

​

セキュリティ/プライバシーに関する考慮事項

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

​

Amazon Bedrock上のClaude Codeのモニタリング