監視
Claude Codeでのオープンテレメトリの有効化と設定方法について学習します。
Claude CodeはOpenTelemetry(OTel)メトリクスとイベントを監視と可観測性のためにサポートしています。
すべてのメトリクスはOpenTelemetryの標準メトリクスプロトコルを介してエクスポートされる時系列データであり、イベントはOpenTelemetryのログ/イベントプロトコルを介してエクスポートされます。メトリクスとログのバックエンドが適切に設定され、集約の粒度が監視要件を満たしていることを確認するのはユーザーの責任です。
OpenTelemetryサポートは現在ベータ版であり、詳細は変更される可能性があります。
クイックスタート
環境変数を使用してOpenTelemetryを設定します:
デフォルトのエクスポート間隔は、メトリクスが60秒、ログが5秒です。セットアップ中は、デバッグ目的でより短い間隔を使用することをお勧めします。本番環境での使用時にはこれらをリセットすることを忘れないでください。
完全な設定オプションについては、OpenTelemetry仕様を参照してください。
管理者設定
管理者は、管理設定ファイルを通じてすべてのユーザーのOpenTelemetry設定を構成できます。これにより、組織全体でテレメトリ設定を一元管理できます。設定の適用方法の詳細については、設定の優先順位を参照してください。
管理設定ファイルの場所:
- macOS:
/Library/Application Support/ClaudeCode/managed-settings.json
- Linux:
/etc/claude-code/managed-settings.json
管理設定の設定例:
管理設定は、MDM(モバイルデバイス管理)やその他のデバイス管理ソリューションを介して配布できます。管理設定ファイルで定義された環境変数は高い優先順位を持ち、ユーザーによって上書きできません。
設定の詳細
共通設定変数
環境変数 | 説明 | 例の値 |
---|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY | テレメトリ収集を有効化(必須) | 1 |
OTEL_METRICS_EXPORTER | メトリクスエクスポータータイプ(カンマ区切り) | console , otlp , prometheus |
OTEL_LOGS_EXPORTER | ログ/イベントエクスポータータイプ(カンマ区切り) | console , otlp |
OTEL_EXPORTER_OTLP_PROTOCOL | OTLPエクスポーターのプロトコル(すべてのシグナル) | grpc , http/json , http/protobuf |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLPコレクターエンドポイント(すべてのシグナル) | http://localhost:4317 |
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | メトリクス用プロトコル(一般設定を上書き) | grpc , http/json , http/protobuf |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | OTLPメトリクスエンドポイント(一般設定を上書き) | http://localhost:4318/v1/metrics |
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | ログ用プロトコル(一般設定を上書き) | grpc , http/json , http/protobuf |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | OTLPログエンドポイント(一般設定を上書き) | http://localhost:4318/v1/logs |
OTEL_EXPORTER_OTLP_HEADERS | OTLP用認証ヘッダー | Authorization=Bearer token |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY | mTLS認証用クライアントキー | クライアントキーファイルへのパス |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE | mTLS認証用クライアント証明書 | クライアント証明書ファイルへのパス |
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属性を含める | true | false |
OTEL_METRICS_INCLUDE_VERSION | メトリクスにapp.version属性を含める | false | true |
OTEL_METRICS_INCLUDE_ACCOUNT_UUID | メトリクスにuser.account_uuid属性を含める | true | false |
これらの変数は、メトリクスのカーディナリティを制御するのに役立ちます。これは、メトリクスバックエンドでのストレージ要件とクエリパフォーマンスに影響します。一般的に、カーディナリティが低いほどパフォーマンスが向上し、ストレージコストが削減されますが、分析用のデータの粒度は低くなります。
設定例
利用可能なメトリクスとイベント
メトリクス
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.usage | Claude Codeセッションのコスト | USD |
claude_code.token.usage | 使用されたトークン数 | tokens |
claude_code.code_edit_tool.decision | コード編集ツール許可決定の数 | count |
メトリクスの詳細
すべてのメトリクスは以下の標準属性を共有します:
session.id
: 一意のセッション識別子(OTEL_METRICS_INCLUDE_SESSION_ID
で制御)app.version
: 現在のClaude Codeバージョン(OTEL_METRICS_INCLUDE_VERSION
で制御)organization.id
: 組織UUID(認証時)user.account_uuid
: アカウントUUID(認証時、OTEL_METRICS_INCLUDE_ACCOUNT_UUID
で制御)
セッションカウンター
各セッションの開始時に発行されます。
コード行数カウンター
コードが追加または削除されたときに発行されます。
追加属性:type
("added"
または"removed"
)
プルリクエストカウンター
Claude Code経由でプルリクエストを作成するときに発行されます。
コミットカウンター
Claude Code経由でgitコミットを作成するときに発行されます。
コストカウンター
各APIリクエスト後に発行されます。
追加属性:model
トークンカウンター
各APIリクエスト後に発行されます。
追加属性:type
("input"
, "output"
, "cacheRead"
, "cacheCreation"
)とmodel
コード編集ツール決定カウンター
ユーザーがEdit、MultiEdit、Write、またはNotebookEditツールの使用を承認または拒否したときに発行されます。
追加属性:tool
(ツール名:"Edit"
, "MultiEdit"
, "Write"
, "NotebookEdit"
)とdecision
("accept"
, "reject"
)
イベント
Claude Codeは、OpenTelemetryログ/イベント(OTEL_LOGS_EXPORTER
が設定されている場合)を介して以下のイベントをエクスポートします:
ユーザープロンプトイベント
- イベント名:
claude_code.user_prompt
- 説明: ユーザーがプロンプトを送信したときにログ記録
- 属性:
- すべての標準属性(user.id、session.idなど)
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_code.api_request
- 説明: ClaudeへのAPIリクエストごとにログ記録
- 属性:
- すべての標準属性
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_code.api_error
- 説明: ClaudeへのAPIリクエストが失敗したときにログ記録
- 属性:
- すべての標準属性
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.usage | type (入力/出力)、ユーザー、チーム、またはモデル別の内訳 |
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_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
を設定してください