监控使用情况（OpenTelemetry）

Claude Code 通过 OpenTelemetry（OTel）导出遥测数据，帮助企业跨组织追踪 Token 消耗、API 成本和工具活动。支持指标（时间序列）、日志/事件和分布式链路追踪（beta）三个信号通道，兼容 OTLP/gRPC、OTLP/HTTP、Prometheus 和 Console 等主流导出后端。管理员可通过托管设置文件集中配置，遥测默认关闭，需要显式启用。

通过 OpenTelemetry（OTel）导出遥测数据，跨组织追踪 Claude Code 使用情况、成本和工具活动。Claude Code 通过标准指标协议导出时间序列数据，通过日志/事件协议导出事件，还可选开启分布式链路追踪（beta）。

快速开始

通过环境变量配置 OpenTelemetry：

bash

# 1. 启用遥测
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 选择导出器（均为可选，只配置需要的）
export OTEL_METRICS_EXPORTER=otlp       # 选项：otlp、prometheus、console、none
export OTEL_LOGS_EXPORTER=otlp          # 选项：otlp、console、none

# 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）

claude

完整配置选项参见 OpenTelemetry specification。

管理员配置

管理员可通过托管设置文件为所有用户集中配置 OpenTelemetry：

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"
  }
}

配置参考

常用配置变量

环境变量	说明	示例值
`CLAUDE_CODE_ENABLE_TELEMETRY`	启用遥测收集（必填）	`1`
`OTEL_METRICS_EXPORTER`	指标导出器类型（逗号分隔），`none` 禁用	`console`、`otlp`、`prometheus`、`none`
`OTEL_LOGS_EXPORTER`	日志/事件导出器类型，`none` 禁用	`console`、`otlp`、`none`
`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`	指标专用端点，覆盖通用设置	`http://localhost:4318/v1/metrics`
`OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`	日志专用协议，覆盖通用设置	`grpc`、`http/json`、`http/protobuf`
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	日志专用端点，覆盖通用设置	`http://localhost:4318/v1/logs`
`OTEL_EXPORTER_OTLP_HEADERS`	OTLP 认证头	`Authorization=Bearer token`
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY`	mTLS 客户端私钥路径	`/path/to/client.key`
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE`	mTLS 客户端证书路径	`/path/to/client.crt`
`OTEL_METRIC_EXPORT_INTERVAL`	指标导出间隔（毫秒，默认 60000）	`5000`
`OTEL_LOGS_EXPORT_INTERVAL`	日志导出间隔（毫秒，默认 5000）	`1000`
`OTEL_LOG_USER_PROMPTS`	启用用户提示内容记录（默认禁用）	`1`
`OTEL_LOG_TOOL_DETAILS`	记录工具参数：Bash 命令、MCP 服务器/工具名、技能名和工具输入（默认禁用）	`1`
`OTEL_LOG_TOOL_CONTENT`	在 span 事件中记录工具输入/输出内容（默认禁用，需开启链路追踪，内容截断在 60KB）	`1`
`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`	指标时间性偏好（默认 `delta`），后端要求累积时设为 `cumulative`	`delta`、`cumulative`
`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`	动态 Headers 刷新间隔（默认 1740000ms / 29 分钟）	`900000`

基数控制变量

控制指标中包含的属性，以管理基数（影响存储成本和查询性能）：

变量	说明	默认值
`OTEL_METRICS_INCLUDE_SESSION_ID`	在指标中包含 `session.id` 属性	`true`
`OTEL_METRICS_INCLUDE_VERSION`	在指标中包含 `app.version` 属性	`false`
`OTEL_METRICS_INCLUDE_ACCOUNT_UUID`	在指标中包含 `user.account_uuid` 和 `user.account_id`	`true`

链路追踪（beta）

分布式链路追踪将每个用户提示与其触发的 API 请求和工具执行关联，可以在追踪后端中将完整请求视为单条链路。

链路追踪默认关闭，启用方式：

bash

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp     # 或 console

链路追踪复用通用 OTLP 配置变量的端点、协议和认证头设置。

变量	说明	示例值
`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`	启用 span 追踪（必填），也接受 `ENABLE_ENHANCED_TELEMETRY_BETA`	`1`
`OTEL_TRACES_EXPORTER`	追踪导出器类型（逗号分隔），`none` 禁用	`console`、`otlp`、`none`
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`	追踪专用协议，覆盖通用设置	`grpc`、`http/json`、`http/protobuf`
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	追踪专用端点，覆盖通用设置	`http://localhost:4318/v1/traces`
`OTEL_TRACES_EXPORT_INTERVAL`	span 批量导出间隔（毫秒，默认 5000）	`1000`

TRACEPARENT 自动继承：链路追踪激活时，Claude 运行的 Bash 和 PowerShell 子进程自动继承 TRACEPARENT 环境变量（包含当前工具执行 span 的 W3C 链路上下文）。支持 TRACEPARENT 的子进程可以在同一链路下挂载自己的 span，实现端到端分布式追踪。

隐私：span 默认不包含用户提示文本、工具输入详情和工具内容。设置 OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1 和 OTEL_LOG_TOOL_CONTENT=1 可选择性包含。

动态 Headers

对于需要动态认证的企业环境，通过脚本动态生成 Headers：

在 .claude/settings.json 中配置：

json

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

脚本要求输出有效的 JSON 键值对（HTTP Headers）：

bash

#!/bin/bash
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

脚本在启动时运行，此后定期刷新（默认每 29 分钟），可通过 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 自定义间隔。

多团队支持

使用 OTEL_RESOURCE_ATTRIBUTES 添加自定义属性区分不同团队：

bash

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

这些自定义属性会包含在所有指标和事件中，可用于按团队/部门过滤、按成本中心追踪费用、创建团队专属仪表板或设置特定团队的告警。

使用示例配置

bash

# 控制台调试（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=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.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、app.version、organization.id、user.account_uuid、user.account_id、user.id、user.email、terminal.type

指标列表

指标名称	说明	单位
`claude_code.session.count`	启动的 CLI 会话数	count
`claude_code.lines_of_code.count`	修改的代码行数（含 `type` 属性：`added`/`removed`）	count
`claude_code.pull_request.count`	创建的 Pull Request 数	count
`claude_code.commit.count`	创建的 Git 提交数	count
`claude_code.cost.usage`	会话成本（含 `model` 属性）	USD
`claude_code.token.usage`	使用的 Token 数量（含 `type`：`input`/`output`/`cacheRead`/`cacheCreation` 和 `model` 属性）	tokens
`claude_code.code_edit_tool.decision`	代码编辑工具权限决策数（含 `tool_name`、`decision`、`source`、`language`）	count
`claude_code.active_time.total`	总活跃时间	s

可用事件

启用 OTEL_LOGS_EXPORTER 后导出。prompt.id（UUID v4）用于关联处理单个用户提示时产生的所有事件。

事件名称	触发时机	包含属性
`claude_code.user_prompt`	用户提交提示时	—
`claude_code.tool_result`	工具完成执行时	`tool_name`、`success`、`duration_ms`、`error`、`decision_type`、`decision_source`、`tool_result_size_bytes`
`claude_code.api_request`	发送 API 请求时	`model`、`cost_usd`、`duration_ms`、`input_tokens`、`output_tokens`、`cache_read_tokens`、`cache_creation_tokens`、`speed`（`fast`/`normal`）
`claude_code.api_error`	API 请求失败时	—
`claude_code.tool_decision`	做出工具权限决策时	—

安全和隐私

遥测是选择加入的，需要显式设置 CLAUDE_CODE_ENABLE_TELEMETRY=1
不包含原始文件内容和代码片段
默认不收集用户提示内容（只记录提示长度）
MCP 服务器/工具名称和技能名称默认不记录
所有数据传输使用你配置的 OTLP 端点，Anthropic 不会接收遥测数据

常见问题

Q: 遥测数据会发送给 Anthropic 吗？

不会。遥测数据只发送到你配置的 OTLP 端点（可以是你自己的 Grafana、Prometheus 或其他后端）。Anthropic 不接收这些数据。

Q: 如何在不同团队之间区分遥测数据？

使用 OTEL_RESOURCE_ATTRIBUTES 添加自定义标签，如 team.id=platform,cost_center=eng-123。这些标签会附加到所有指标和事件上，方便在监控后端按团队过滤。

Q: 分布式链路追踪（Traces）适合什么场景？

适合需要深入分析单个用户请求完整执行链路的场景——可以看到一次提示触发了哪些工具、每个工具的耗时、以及对应的 API 调用成本。对排查慢响应和优化 Token 使用很有帮助。目前为 beta 功能，需要额外设置 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1。

监控使用情况（OpenTelemetry） ​

快速开始 ​

管理员配置 ​

配置参考 ​

常用配置变量 ​

基数控制变量 ​

链路追踪（beta） ​

动态 Headers ​

多团队支持 ​

使用示例配置 ​

可用指标 ​

标准属性 ​

指标列表 ​

可用事件 ​

安全和隐私 ​

相关资源 ​

常见问题 ​

监控使用情况（OpenTelemetry）

快速开始

管理员配置

配置参考

常用配置变量

基数控制变量

链路追踪（beta）

动态 Headers

多团队支持

使用示例配置

可用指标

标准属性

指标列表

可用事件

安全和隐私

相关资源

常见问题