Claude Code 通过 OpenTelemetry（OTel）导出遥测数据，助力组织追踪 Token 消耗、API 成本、工具活动和分布式链路。需要显式设置 CLAUDE_CODE_ENABLE_TELEMETRY=1，并配置导出器、端点、认证；支持管理员集中管理、动态 Headers 刷新、基数控制以及多团队自定义资源属性。Telemetry 仅发送到用户配置的 OTLP 后端，Anthropic 不接收这些数据。

Claude Code 监控配置：OpenTelemetry 导出指标、事件与链路追踪 #

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

快速开始 #

通过环境变量配置 OpenTelemetry：

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

# 6. 启动 Claude Code
claude

默认指标导出间隔 60 秒，日志/事件导出间隔 5 秒。调试时可缩短间隔，生产环境请恢复默认值。

完整配置选项参见 OpenTelemetry specification。

管理员配置 #

管理员可通过托管设置文件为所有用户集中配置 OpenTelemetry。环境变量在托管设置文件中具有高优先级，用户无法覆盖。

{
  "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 不会将 OTEL_* 环境变量传递给子进程（Bash 工具、钩子、MCP 服务器、语言服务器）。如果子进程中运行的应用程序需要导出自身的遥测数据，需要在命令中直接设置这些变量。

配置细节 #

常用配置变量 #

mTLS 认证 #

配置客户端证书的方式取决于对应信号使用的 OTLP 协议（通过 OTEL_EXPORTER_OTLP_PROTOCOL 或各信号覆盖变量设置）。

对于 grpc，OpenTelemetry SDK 直接读取标准 OTLP 变量，已有配置中设置每信号指标变量的方式仍然有效。

指标基数控制 #

以下环境变量控制指标中包含哪些属性，以管理基数（影响存储和查询性能）。较低的基数通常带来更好的性能和更低的存储成本。

例如禁用 session.id：export OTEL_METRICS_INCLUDE_SESSION_ID=false。

链路追踪（beta） #

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

启用方式：同时设置 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1，然后设置 OTEL_TRACES_EXPORTER 选择发送目标。追踪复用通用 OTLP 配置的端点、协议、验证头和mTLS设置。

Spans 默认不记录用户提示文本、工具输入详情和工具内容。分别设置 OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1 和 OTEL_LOG_TOOL_CONTENT=1 可包含它们。

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

当链路追踪激活且 Claude Code 直接连接 Anthropic API 时，每个模型请求携带 W3C traceparent header（值为 claude_code.llm_request span 的上下文），API 返回的 traceresponse header 记录为 span 链接。该 header 不会发送给第三方提供商。

在 Agent SDK 和非交互式 -p 会话中，Claude Code 启动每个交互 span 时也会读取自身的 TRACEPARENT 和 TRACESTATE，使 Claude Code 的 spans 成为调用者分布式追踪的子 span。交互式 CLI 会话忽略传入的 TRACEPARENT，以避免意外继承 CI 或容器环境的值。

Span 层级 #

每个用户提示启动一个 claude_code.interaction 根 span。API 调用、工具调用和钩子执行记录为其子 span。工具 span 有两个子 span：一个等待权限决策的耗时，一个执行本身。当 Task 工具生成子代理时，子代理的 API 和工具 spans 嵌套在父级的 claude_code.tool span 下。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    （需要详细 beta 追踪）
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── （Task 工具）子代理的 claude_code.llm_request / claude_code.tool spans

在 Agent SDK 和 claude -p 会话中，当环境中设置了 TRACEPARENT 时，claude_code.interaction 本身会成为调用者 span 的子 span。

Span 属性 #

所有 spans 除标准属性外，还携带 span.type 属性（与 span 名称一致）。下面列出各 span 的额外属性。llm_request、tool.execution 和 hook spans 在记录失败时设置 OpenTelemetry status ERROR；其他 spans 始终以 status UNSET 结束。

claude_code.interaction

claude_code.llm_request

每次重试尝试还记录为 gen_ai.request.attempt span 事件，携带 attempt 和 client_request_id 属性。

claude_code.tool

当 OTEL_LOG_TOOL_CONTENT=1 时，此 span 还记录一个 tool.output span 事件，其属性包含工具输入和输出内容（每个属性截断至 60 KB）。

claude_code.tool.blocked_on_user

claude_code.tool.execution

claude_code.hook

该 span 仅在详细 beta 追踪激活时发出，需要在上述追踪导出配置外额外设置 ENABLE_BETA_TRACING_DETAILED=1 和 BETA_TRACING_ENDPOINT。在交互式 CLI 会话中，还需要组织被加入白名单。Agent SDK 和非交互式 -p 会话不受限制。

动态 Headers #

企业环境需要动态认证时，可配置脚本动态生成 Headers。动态 Headers 仅适用于 http/protobuf 和 http/json 协议。grpc 导出器仅使用静态 OTEL_EXPORTER_OTLP_HEADERS。

设置配置 #

在 .claude/settings.json 中添加：

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

脚本要求 #

脚本必须输出有效的 JSON 键值对（表示 HTTP Headers）：

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

刷新行为 #

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

多团队组织支持 #

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

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

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

重要格式要求：

• 使用逗号分隔的 key=value 对
• 不允许空格：user.organizationName=My Company 无效
• 只允许 US-ASCII 字符（不含控制字符、空白、双引号、逗号、分号、反斜杠）
• 特殊字符需要百分号编码
• 例如 org.name="My Company" 会包含字面双引号，不是 My Company

示例配置 #

在启动 claude 前设置这些环境变量。每组展示不同导出器或部署场景：

# 控制台调试（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=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# 指标和日志不同端点/后端
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

可用指标与事件 #

标准属性 #

所有指标和事件共享以下属性：

事件额外包含以下属性（不会附加到指标，因为会导致无限基数）：

• prompt.id：UUID，关联用户提示及之后的所有事件，直到下一个提示。参见事件关联属性。
• workspace.host_paths：桌面应用中选择的主机工作目录（字符串数组）

指标 #

Claude Code 导出以下指标：

指标详情 #

每个指标均包含标准属性。下面列出的指标具有额外上下文特定属性。

会话计数器：在每次会话开始时递增。额外属性：

• start_type："fresh"、"resume" 或 "continue"

代码行数计数器：添加或删除代码时递增。额外属性：

• type："added"、"removed"

Pull Request 计数器：通过 Shell 命令或 MCP 工具创建 PR/MR 时递增。

提交计数器：通过 Claude Code 创建 Git 提交时递增。

成本计数器：每次 API 请求后递增。属性包含 model、query_source（"main"、"subagent"、"auxiliary"）、speed（"fast" 或 absent）、effort（"low"、"medium"、"high"、"xhigh"、"max" 或 absent）、agent.name（内置和官方市场插件名称原样输出，用户定义名称替换为 "custom"）、skill.name（内置、捆绑、用户定义、官方市场原样输出，第三方插件替换为 "third-party"）、plugin.name、marketplace.name。

Token 计数器：每次 API 请求后递增。属性与成本计数器类似，额外 type 区分 token 类型。

代码编辑工具决策计数器：用户接受或拒绝 Edit、Write、NotebookEdit 工具时递增。额外属性：

• tool_name："Edit"、"Write"、"NotebookEdit"
• decision："accept"、"reject"
• source：决策来源，参见工具决策事件
• language：编辑文件的编程语言，如 "TypeScript"、"Python"、"JavaScript"、"Markdown"，未识别时返回 "unknown"

活跃时间计数器：跟踪 Claude Code 实际使用时间（排除空闲）。type 为 "user"（键盘交互）或 "cli"（工具执行和 AI 响应生成）。

事件 #

通过 OpenTelemetry 日志/事件协议导出以下事件（需配置 OTEL_LOGS_EXPORTER）。

事件关联属性 #

当用户提交一个提示时，Claude Code 可能发起多个 API 调用和运行多个工具。prompt.id 属性让你能将所有这些事件关联到触发它们的单个提示。

要追踪单个提示触发的所有活动，按特定 prompt.id 值过滤事件，将返回 user_prompt 事件、任何 api_request 事件和 tool_result 事件。

prompt.id 故意被排除在指标之外，因为每个提示产生唯一 ID 会导致时间序列无限增长。仅用于事件级分析和审计记录。

用户提示事件 #

用户提交提示时记录。事件名称：claude_code.user_prompt

属性：标准属性 + event.name、event.timestamp、event.sequence、prompt_length、prompt（默认脱敏，OTEL_LOG_USER_PROMPTS=1 启用）、command_name（内置和捆绑命令原样输出，别名按输入原样，自定义/插件/MCP 命令名默认隐藏，OTEL_LOG_TOOL_DETAILS=1 时原样）、command_source（"builtin"、"custom"、"mcp"，插件命令报告为 "custom"）

工具结果事件 #

工具完成执行时记录。事件名称：claude_code.tool_result

属性：标准属性 + event.name、event.timestamp、event.sequence、tool_name、tool_use_id（与钩子匹配）、success、duration_ms、error_type、error（OTEL_LOG_TOOL_DETAILS=1 时包含）、decision_type、decision_source、tool_input_size_bytes、tool_result_size_bytes、mcp_server_scope、tool_parameters（OTEL_LOG_TOOL_DETAILS=1 时包含 Bash 命令、MCP 服务器/工具名、技能名等，Git 提交成功时含 git_commit_id）、tool_input（OTEL_LOG_TOOL_DETAILS=1 时包含，单个值超 512 字符截断，总载荷约 4K 字符）

API 请求事件 #

每次向 Claude API 发送请求时记录。事件名称：claude_code.api_request

属性：标准属性 + event.name、event.timestamp、event.sequence、model、cost_usd、duration_ms、input_tokens、output_tokens、cache_read_tokens、cache_creation_tokens、request_id、speed、query_source、effort

API 错误事件 #

API 请求失败时记录。事件名称：claude_code.api_error

属性：标准属性 + event.name、event.timestamp、event.sequence、model、error、status_code（非 HTTP 错误时缺席）、duration_ms、attempt（总尝试次数）、request_id、speed、query_source、effort

API 请求体事件 #

当设置了 OTEL_LOG_RAW_API_BODIES 时，每个 API 请求尝试记录一次。事件名称：claude_code.api_request_body

属性：标准属性 + event.name、event.timestamp、event.sequence、body（内联模式，截断 60 KB，思维链内容脱敏；文件模式缺席）、body_ref（文件模式，绝对路径）、body_length、body_truncated、model、query_source

API 响应体事件 #

当设置了 OTEL_LOG_RAW_API_BODIES 时，每个成功 API 响应记录一次。事件名称：claude_code.api_response_body

属性：标准属性 + event.name、event.timestamp、event.sequence、body（内联模式，截断 60 KB，思维链内容脱敏）、body_ref（文件模式）、body_length、body_truncated、model、query_source、request_id

工具决策事件 #

工具权限决策（接受/拒绝）时记录。事件名称：claude_code.tool_decision

属性：标准属性 + event.name、event.timestamp、event.sequence、tool_name、tool_use_id、decision（"accept"、"reject"）、source（"config"、"hook"、"user_permanent"、"user_temporary"、"user_abort"、"user_reject"）。各来源含义：

• "config"：基于项目设置、个人设置、企业策略、--allowedTools/--disallowedTools、权限模式、会话范围授权，或工具本身安全，自动决策。
• "hook"：PreToolUse 或 PermissionRequest 钩子返回的决策。
• "user_permanent"：用户选择“是，以后别问”时。在 CLI 中只对本次选择发出，后续匹配规则时发出 "config"；在 SDK 或非交互式 -p 中，初始选择和后续匹配都发出 "user_permanent"。
• "user_temporary"：用户选择“是”一次性批准或“本次会话允许”时。类似上条的行为差异。
• "user_abort"：用户关闭权限提示未作答。
• "user_reject"：用户选择“否”或匹配拒绝规则。

权限模式变更事件 #

权限模式变更时记录（如 Shift+Tab 切换、退出规划模式、自动模式门控检查）。事件名称：claude_code.permission_mode_changed

属性：标准属性 + event.name、event.timestamp、event.sequence、from_mode、to_mode、trigger（"shift_tab"、"exit_plan_mode"、"auto_gate_denied"、"auto_opt_in"，来自 SDK 或桥接时缺席）

认证事件 #

/login 或 /logout 完成时记录。事件名称：claude_code.auth

属性：标准属性 + event.name、event.timestamp、event.sequence、action（"login"、"logout"）、success、auth_method、error_category、status_code

MCP 服务器连接事件 #

MCP 服务器连接、断开或连接失败时记录。事件名称：claude_code.mcp_server_connection

属性：标准属性 + event.name、event.timestamp、event.sequence、status（"connected"、"failed"、"disconnected"）、transport_type（"stdio"、"sse"、"http"）、server_scope（"user"、"project"、"local"）、duration_ms、error_code、server_name（OTEL_LOG_TOOL_DETAILS=1 时包含）、error（同上）

内部错误事件 #

Claude Code 捕获到意外的内部错误时记录。仅记录错误类名和 errno 风格代码，不包含错误信息和堆栈。在 Bedrock、Vertex、Foundry 上运行或设置了 DISABLE_ERROR_REPORTING 时不发出。事件名称：claude_code.internal_error

属性：标准属性 + event.name、event.timestamp、event.sequence、error_name（如 "TypeError"、"SyntaxError"）、error_code（如 "ENOENT"）

插件安装事件 #

插件安装完成时记录（来自 claude plugin install 命令或交互式 /plugin 界面）。事件名称：claude_code.plugin_installed

属性：标准属性 + event.name、event.timestamp、event.sequence、marketplace.is_official、install.trigger（"cli"、"ui"）、plugin.name、plugin.version、marketplace.name。第三方市场插件名称和版本需要 OTEL_LOG_TOOL_DETAILS=1 才输出。

插件加载事件 #

会话启动时每个已启用插件记录一次。用于盘点整个组织中的活跃插件。事件名称：claude_code.plugin_loaded

属性：标准属性 + event.name、event.timestamp、event.sequence、plugin.name（官方市场外和内置 bundle 外的插件值为 "third-party"，除非 OTEL_LOG_TOOL_DETAILS=1）、marketplace.name、plugin.version、plugin.scope（"official"、"org"、"user-local"、"default-bundle"）、enabled_via（"default-enable"、"org-policy"、"seed-mount"、"user-install"）、plugin_id_hash、has_hooks、has_mcp、skill_path_count、command_path_count、agent_path_count

技能激活事件 #

技能被调用时记录（通过 Skill 工具或 / 命令）。事件名称：claude_code.skill_activated

属性：标准属性 + event.name、event.timestamp、event.sequence、skill.name（用户定义和第三方插件技能占位为 "custom_skill"，除非 OTEL_LOG_TOOL_DETAILS=1）、invocation_trigger（"user-slash"、"claude-proactive"、"nested-skill"）、skill.source（"bundled"、"userSettings"、"projectSettings"、"plugin"）、plugin.name（当 OTEL_LOG_TOOL_DETAILS=1 或插件来自官方市场时）、marketplace.name（同上）

@提及事件 #

Claude Code 解析提示中的 @-mention 时记录。某些快速退出路径（如权限拒绝、文件过大、PDF 引用附件、目录列出失败）不记录。事件名称：claude_code.at_mention

属性：标准属性 + event.name、event.timestamp、event.sequence、mention_type（"file"、"directory"、"agent"、"mcp_resource"）、success（"true"、"false"）

API 重试耗尽事件 #

API 请求在超过一次尝试后仍失败时记录一次。与最终的 api_error 事件同时发出。事件名称：claude_code.api_retries_exhausted

属性：标准属性 + event.name、event.timestamp、event.sequence、model、error、status_code、total_attempts、total_retry_duration_ms、speed

钩子注册事件 #

每个配置的钩子在会话启动时记录一次。用于盘点整个组织中活跃的钩子。事件名称：claude_code.hook_registered

属性：标准属性 + event.name、event.timestamp、event.sequence、hook_event（如 "PreToolUse"、"PostToolUse"）、hook_type（"command"、"prompt"、"mcp_tool"、"http"、"agent"）、hook_source（"userSettings"、"projectSettings"、"localSettings"、"flagSettings"、"policySettings"、"pluginHook"）、hook_matcher（OTEL_LOG_TOOL_DETAILS=1）、plugin.name、plugin_id_hash

钩子执行开始事件 #

一个或多个钩子开始执行时记录。事件名称：claude_code.hook_execution_start

属性：标准属性 + event.name、event.timestamp、event.sequence、hook_event、hook_name（含匹配器，如 "PreToolUse:Write"）、num_hooks、managed_only、hook_source（"policySettings"、"merged"）、hook_definitions（仅当详细 beta 追踪和 OTEL_LOG_TOOL_DETAILS=1 同时启用）

钩子执行完成事件 #

某个钩子事件的所有钩子执行完毕时记录。事件名称：claude_code.hook_execution_complete

属性：标准属性 + event.name、event.timestamp、event.sequence、hook_event、hook_name、num_hooks、num_success、num_blocking、num_non_blocking_error、num_cancelled、total_duration_ms、managed_only、hook_source、hook_definitions

钩子插件指标事件 #

官方市场插件钩子发出每次调用指标时记录。只有从官方 Anthropic 市场安装的插件才能发出。事件名称：claude_code.hook_plugin_metrics

属性：标准属性 + event.name、event.timestamp、event.sequence、plugin_id（<name>@<marketplace> 格式）、hook_event、以及最多 20 个插件发出的指标键值（键名匹配 ^[a-z][a-z0-9_]{0,39}$，值为布尔或数字）

压缩事件 #

对话压缩完成时记录。事件名称：claude_code.compaction

属性：标准属性 + event.name、event.timestamp、event.sequence、trigger（"auto"、"manual"）、success、duration_ms、pre_tokens、post_tokens、error

反馈调查事件 #

会话质量调查显示或回答时记录。见会话质量调查。事件名称：claude_code.feedback_survey

属性：标准属性 + event.name、event.timestamp、event.sequence、event_type（如 "appeared"、"responded"、"transcript_prompt_appeared"）、appearance_id、survey_type（"session"）、response、enabled_via_override（布尔值，当设置了 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL 时为 true）

解读指标与事件数据 #

导出的指标和事件支持多种分析。

用量监控 #

成本监控 #

claude_code.cost.usage 指标可用于跟踪团队/个人趋势、识别高使用会话、通过 skill.name、plugin.name、agent.name 属性归因花费。

成本指标是近似值。官方账单数据请参考 API 提供商（Claude Console、Amazon Bedrock 或 Google Cloud Vertex）。

告警与细分 #

常见告警：成本激增、异常 Token 消耗、特定用户的高会话量。所有指标可按 user.account_uuid、user.account_id、organization.id、session.id、model、app.version 细分。

检测重试耗尽 #

Claude Code 内部重试失败的 API 请求，仅在放弃后发出一个 claude_code.api_error 事件。attempt 属性记录总尝试次数。大于 CLAUDE_CODE_MAX_RETRIES（默认 10）表示所有重试已耗尽。较低值表示不可重试的错误（如 400 响应）。要区分会话是恢复还是停滞，按 session.id 分组事件，检查错误后是否存在后续 api_request 事件。

事件分析 #

事件数据提供详尽的交互洞察：

工具使用模式：分析工具结果事件可识别最常用工具、成功率和执行时间、错误模式。

性能监控：跟踪 API 请求持续时间和工具执行时间，识别性能瓶颈。

审计安全事件 #

OpenTelemetry 事件是 Claude Code 活动的审计数据源。每个事件携带身份属性，将工具调用、MCP 活动和权限决策关联到触发它们的用户。OTLP 日志导出器可将这些事件发送到任何具有 OTLP 接收器的 SIEM 平台，或通过 OpenTelemetry Collector 转发。

属性归因到用户 #

标准属性包含认证用户身份：user.email、user.account_uuid、user.account_id、organization.id（通过 Claude 账户登录时），以及安装范围的 user.id 和会话的 session.id。MCP 工具调用、Bash 命令、文件编辑都归因于发起会话的开发者。Claude Code 不使用单独的服务账户。

当使用直接 API Key、Bedrock、Vertex AI 或 Microsoft Foundry 认证时，会话中没有 Claude 账户，仅填充 user.id 和 session.id。需要自己通过 OTEL_RESOURCE_ATTRIBUTES 附加用户身份：

export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

审计 MCP 活动 #

要捕获 MCP 服务器活动的完整调用详情，启用日志导出器并设置 OTEL_LOG_TOOL_DETAILS=1。每个 MCP 操作将生成结构化事件：

不设置 OTEL_LOG_TOOL_DETAILS 时，tool_result 仍携带 tool_name 和 mcp_server_scope，但省略 mcp_server_name/mcp_tool_name 细分和参数；mcp_server_connection 省略 server_name 和错误信息。

安全查询映射表 #

Claude Code 仅输出原始事件流。异常检测、基线建立、跨会话关联和告警是 SIEM 或可观测性后端的职责。

将事件发送到 SIEM #

将 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 指向 SIEM 的 OTLP 接收器，或指向 OpenTelemetry Collector（转发到 SIEM 的原生 ingest API）。以下托管设置示例仅导出事件，并启用完整的工具详情用于 MCP 和 Bash 审计：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

后端选择考虑 #

对于指标 #

• 时间序列数据库（如 Prometheus）：速率计算、聚合指标
• 列式存储（如 ClickHouse）：复杂查询、唯一用户分析
• 全功能可观测性平台（如 Honeycomb、Datadog）：高级查询、可视化、告警

对于事件/日志 #

• 日志聚合系统（如 Elasticsearch、Loki）：全文搜索、日志分析
• 列式存储（如 ClickHouse）：结构化事件分析
• 全功能可观测性平台：指标与事件关联

对于链路追踪 #

选择支持分布式追踪存储和 span 关联的后端：

• 分布式追踪系统（如 Jaeger、Zipkin、Grafana Tempo）：span 可视化、请求瀑布、延迟分析
• 全功能可观测性平台：追踪搜索并与指标/日志关联

对于需要 DAU/WAU/MAU 指标的组织，考虑支持高效唯一值查询的后端。

服务信息 #

所有指标和事件携带以下资源属性：

• service.name：claude-code
• service.version：当前 Claude Code 版本
• os.type：操作系统类型（如 linux、darwin、windows）
• os.version：操作系统版本字符串
• host.arch：主机架构（如 amd64、arm64）
• wsl.version：WSL 版本（仅在 Windows Subsystem for Linux 上存在）
• Meter Name：com.anthropic.claude_code

ROI 测量资源 #

关于 Claude Code 的投资回报率测量完整指南，包括遥测设置、成本分析、生产力指标和自动化报告，参见 Claude Code ROI Measurement Guide。该仓库提供了立即可用的 Docker Compose 配置、Prometheus 和 OpenTelemetry 设置，以及与 Linear 等工具集成的生产力报告生成模板。

安全与隐私 #

• OpenTelemetry 导出是选择加入的，需要显式配置。关于 Anthropic 的独立运营遥测以及如何禁用它，参见数据使用。
• 原始文件内容和代码片段不包括在指标或事件中。追踪 span 是独立的数据路径，见上文的 OTEL_LOG_TOOL_CONTENT 说明。
• 通过 OAuth 认证时，user.email 包含在遥测属性中。如果这是组织关注的问题，可在遥测后端过滤或脱敏该字段。
• 用户提示内容默认不收集，仅记录提示长度。设置 OTEL_LOG_USER_PROMPTS=1 可包含。
• 工具输入参数和参数默认不记录。设置 OTEL_LOG_TOOL_DETAILS=1 可包含。启用后，tool_result 事件包含 Bash 命令、MCP 服务器/工具名称、技能名称等；user_prompt 事件包含自定义、插件、MCP 命令的 command_name。单个值超过 512 字符截断，总载荷约 4K 字符。
• 工具输入和输出内容默认不在追踪 span 中记录。设置 OTEL_LOG_TOOL_CONTENT=1 可包含。启用后 span 事件包含完整输入/输出，每个 span 截断至 60 KB。这可能包含 Read 工具的文件内容、Bash 命令输出。需要配置后端过滤或脱敏。
• 原始 Anthropic Messages API 请求和响应体默认不记录。设置 OTEL_LOG_RAW_API_BODIES 可包含。=1 时内联截断 60 KB；=file:<dir> 时将未截断体写入指定目录，事件携带 body_ref 路径。两种模式都包含完整对话历史，启用该选项即表示同意其他 OTEL_LOG_* 内容标志的全部含义。

在 Amazon Bedrock 上监控 Claude Code #

关于 Amazon Bedrock 上 Claude Code 的详细用量监控指南，参见 Claude Code Monitoring Implementation (Bedrock)。

常见问题 #

如何启用 Claude Code 的 OpenTelemetry 监控？ #

需要设置环境变量 CLAUDE_CODE_ENABLE_TELEMETRY=1，并配置至少一个导出器（如 OTEL_METRICS_EXPORTER=otlp），以及对应的 OTLP 端点和认证。建议先以 console 导出器调试，确认数据格式后再切换到生产后端。

Claude Code 的遥测数据会不会发送到 Anthropic？ #

不会。OpenTelemetry 遥测数据只发送到你自己配置的 OTLP 端点（如 Grafana、Prometheus、Jaeger、Datadog 等）。Anthropic 不会接收这些数据。Claude Code 另有独立运营遥测用于产品改进，可通过 CLAUDE_CODE_ENABLE_TELEMETRY_SERVICE 或 DISABLE_ERROR_REPORTING 控制。

如何区分不同团队的用量和成本？ #

使用 OTEL_RESOURCE_ATTRIBUTES 添加自定义标签，如 department=engineering,team.id=platform。这些标签会附加到所有指标和事件上。在成本指标上还可以通过 agent.name、skill.name、plugin.name 属性进一步细分。