監視
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 |
これらの変数は、ストレージ要件とメトリクスバックエンドでのクエリパフォーマンスに影響するメトリクスのカーディナリティを制御するのに役立ちます。一般的に、低いカーディナリティはより良いパフォーマンスと低いストレージコストを意味しますが、分析用のデータの粒度は低くなります。
マルチチーム組織サポート
複数のチームや部門を持つ組織は、OTEL_RESOURCE_ATTRIBUTES
環境変数を使用して、異なるグループを区別するためのカスタム属性を追加できます:
これらのカスタム属性はすべてのメトリクスとイベントに含まれ、以下のことが可能になります:
- チームや部門でメトリクスをフィルタリング
- コストセンターごとのコスト追跡
- チーム固有のダッシュボード作成
- 特定のチーム用のアラート設定
設定例
利用可能なメトリクスとイベント
標準属性
すべてのメトリクスとイベントは、これらの標準属性を共有します:
属性 | 説明 | 制御者 |
---|---|---|
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.app 、vscode 、cursor 、tmux ) | 検出された場合は常に含まれる |
メトリクス
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 |
メトリクスの詳細
セッションカウンター
各セッションの開始時に発行されます。
属性:
- すべての標準属性
コード行数カウンター
コードが追加または削除されたときに発行されます。
属性:
- すべての標準属性
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.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
を設定してください