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

すべてのメトリクスはOpenTelemetryの標準メトリクスプロトコル経由でエクスポートされる時系列データであり、イベントは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

デフォルトのエクスポート間隔は、メトリクスが60秒、ログが5秒です。セットアップ中は、デバッグ目的でより短い間隔を使用することをお勧めします。本番環境では、これらをリセットすることを忘れないでください。

完全な設定オプションについては、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"
  }
}

管理設定は、MDM(モバイルデバイス管理)またはその他のデバイス管理ソリューションを介して配布できます。管理設定ファイルで定義された環境変数は高い優先順位を持ち、ユーザーによって上書きすることはできません。

設定の詳細

共通設定変数

環境変数説明例の値
CLAUDE_CODE_ENABLE_TELEMETRYテレメトリ収集を有効化(必須)1
OTEL_METRICS_EXPORTERメトリクスエクスポータータイプ(カンマ区切り)console, otlp, prometheus
OTEL_LOGS_EXPORTERログ/イベントエクスポータータイプ(カンマ区切り)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLOTLPエクスポーターのプロトコル(すべてのシグナル)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTOTLPコレクターエンドポイント(すべてのシグナル)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLメトリクス用プロトコル(一般設定を上書き)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTOTLPメトリクスエンドポイント(一般設定を上書き)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLログ用プロトコル(一般設定を上書き)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTLPログエンドポイント(一般設定を上書き)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSOTLP用認証ヘッダーAuthorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYmTLS認証用クライアントキークライアントキーファイルへのパス
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATEmTLS認証用クライアント証明書クライアント証明書ファイルへのパス
OTEL_METRIC_EXPORT_INTERVALエクスポート間隔(ミリ秒、デフォルト: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALログエクスポート間隔(ミリ秒、デフォルト: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSユーザープロンプト内容のログ記録を有効化(デフォルト: 無効)有効化するには1

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

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

環境変数説明デフォルト値無効化する例
OTEL_METRICS_INCLUDE_SESSION_IDメトリクスにsession.id属性を含めるtruefalse
OTEL_METRICS_INCLUDE_VERSIONメトリクスにapp.version属性を含めるfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDメトリクスにuser.account_uuid属性を含めるtruefalse

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

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

複数のチームや部門を持つ組織は、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

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

標準属性

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

属性説明制御者
session.id一意のセッション識別子OTEL_METRICS_INCLUDE_SESSION_ID(デフォルト: true)
app.version現在のClaude CodeバージョンOTEL_METRICS_INCLUDE_VERSION(デフォルト: false)
organization.id組織UUID(認証時)利用可能な場合は常に含まれる
user.account_uuidアカウントUUID(認証時)OTEL_METRICS_INCLUDE_ACCOUNT_UUID(デフォルト: true)
terminal.typeターミナルタイプ(例:iTerm.appvscodecursortmux検出された場合は常に含まれる

メトリクス

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

メトリクス名説明単位
claude_code.session.count開始されたCLIセッション数count
claude_code.lines_of_code.count変更されたコード行数count
claude_code.pull_request.count作成されたプルリクエスト数count
claude_code.commit.count作成されたgitコミット数count
claude_code.cost.usageClaude CodeセッションのコストUSD
claude_code.token.usage使用されたトークン数tokens
claude_code.code_edit_tool.decisionコード編集ツール許可決定の数count

メトリクスの詳細

セッションカウンター

各セッションの開始時に発行されます。

属性

コード行数カウンター

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

属性

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

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.token.usagetype(入力/出力)、ユーザー、チーム、またはモデル別の内訳
claude_code.session.count時間経過に伴う採用とエンゲージメントの追跡
claude_code.lines_of_code.countコードの追加/削除を追跡することによる生産性の測定
claude_code.commit.count & claude_code.pull_request.count開発ワークフローへの影響の理解

コスト監視

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

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

コストメトリクスは近似値です。公式の請求データについては、APIプロバイダー(Anthropic Console、AWS Bedrock、またはGoogle Cloud Vertex)を参照してください。

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

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

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

すべてのメトリクスは、user.account_uuidorganization.idsession.idmodel、および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を設定してください