はじめに
経営会議でClaudeへの投資対効果を問われたとき、あなたはどう答えるか。
「エンジニアたちが喜んで使っています」では通じない。「/usageで確認したところ、月間コストは〇〇円です」と答えても、それはただの請求明細だ。経営が聞きたいのは、誰が使っているのか、何人が本当に使い続けているのか、コードの品質は上がっているのか、セキュリティのリスクは制御できているのか——つまり投資判断の根拠になる数字だ。
この問いに答えられるようになるのが、Claude Code の OpenTelemetry（OTel）エクスポートだ。メトリクス8種・ログイベント15種以上・トレース4階層が、あなたの組織がすでに持っているDatadog、Honeycomb、Prometheus、あるいはSIEMに直接流れ込む。3種の信号がそれぞれ独立にon/offできる構造になっているため、SIEM連携だけ先に動かすことも、コストKPIの可視化だけから始めることもできる。
3種の信号——それぞれ独立に動かせる
Claude Code が外部に送出するのは、メトリクス・ログイベント・トレースだ。◎ 公式監視ドキュメントにはこう書かれている。
> Claude Code exports metrics as time series data via the standard metrics protocol, events via the logs/events protocol, and optionally distributed traces via the traces protocol.
3種は独立にon/offできる。SIEM連携だけ始めるならログイベントのみ、コストKPIの可視化だけならメトリクスのみ、パフォーマンス分析にはトレースを追加する。既存の観測スタックとの統合順序を組織の事情に合わせられる柔軟性は、実運用で予想以上に効いてくる。
| 信号 | 主な用途 | 既定エクスポート間隔 |
|---|---|---|
| Metrics | コスト・トークン・採用率の時系列KPI | 60秒 |
| Log Events | セキュリティ監査・ツール使用状況・プラグインinventory | 5秒 |
| Traces（beta） | LLMリクエストのレイテンシ・subagent階層の可視化 | 5秒 |
最小構成の環境変数はこうなる。
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317組織レベルで全員に強制したい場合は、managed settingsのenvブロックに同じキーを置けばMDM配布できる。なお、◎ 公式ドキュメントに注意点が明記されている。
> Claude Code does not pass OTEL_* environment variables to the subprocesses it spawns, including the Bash tool, hooks, MCP servers, and language servers.
Bashで起動した別アプリはClaude CodeのOTel設定を継承しない。トレースのTRACEPARENTだけはW3C trace contextとしてサブプロセスに伝播するが、それ以外は別途設定が必要だ。
メトリクス8種でわかること
メトリクスは8種ある。「何が取れるか」と「EM・SREが何を判断できるか」を並べておく。
| メトリクス | 単位 | 判断できること |
|---|---|---|
claude_code.cost.usage | USD | model・agent・skill・pluginごとのROI試算。ROIが低い拡張機能の棚卸しができる |
claude_code.token.usage | tokens | input/output/cacheRead/cacheCreationの比率でプロンプトキャッシュの効きを確認できる |
claude_code.session.count | count | fresh/resume/continueの比率で「使い始め」vs「継続利用」の分布が見える |
claude_code.active_time.total | 秒 | user/cli別の実作業時間で採用率の実態を把握できる |
claude_code.lines_of_code.count | count | 追加/削除行数で生産性の変化を追える |
claude_code.pull_request.count | count | Claude-assistedなPR数の推移が見える |
claude_code.commit.count | count | コミット頻度の変化を追える |
claude_code.code_edit_tool.decision | count | 言語別・ツール別のaccept/reject率で提案品質を評価できる |
◎ 公式の重要注記:
> Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, Amazon Bedrock, or Google Cloud Vertex).
cost.usageはあくまで近似値だ。社内ダッシュボードでは「速報」として扱い、月次精算はAPIプロバイダ側のbillingデータを使う運用にしておいてほしい。
トークン最適化の判断基準
token.usageのtype属性にはcacheReadとcacheCreationが含まれる。cacheRead比率が継続して低い場合、プロンプト設計を見直すか別モデルへ切り替えるかの判断材料になる。逆にcacheCreationが高騰しているときはキャッシュ無効化が頻発しており、CLAUDE.mdやsystem promptが頻繁に変更されている可能性がある。prompt cachingの詳細はcacheRead比率の最適化を扱った別記事を参照してほしい。
何から可視化して何を判断するか——運用の優先軸
メトリクス8種・イベント15種以上・トレース4階層を10カテゴリに整理することもできるが、全部一度に入れても運用しきれない。私が実際に使っている優先順で説明する。
コスト分析と採用率
最初に整備すべき二軸だ。cost.usageをquery_source属性で分解すると、main/subagent/auxiliaryごとのコスト分布が見える。subagentが思いのほかコストを消費しているなら、マルチエージェント構成の見直し判断ができる。skill.name・plugin.name別の内訳を出せば、ROIが低い拡張機能の棚卸しにもなる。
採用率はsession.countのstart_type比率と、active_time.totalのtype=userを組み合わせて見る。DAU/WAU/MAUはuser.account_uuidでunique集計すれば算出できる。「ライセンスを付与しているエンジニアのうち何割が週1以上使っているか」という数字は、経営報告で最も問われる指標の一つだ。
セキュリティ監査とSIEM統合
ログイベントの中で、セキュリティ担当がとくに注目すべきイベントがある。◎ 公式が提示するマッピング:
| 監視したい挙動 | 使うイベント | 主属性 |
|---|---|---|
| ツール許可/拒否の判定 | tool_decision | decision, source, tool_name |
| permission modeの昇格 | permission_mode_changed | from_mode, to_mode, trigger |
| hookによるブロック | hook_execution_complete | hook_event, num_blocking |
| ログイン/ログアウト/失敗 | auth | action, success, error_category |
| MCP接続/失敗 | mcp_server_connection | status, server_name, error_code |
| プラグイン導入と出所 | plugin_installed | plugin.name, marketplace.name, marketplace.is_official |
| 実行コマンドと触ったファイル | tool_result（OTEL_LOG_TOOL_DETAILS=1） | tool_parameters, tool_input |
OTLPからSIEM直送、またはOTel Collector経由でSIEMネイティブAPIへの転送、どちらでも接続できる。ただし◎ 公式が明確に述べている。
> Claude Code emits the raw event stream only. Anomaly detection, baselining, correlation across sessions, and alerting are the responsibility of your SIEM or observability backend.
Claude CodeはRaw eventを提供するだけだ。アラート設計とベースライン化はSIEM側の仕事になる。
モデル選択とコンテキスト管理
トレース（beta）を有効化するとllm_requestスパンにttft_ms（time-to-first-token）が付く。モデル別の中央値を比較することで体感速度の定量評価ができる。gen_ai.response.finish_reasonsのmax_tokens比率が高いモデルはコンテキスト不足で打ち切られている可能性があり、モデル切り替えの判断材料になる。
コンテキスト管理はcompactionイベントで追える。pre_tokensとpost_tokensの比率で圧縮効率が分かり、同一session.idでのcompaction発生頻度が高い場合は、エージェントの設計自体を見直すシグナルになる。
Bedrock・Vertex・Foundryでの挙動差
CloudのネイティブAIサービス経由でClaude Codeを使っている場合、ユーザーアイデンティティの扱いが変わる。◎ 公式ドキュメントより:
> When Claude Code authenticates with a direct API key, or against Bedrock, Vertex AI, or Microsoft Foundry, there is no Claude account in the session and only user.id and session.id are populated.
Claude accountを介さない認証経路ではuser.emailなどのアイデンティティ属性が出ない。「誰の操作か」をSIEMで追跡したいなら、managed settingsからOTEL_RESOURCE_ATTRIBUTESで補完する必要がある。
OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."BedrockとサブスクリプションでのClaude Code機能差については別記事で扱っているが、OTelの観点では「ユーザーアイデンティティの欠落」がBedrockを使う組織の主な課題になる。
analytics ダッシュボードとOTelの役割分担
claude.ai/analytics/claude-codeのダッシュボードとOTelエクスポートは競合しない。◎ 公式analyticsドキュメントにこう書かれている。
> For per-user token counts and cost estimates, configure OpenTelemetry export.
役割の差を表で並べる:
| 観点 | analytics ダッシュボード | OTel エクスポート |
|---|---|---|
| データ粒度 | 日次集計（24時間遅延）、PR紐付け | リアルタイム時系列・raw event |
| GitHub PR連動 | GitHub アプリ経由でClaude-assistedラベル付与 | 不可（PR/commit countのみ） |
| Zero Data Retention | contribution metrics非対応 | 自社内に閉じるので影響なし |
| アクセス制御 | Admin / Owner | 観測バックエンドのアクセス権で制御 |
「全社レベルのKPIダッシュボード」はanalyticsダッシュボード、「詳細監査・コスト最適化・SIEM統合・モデル選択分析」はOTelと役割が分かれる。両方セットで使うのが前提だ。
運用上の注意点
カーディナリティ制御
Prometheusを使う場合に特に問題になるのがカーディナリティだ。Claude Codeにはカーディナリティを絞る環境変数が3本ある。
| 環境変数 | 既定 | 影響 |
|---|---|---|
OTEL_METRICS_INCLUDE_SESSION_ID | true | OFFにすると時系列は劇的に細くなるがsession単位の追跡は失われる |
OTEL_METRICS_INCLUDE_ACCOUNT_UUID | true | OFFにするとユーザー別追跡が消える |
OTEL_METRICS_INCLUDE_VERSION | false | ONにするとバージョン別の比較ができる |
prompt.idはメトリクスには含まれない。◎ 公式の説明:
> prompt.id is intentionally excluded from metrics because each prompt generates a unique ID, which would create an ever-growing number of time series. Use it for event-level analysis and audit trails only.
session_idをOFFにしないとPrometheus TSDBが破綻する規模になりやすい環境では、早めに検討が必要だ。
プライバシー4段階とコンテンツ制御
コンテンツをどこまでログに乗せるかは、4本の環境変数で段階的に制御できる。
| 変数 | オプトインするもの | 留意点 |
|---|---|---|
OTEL_LOG_USER_PROMPTS=1 | プロンプト本文 | 個人情報・機密情報が含まれうる |
OTEL_LOG_TOOL_DETAILS=1 | Bashコマンド・MCP名・ツール引数 | 最大512文字/属性、合計4KB |
OTEL_LOG_TOOL_CONTENT=1 | ツールspanのfull input/output | 60KB/属性。traces必須 |
OTEL_LOG_RAW_API_BODIES | Messages APIの生request/response | 60KB（=1）または無制限（file:dir） |
◎ 公式の強い警告:
> Leave these unset unless your observability pipeline is approved to store the data your agent handles.
OTEL_LOG_RAW_API_BODIESは会話履歴全体・system prompt・ツール結果すべてを含む。エンドユーザーのPIIを扱うエージェントで安易に有効化するとGDPR・個人情報保護法に抵触しうる。承認済みパイプライン以外では原則として切っておく。
短時間タスクのフラッシュ問題
claude -pやAgent SDKで短時間タスクを回すとき、5秒間隔のlogs/tracesバッファに残ったまま終了してデータが欠落することがある。◎ 公式Agent SDKドキュメントより:
> The CLI batches telemetry and exports on an interval. On a clean process exit it attempts to flush pending data, but the flush is bounded by a short timeout, so spans can still be dropped if the collector is slow to respond.
対策はエクスポートインターバルを短くするか、ローカルのOTel Collectorを経由させることだ。Collectorを挟むとCollector自身がバッファして再送するため、フラッシュ問題が軽減する。
export OTEL_METRIC_EXPORT_INTERVAL=1000
export OTEL_LOGS_EXPORT_INTERVAL=1000
export OTEL_TRACES_EXPORT_INTERVAL=1000まとめ
Claude CodeのOTelエクスポートは、「誰が・どのモデルで・何にコストをかけているか」を組織横断で可視化する。/usageコマンドが個人セッションのスナップショットを返すのに対して、OTelは時系列・複数ユーザー・ツール別・エージェント階層にまたがるデータを自社の観測スタックに直接流す。
迷うなら、メトリクスだけ先に有効化してコストとセッション数を眺めてほしい。それだけで「誰が使っていないか」はすぐ分かる。SIEMがある組織はログイベントを同時に入れておく方がいい——あとから追加するより、最初からパイプラインを通しておく方が運用がシンプルになる。トレースはbetaのため本番投入は慎重でいいが、llm_request単位のレイテンシやsubagentコスト内訳が取れる点は他の手段では代替できない。CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1に加えてOTEL_TRACES_EXPORTER=otlpを設定するだけで動くので、開発環境で試す分には即座に確認できる。
Anthropicは ◎ claude-code-monitoring-guide でDocker Compose一式・Prometheus設定・Linear連携テンプレートを公式に公開している。ゼロからダッシュボードを作らずに済む。
今日試せる最小アクション: .envにCLAUDE_CODE_ENABLE_TELEMETRY=1とOTEL_METRICS_EXPORTER=otlpを追加し、エンドポイントをローカルのOTel Collector（http://localhost:4317）に向けるだけで、最初のメトリクスが流れ始める。
コメント