监控与 OpenTelemetry

通过 OpenTelemetry 把 Claude Code 的用量、成本与工具活动以 metrics / events / traces 三类信号导出到你自己的可观测或安全后端。

是什么

Claude Code 的「监控」能力基于 OpenTelemetry（OTel），把 Claude Code 的用量、成本、工具活动以三类信号导出到你自己的后端：metrics（时间序列）、events（logs/events 协议）、以及可选的 distributed traces（beta）。全部通过环境变量配置，默认关闭（opt-in），需显式 CLAUDE_CODE_ENABLE_TELEMETRY=1 才开启。导出目标（Prometheus / OTLP collector / SIEM / Jaeger 等）由你自行选择和搭建；Claude Code 只产出原始信号流，告警、基线、跨会话关联由后端负责。

怎么工作

三条独立数据通道：metrics 走标准 metrics 协议（时间序列）、events 走 logs/events 协议、traces（beta）走 traces 协议；三者各自可配 exporter、endpoint、协议、间隔，互不强制同时开
exporter 选择独立：OTEL_METRICS_EXPORTER 支持 otlp/prometheus/console/none；OTEL_LOGS_EXPORTER 支持 otlp/console/none；OTEL_TRACES_EXPORTER 支持 otlp/console/none；均可逗号分隔同时启用多个（如 console,otlp）
协议与端点有'通用 + 按信号覆盖'两层：OTEL_EXPORTER_OTLP_PROTOCOL/ENDPOINT 作用于所有信号，OTEL_EXPORTER_OTLP_METRICS_、LOGS、TRACES* 可单独覆盖（metrics/logs 可发往不同 backend）
隐私默认安全：默认不收集 prompt 正文（只记 prompt 长度）、不记工具参数、不记工具输入输出内容、不记原始 API body；要收集需分别显式打开 OTEL_LOG_USER_PROMPTS / OTEL_LOG_TOOL_DETAILS / OTEL_LOG_TOOL_CONTENT / OTEL_LOG_RAW_API_BODIES
基数（cardinality）控制：通过 OTEL_METRICS_INCLUDE_* 系列开关决定 session.id / app.version / account_uuid / app.entrypoint 是否进入 metrics 标签，降低存储与查询成本
事件关联：每个 prompt 生成一个 prompt.id（UUID v4），把该 prompt 引发的 user_prompt / api_request / tool_result 等事件串起来；prompt.id 只进 events 不进 metrics（避免无限基数）
身份归因：每条 event 带 user.email / user.account_uuid / user.account_id / organization.id（登录态）+ 安装级 user.id + 会话级 session.id；Claude Code 不用单独服务账号，工具调用归因到启动会话的开发者本人
Traces span 层级：每个 prompt 起一个 claude_code.interaction 根 span，下挂 claude_code.llm_request、claude_code.hook、claude_code.tool；tool span 再分 blocked_on_user（等权限）和 execution（实际执行）两个子 span；Task 工具派生的 subagent 的 span 嵌在父 tool span 下
trace 上下文传播：tracing 开启时，Bash/PowerShell 子进程自动继承 TRACEPARENT 环境变量；直连 Anthropic API 时模型请求带 W3C traceparent 头；自定义 ANTHROPIC_BASE_URL 代理下需 CLAUDE_CODE_PROPAGATE_TRACEPARENT=1 才传播
重试语义：Claude Code 内部重试失败请求，只在彻底放弃后发一条 api_error；attempt 大于 CLAUDE_CODE_MAX_RETRIES（默认 10）说明耗尽重试，超出后另发 api_retries_exhausted 事件
子进程隔离：Claude Code 不把 OTEL_* 传给它派生的子进程（Bash 工具、hooks、MCP server、language server），这些进程要自己导出遥测需在命令里直接设变量

怎么配置 / 用法

启用方式（环境变量，最小可用）：

bash

export CLAUDE_CODE_ENABLE_TELEMETRY=1          # 必需，开启遥测
export OTEL_METRICS_EXPORTER=otlp              # otlp | prometheus | console | none，可逗号分隔多个
export OTEL_LOGS_EXPORTER=otlp                 # otlp | console | none
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc        # grpc | http/json | http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"
export OTEL_METRIC_EXPORT_INTERVAL=10000       # ms，默认 60000
export OTEL_LOGS_EXPORT_INTERVAL=5000          # ms，默认 5000
claude

管理员集中下发（managed settings 文件，可走 MDM，优先级最高、用户不可覆盖）：

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.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Traces (beta)：需同时 CLAUDE_CODE_ENABLE_TELEMETRY=1 + CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1（也接受 ENABLE_ENHANCED_TELEMETRY_BETA），再设 OTEL_TRACES_EXPORTER（console|otlp|none），traces 端点/协议/头复用通用 OTLP 配置，可用 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_TRACES_PROTOCOL / OTEL_TRACES_EXPORT_INTERVAL（默认 5000ms）覆盖。

动态 header（仅 http/protobuf、http/json 有效；grpc 只用静态 OTEL_EXPORTER_OTLP_HEADERS）写在 .claude/settings.json：

json

{ "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh" }

脚本须输出字符串键值对 JSON，例如 echo "{\"Authorization\": \"Bearer $(get-token.sh)\"}"；默认每 29 分钟刷新一次，可用 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS（默认 1740000ms）调整。

多团队归因：export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"（逗号分隔 key=value，禁空格）。

什么时候用

想统计 Claude Code 在组织内的用量、成本、token、工具活动、PR/commit 数量、活跃时长时——开启 metrics + OTLP
需要把每次工具调用/MCP 活动/权限决策归因到具体用户做安全审计（SIEM）时——开 OTEL_LOGS_EXPORTER=otlp 并把 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 指向 SIEM 的 OTLP receiver，建议加 OTEL_LOG_TOOL_DETAILS=1
想把一次 prompt 触发的所有 API 请求与工具执行串成一条分布式 trace 看请求瀑布/延迟时——启用 Traces (beta)
本地调试遥测链路时——用 OTEL_METRICS_EXPORTER=console + OTEL_METRIC_EXPORT_INTERVAL=1000 快速看输出
别用：默认就是 opt-in 关闭的，不配置即不向你的后端导出；不想暴露 user.email/prompt/工具参数时不要随意开 OTEL_LOG_USER_PROMPTS / OTEL_LOG_TOOL_DETAILS / OTEL_LOG_TOOL_CONTENT / OTEL_LOG_RAW_API_BODIES
调试用的短 interval 用完要改回生产值（默认 metrics 60s / logs 5s）

限制 / 坑

默认关闭：不配置 CLAUDE_CODE_ENABLE_TELEMETRY=1 就不会向你的后端导出任何数据（opt-in）
成本是估算：claude_code.cost.usage 为近似值，官方账单以 API provider（Claude Console / Amazon Bedrock / Google Cloud Vertex）为准
OTEL_* 不传给子进程：Bash 工具、hooks、MCP server、language server 不继承 exporter endpoint/headers，需在命令里单独设
动态 header 协议限制：otelHeadersHelper 仅 http/protobuf 与 http/json 生效；grpc 只用静态 OTEL_EXPORTER_OTLP_HEADERS
OTEL_RESOURCE_ATTRIBUTES 格式严格：值不能含空格（user.organizationName=My Company 非法），只允许 US-ASCII 非控制字符，禁双引号/逗号/分号/反斜杠/空白，特殊字符须百分号编码；加引号不会转义空格（org.name="My Company" 会得到带引号的字面值）
隐私敏感开关需谨慎：OTEL_LOG_USER_PROMPTS 记 prompt 正文、OTEL_LOG_TOOL_DETAILS 记工具参数(含 Bash 命令/文件路径/URL)、OTEL_LOG_TOOL_CONTENT 记工具输入输出(可含原始文件内容)、OTEL_LOG_RAW_API_BODIES 记完整对话历史——后两者/后一者尤其敏感
OAuth 登录时 user.email 默认进遥测属性；介意需在后端过滤/脱敏
content 截断：trace span 内容、api body inline 模式均在 60 KB 截断；tool_input 单值超 512 字符截断、总量约束在 ~4 K 字符；extended-thinking 内容在 raw API body 中始终被脱敏
detailed beta tracing（claude_code.hook span 及 new_context/tool_input 等内容属性）门槛更高：需 ENABLE_BETA_TRACING_DETAILED=1 + BETA_TRACING_ENDPOINT，交互式 CLI 还需组织被 allowlist；只设 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 不会发出
direct API key / Bedrock / Vertex / Foundry 部署下无 Claude 账号，只有 user.id 与 session.id，身份需自己用 OTEL_RESOURCE_ATTRIBUTES 注入（如 enduser.id）
claude_code.internal_error 在 Bedrock/Vertex/Foundry 或设置 DISABLE_ERROR_REPORTING 时不发出；且只记错误类名+errno 码，不含 message/堆栈
hook_plugin_metrics 仅 official Anthropic marketplace 插件能发；第三方 marketplace 插件与用户自配 hook 不发；该事件最多 20 个插件自定义 metric key（名须匹配 ^[a-z][a-z0-9_]{0,39}$）
compaction 事件的 precompute_reuse 属性需 Claude Code v2.1.153 或更高
at_mention 事件并非每次都发：权限拒绝、超大文件、PDF 引用附件、目录列举失败等 early-exit 路径不记录
Claude Code 只产出原始事件流，异常检测/基线/跨会话关联/告警由你的 SIEM 或可观测后端负责

硬事实速查（34 条）

开关：CLAUDE_CODE_ENABLE_TELEMETRY=1（必需）
metrics exporter：OTEL_METRICS_EXPORTER，取值 otlp / prometheus / console / none，可逗号分隔
logs exporter：OTEL_LOGS_EXPORTER，取值 otlp / console / none（注意无 prometheus）
traces exporter：OTEL_TRACES_EXPORTER，取值 console / otlp / none
协议：OTEL_EXPORTER_OTLP_PROTOCOL = grpc | http/json | http/protobuf
通用端点：OTEL_EXPORTER_OTLP_ENDPOINT，gRPC 示例 http://localhost:4317
按信号覆盖端点示例：metrics http://localhost:4318/v1/metrics，logs http://localhost:4318/v1/logs，traces http://localhost:4318/v1/traces（HTTP 默认 4318）
认证头：OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token"
导出间隔：OTEL_METRIC_EXPORT_INTERVAL 默认 60000ms；OTEL_LOGS_EXPORT_INTERVAL 默认 5000ms；OTEL_TRACES_EXPORT_INTERVAL 默认 5000ms（单位均为毫秒）
temporality：OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE 默认 delta，可设 cumulative
隐私开关：OTEL_LOG_USER_PROMPTS（默认关）/ OTEL_LOG_TOOL_DETAILS（默认关）/ OTEL_LOG_TOOL_CONTENT（默认关，需 tracing，60 KB 截断）
OTEL_LOG_RAW_API_BODIES：=1 内联 body 截断 60 KB；=file:<dir> 写未截断 body 到磁盘并在事件里给 body_ref 指针
基数控制默认值：OTEL_METRICS_INCLUDE_SESSION_ID 默认 true；OTEL_METRICS_INCLUDE_VERSION 默认 false；OTEL_METRICS_INCLUDE_ACCOUNT_UUID 默认 true；OTEL_METRICS_INCLUDE_ENTRYPOINT 默认 false
Traces (beta) 需 CLAUDE_CODE_ENABLE_TELEMETRY=1 + CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1（亦接受 ENABLE_ENHANCED_TELEMETRY_BETA）
traceparent 代理传播：CLAUDE_CODE_PROPAGATE_TRACEPARENT=1（自定义 ANTHROPIC_BASE_URL 代理时需要）
动态 header：.claude/settings.json 的 otelHeadersHelper 字段；仅 http/protobuf 与 http/json 有效；默认每 29 分钟刷新；间隔由 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 控制（默认 1740000ms，示例 900000）
mTLS：http/protobuf|http/json 用 CLAUDE_CODE_CLIENT_CERT / CLAUDE_CODE_CLIENT_KEY /（可选）CLAUDE_CODE_CLIENT_KEY_PASSPHRASE，CA 用 NODE_EXTRA_CA_CERTS；grpc 用 OTEL_EXPORTER_OTLP_CLIENT_KEY / OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE（CA 用 OTEL_EXPORTER_OTLP_CERTIFICATE）
多团队归因：OTEL_RESOURCE_ATTRIBUTES，逗号分隔 key=value，禁空格
重试：CLAUDE_CODE_MAX_RETRIES 默认 10；api_error 的 attempt 超过该值表示耗尽重试
8 个 metrics：claude_code.session.count(count) / claude_code.lines_of_code.count(count) / claude_code.pull_request.count(count) / claude_code.commit.count(count) / claude_code.cost.usage(USD) / claude_code.token.usage(tokens) / claude_code.code_edit_tool.decision(count) / claude_code.active_time.total(s)
token.usage 的 type 取值：input / output / cacheRead / cacheCreation
code_edit_tool.decision 的 tool_name：Edit / Write / NotebookEdit；decision：accept / reject；source：config/hook/user_permanent/user_temporary/user_abort/user_reject
active_time.total 的 type：user（键盘交互）/ cli（工具执行与 AI 响应）
session.count 的 start_type：fresh / resume / continue
成本/token 归因属性：model、query_source(main/subagent/auxiliary)、speed(fast)、effort(low/medium/high/xhigh/max)、agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name（用户自配名脱敏为 custom，第三方插件脱敏为 third-party）
事件（OTLP logs）名清单：claude_code.user_prompt / tool_result / api_request / api_error / api_request_body / api_response_body / tool_decision / permission_mode_changed / auth / mcp_server_connection / internal_error / plugin_installed / plugin_loaded / skill_activated / at_mention / api_retries_exhausted / hook_registered / hook_execution_start / hook_execution_complete / hook_plugin_metrics / compaction / feedback_survey
permission_mode_changed 的 to/from 模式：default / plan / acceptEdits / auto / bypassPermissions；trigger：shift_tab / exit_plan_mode / auto_gate_denied / auto_opt_in
标准属性：session.id、app.version、app.entrypoint(cli/sdk-cli/sdk-ts/sdk-py/claude-vscode)、organization.id、user.account_uuid、user.account_id(如 user_01BWBeN28...)、user.id、user.email、terminal.type(iTerm.app/vscode/cursor/tmux)
prompt.id 为 UUID v4，关联单个 prompt 的所有事件，且故意不进 metrics
SIEM 审计：OTEL_LOGS_EXPORTER=otlp + OTEL_LOG_TOOL_DETAILS=1，OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 指向 SIEM 的 OTLP receiver
service 资源属性：service.name=claude-code、service.version=当前版本、os.type(linux/darwin/windows)、os.version、host.arch(amd64/arm64)、wsl.version(仅 WSL)、Meter Name=com.anthropic.claude_code
tool_result 的 tool_input 截断：单值超 512 字符截断，总量约束 ~4 K 字符
feedback_survey 需 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL（enabled_via_override 属性反映是否被覆盖）
ROI/落地参考：github.com/anthropics/claude-code-monitoring-guide（含 Docker Compose、Prometheus、OTel 配置模板）

官方出处：https://code.claude.com/docs/en/monitoring-usage

监控与 OpenTelemetry ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​

硬事实速查（34 条） ​