监控

了解如何为 Claude Code 启用和配置 OpenTelemetry。

通过 OpenTelemetry (OTel) 导出遥测数据，跟踪整个组织的 Claude Code 用量、成本和工具活动。Claude Code 使用标准指标协议将指标导出为时间序列数据，使用日志/事件协议导出事件，还可选择通过追踪协议导出分布式追踪。请根据监控需求配置指标、日志和追踪后端。

快速开始

使用环境变量配置 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

完整的配置选项请参阅 OpenTelemetry 规范。

管理员配置

管理员可以通过托管设置文件为所有用户配置 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 工具、Hook、MCP 服务器和语言服务器。因此，通过 Bash 工具运行、且已集成 OpenTelemetry 的应用程序不会继承 Claude Code 的导出端点或请求头。如果该应用需要导出自己的遥测数据，请直接在命令中设置这些变量。

配置详解

常用配置变量

mTLS 身份验证

如何为 OTLP 导出器配置客户端证书，取决于相应信号使用的 OTLP 协议；该协议通过 OTEL_EXPORTER_OTLP_PROTOCOL 或针对各信号的覆盖设置指定。指标、日志和追踪均使用同一套配置方式。

对于 grpc，OpenTelemetry SDK 会直接读取标准 OTLP 变量，因此，已有配置中针对指标设置的各信号变量仍可继续使用。

控制指标基数

以下环境变量用于控制指标中包含哪些属性，以管理基数：

这些变量有助于控制指标基数，而指标基数会影响指标后端的存储需求和查询性能。基数越低，通常性能越好、存储成本越低，但可供分析的数据粒度也会随之降低。

追踪（测试版）

分布式追踪会导出一组相互关联的 span，将每条用户 Prompt 与其触发的 API 请求和工具执行连接起来。这样，你便可以在追踪后端中将一次完整请求作为一条追踪查看。

追踪功能默认关闭。要启用，请同时设置 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1，再通过 OTEL_TRACES_EXPORTER 选择 span 的发送目标。端点、协议、请求头和 mTLS 均复用通用 OTLP 配置。

span 默认会隐去用户 Prompt 文本、工具输入详情和工具内容。设置 OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1 和 OTEL_LOG_TOOL_CONTENT=1 可将其包含在内。

启用追踪后，Bash 和 PowerShell 子进程会自动继承 TRACEPARENT 环境变量，其中包含当前工具执行 span 的 W3C 追踪上下文。凡是读取 TRACEPARENT 的子进程，都可以将自己的 span 置于同一条追踪下，从而对 Claude 所运行的脚本和命令实现端到端分布式追踪。

启用追踪且 Claude Code 直接连接 Anthropic API 时，每个模型请求都会携带 W3C traceparent 请求头，其值设置为 claude_code.llm_request span 的上下文；API 的 traceresponse 请求头则会记录为 span link。二者共同将 Claude Code 的客户端 span 经过任意符合规范的中间层连接到服务端追踪。出站 HTTP MCP 请求也会以同样方式携带 traceparent。该请求头不会发送给第三方提供商。

默认情况下，仅当 ANTHROPIC_BASE_URL 未设置或指向 Anthropic API 时，模型请求和 HTTP MCP 请求才会发送 traceparent 请求头，因为某些代理会拒绝无法识别的请求头。为保持一致，子进程的 TRACEPARENT 变量也由同一开关控制。如果通过自定义 ANTHROPIC_BASE_URL 代理运行 Claude Code，并希望传播追踪上下文，请设置 CLAUDE_CODE_PROPAGATE_TRACEPARENT=1。

在 Agent SDK 和以 -p 启动的非交互式会话中，Claude Code 还会在每个交互 span 启动时，从自身环境中读取 TRACEPARENT 和 TRACESTATE。这样，嵌入 Claude Code 的进程就能把当前 W3C 追踪上下文传给子进程，使 Claude Code 的 span 成为调用方分布式追踪的子级。交互式会话会忽略传入的 TRACEPARENT，以免意外继承 CI 或容器环境中的环境值。

Span 层级

每条用户 Prompt 都会启动一个 claude_code.interaction 根 span。API 调用、工具调用和 Hook 执行均记录为其子级。工具 span 还有两个自己的子 span：一个记录等待权限决定的时间，另一个记录工具本身的执行。当 Agent 工具或旧版 Task 工具启动子智能体时，子智能体的 API 和工具 span 会嵌套在父级 claude_code.tool span 之下。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans

在 Agent SDK 和 claude -p 会话中，如果环境里设置了 TRACEPARENT，claude_code.interaction 本身会成为调用方 span 的子级。

Span 属性

每个 span 都带有标准属性，另有一个与其名称相同的 span.type 属性。下表列出各类 span 设置的其他属性。llm_request、tool.execution 和 hook span 在记录失败时，会将 OpenTelemetry 状态设为 ERROR；其他 span 结束时的状态始终为 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。除上述追踪导出器配置外，这还要求设置 ENABLE_BETA_TRACING_DETAILED=1 和 BETA_TRACING_ENDPOINT。在交互式 CLI 会话中，还要求你的组织已加入该功能的允许列表。Agent SDK 和非交互式 -p 会话不受此限制。仅设置 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 时，不会发出此 span。

动态请求头

如果企业环境需要动态身份验证，可以配置一个脚本来动态生成请求头。动态请求头仅适用于 http/protobuf 和 http/json 协议。grpc 导出器只使用静态的 OTEL_EXPORTER_OTLP_HEADERS 值。

设置配置

在 .claude/settings.json 中添加：

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

该值可以是可执行文件路径（包括含空格的路径），也可以是带参数的 shell 命令行。在 Windows 上，该值始终通过 shell 运行，因此，如果 JSON 值中的路径含空格，需要用引号将路径括起来。

脚本要求

脚本必须输出有效的 JSON，其中使用字符串键值对表示 HTTP 请求头：

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

如果辅助脚本执行失败，或其输出不符合上述要求，Claude Code 会在以下位置报告错误：

• /status 输出
• 使用 --debug 运行时的调试日志，或在会话中运行 /debug 后的调试日志
• 以 -p 启动的非交互式会话的 stderr

刷新行为

请求头辅助脚本会在启动时运行，此后也会定期运行，以支持 Token 刷新。默认情况下，该脚本每 29 分钟运行一次。可以通过 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 环境变量自定义间隔。

多团队组织支持

拥有多个团队或部门的组织可以通过 OTEL_RESOURCE_ATTRIBUTES 环境变量添加自定义属性，以区分不同群组：

# 添加用于标识团队的自定义属性
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

所有指标和事件中都会包含这些自定义属性，因此你可以：

• 按团队或部门筛选指标
• 跟踪各成本中心的成本
• 创建团队专属仪表板
• 为特定团队设置警报

除了在 OTLP resource 块中发送这些值，Claude Code 还会将其作为属性附加到每个指标数据点和事件记录。大多数指标后端都会把数据点属性公开为可查询标签，因此可以直接按自定义键对指标进行分组和筛选。自定义键不会覆盖 user.id 或 session.id 等标准属性：发生键冲突时，Claude Code 会保留内置值。

每个自定义键都会成为所有指标序列上的标签，因此，高基数值会增加指标后端的存储成本。如果只想在 resource 块中发送自定义属性，而不将其用作数据点标签，请设置 OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false。请参阅控制指标基数。

export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

配置示例

运行 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

可用的指标和事件

标准属性

所有指标和事件都具有以下标准属性：

当 Claude Code 登录到 Claude 应用网关时，CLI 会在导出的数据中写入网关会话所提供的已验证身份：user.id 是 IdP subject，而非匿名安装标识符；user.email 是登录使用的电子邮件地址；user.groups 以逗号分隔的字符串保存 IdP 群组成员信息。每次导出还会带有 identity.source: gateway-oidc。网关身份最后应用，因此，在网关会话中通过 OTEL_RESOURCE_ATTRIBUTES 设置的 user.* 和 identity.* 键会被忽略。

事件还包含以下属性。由于这些属性会造成无界基数，因此绝不会附加到指标：

• prompt.id：用于关联一条用户 Prompt 与下一条 Prompt 之前所有后续事件的 UUID。请参阅事件关联属性。
• workspace.host_paths：在桌面应用中选择的主机工作区目录，以字符串数组表示
• workflow.run_id：在属于 Workflow 工具运行的智能体所发出的 API 和工具事件中，表示以 wf_ 开头的运行标识符。按同一个 workflow.run_id 筛选事件，即可重建该次运行的 API 请求和工具结果。该标识符涵盖工作流脚本启动的智能体，以及这些智能体继续启动的所有智能体，例如 Skill 调用。它与 Workflow 工具结果中报告的运行标识符一致。其他所有事件均无此属性。需要 Claude Code v2.1.202 或更高版本
• workflow.name：工作流名称，即其脚本的 meta.name，与 workflow.run_id 一同发出。使用未经修改的内置脚本运行时，内置工作流名称会按原样显示。除非设置 OTEL_LOG_TOOL_DETAILS=1，否则用户创建的名称（包括修改后的内置脚本副本）会替换为 custom。需要 Claude Code v2.1.202 或更高版本

指标

Claude Code 导出以下指标：

指标详解

每项指标都包含上面列出的标准属性。下文会特别注明具有其他上下文相关属性的指标。

会话计数器

每次会话开始时递增。

属性：

• 所有标准属性
• start_type：会话的启动方式。值为 "fresh"、"resume"、"continue" 或 "agents_view" 之一。"agents_view" 表示 claude agents 仪表板进程，即由用户启动的本地 UI，而不是对话会话。可在仪表板中按此值筛选，以区分 UI 进程启动与对话会话。

代码行计数器

添加或删除代码时递增。

属性：

• 所有标准属性
• type：（"added"、"removed"）
• model：执行该更改的模型标识符（例如 "claude-sonnet-5"）

拉取请求计数器

Claude Code 通过 shell 命令或 MCP 工具创建拉取请求或合并请求时递增。

属性：

• 所有标准属性

Commit 计数器

通过 Claude Code 创建 git commit 时递增。

属性：

• 所有标准属性

成本计数器

每次 API 请求后递增。

属性：

• 所有标准属性
• model：模型标识符（例如 "claude-sonnet-5"）
• query_source：发出请求的子系统类别。值为 "main"、"subagent" 或 "auxiliary" 之一
• speed：请求使用快速模式时为 "fast"，否则无此属性
• effort：应用于请求的 Effort 级别："low"、"medium"、"high"、"xhigh" 或 "max"。模型不支持 Effort 时无此属性。
• agent.name：发出请求的子智能体类型。内置智能体名称以及来自官方插件市场插件的智能体名称会按原样显示。其他用户定义的智能体名称会替换为 "custom"。请求并非由具名子智能体类型发出时无此属性。
• skill.name：请求中活跃的 Skill，由 Skill 工具、/ 命令设置，或由启动的子智能体继承。内置、捆绑、用户定义及官方插件市场插件的 Skill 名称会按原样显示。第三方插件 Skill 名称会替换为 "third-party"。没有活跃 Skill 时无此属性。
• plugin.name：当活跃的 Skill 或子智能体由插件提供时，表示所属插件。官方插件市场的插件名称会按原样显示。第三方插件名称会替换为 "third-party"。Skill 和子智能体均无所属插件时无此属性。
• marketplace.name：所属插件的安装来源插件市场。仅对官方插件市场的插件发出，其他情况无此属性。
• mcp_server.name：在生成此请求的交互轮次中运行过工具的 MCP 服务器。内置、由 claude.ai 代理以及来自官方注册表的服务器名称会按原样显示。用户配置的服务器名称会替换为 "custom"。未运行 MCP 工具时无此属性。
• mcp_tool.name：在生成此请求的交互轮次中运行过的 MCP 工具，其隐去规则与 mcp_server.name 相同。未运行 MCP 工具时无此属性。

Token 计数器

每次 API 请求后递增。

属性：

• 所有标准属性
• type：（"input"、"output"、"cacheRead"、"cacheCreation"）
• model：模型标识符（例如 "claude-sonnet-5"）
• query_source：发出请求的子系统类别。值为 "main"、"subagent" 或 "auxiliary" 之一
• speed：请求使用快速模式时为 "fast"，否则无此属性
• effort：应用于请求的 Effort 级别。详情请参阅成本计数器。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的 Skill、插件、智能体和 MCP 归因信息。有关定义和隐去规则，请参阅成本计数器。

代码编辑工具决定计数器

用户接受或拒绝使用 Edit、Write 或 NotebookEdit 工具时递增。

属性：

• 所有标准属性
• tool_name：工具名称（"Edit"、"Write"、"NotebookEdit"）
• decision：用户决定（"accept"、"reject"）
• source：决定来源。值为 "config"、"hook"、"user_permanent"、"user_temporary"、"user_abort" 或 "user_reject" 之一。各值的含义请参阅工具决定事件。
• language：已编辑文件的编程语言，例如 "TypeScript"、"Python"、"JavaScript" 或 "Markdown"。无法识别文件扩展名时返回 "unknown"。

活跃时间计数器

跟踪实际使用 Claude Code 的时间，不包括闲置时间。此指标会在用户交互期间递增，例如输入内容和阅读响应；也会在 CLI 处理期间递增，例如工具执行和 AI 响应生成。

属性：

• 所有标准属性
• type：键盘交互为 "user"，工具执行和 AI 响应为 "cli"

事件

配置 OTEL_LOGS_EXPORTER 后，Claude Code 会通过 OpenTelemetry 日志/事件导出以下事件：

事件关联属性

用户提交一条 Prompt 后，Claude Code 可能会进行多次 API 调用并运行多个工具。借助 prompt.id 属性，可以将所有这些事件关联回触发它们的同一条 Prompt。

要追踪一条 Prompt 所触发的全部活动，请按特定的 prompt.id 值筛选事件。结果会包含处理该 Prompt 期间发生的 user_prompt 事件、所有 api_request 事件和所有 tool_result 事件。

用户 Prompt 事件

用户提交 Prompt 时记录。

事件名称：claude_code.user_prompt

属性：

• 所有标准属性
• event.name："user_prompt"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• prompt_length：Prompt 长度
• prompt：Prompt 内容，默认隐去。设置 OTEL_LOG_USER_PROMPTS=1 可将其包含在内
• command_name：Prompt 调用命令时的命令名称。compact 或 debug 等内置和捆绑命令的名称会按原样发出；reset 等别名会按用户输入的形式发出，而不是使用其规范名称。除非设置 OTEL_LOG_TOOL_DETAILS=1，否则自定义命令、插件命令和 MCP 命令的名称会统一为 custom 或 mcp
• command_source：命令存在时的来源：builtin、custom 或 mcp。插件提供的命令报告为 custom

助手响应事件

每次 API 请求从模型返回文本内容后记录。仅包含响应中的文本块，不包含 thinking 块和工具使用块。需要 Claude Code v2.1.193 或更高版本。

事件名称：claude_code.assistant_response

属性：

• 所有标准属性
• event.name："assistant_response"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• response_length：响应文本长度（字符数）
• response：响应文本，在 60 KB 处截断。默认隐去为 <REDACTED>。设置 OTEL_LOG_ASSISTANT_RESPONSES=1 可将其包含在内。未设置 OTEL_LOG_ASSISTANT_RESPONSES 时，改由 OTEL_LOG_USER_PROMPTS 控制；因此，如果要在记录 Prompt 的同时继续隐去响应，请设置 OTEL_LOG_ASSISTANT_RESPONSES=0
• model：模型标识符（例如 "claude-sonnet-5"）
• request_id：响应的 request-id 请求头中的 Anthropic API 请求 ID。仅当 API 返回此值时才存在
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子智能体名称

工具结果事件

工具完成执行时记录。如果工具调用被拒绝，则不会发出此事件；有关拒绝记录，请参阅工具决定事件。

事件名称：claude_code.tool_result

属性：

• 所有标准属性
• event.name："tool_result"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• tool_name：工具名称
• tool_use_id：此次工具调用的唯一标识符。它与传给 Hook 的 tool_use_id 一致，可用于关联 OTel 事件与 Hook 捕获的数据。
• success："true" 或 "false"
• duration_ms：执行时间（毫秒）
• error_type：工具失败时的错误类别字符串，例如 "Error:ENOENT" 或 "ShellError"
• error（当 OTEL_LOG_TOOL_DETAILS=1 时）：工具失败时的完整错误消息
• decision_type：始终为 "accept"，因为只有工具运行后才会发出此事件。调用被拒绝时不会产生工具结果
• decision_source：权限决定的来源。值为 "config"、"hook"、"user_permanent" 或 "user_temporary" 之一。各值的含义请参阅工具决定事件。仅用于拒绝的来源 "user_abort" 和 "user_reject" 不会出现在此事件中。
• tool_input_size_bytes：JSON 序列化后工具输入的大小（字节）
• tool_result_size_bytes：工具结果的大小（字节）
• mcp_server_scope：MCP 服务器作用域标识符（适用于 MCP 工具）
• tool_parameters（当 OTEL_LOG_TOOL_DETAILS=1 时）：包含特定工具参数的 JSON 字符串：
  • 对于 Bash 工具：包括 bash_command、full_command、timeout、description、dangerouslyDisableSandbox 和 git_commit_id（git commit 命令成功时的 commit SHA）
  • 对于 WorkspaceBash 工具：包括 bash_command、full_command、timeout
  • 对于 MCP 工具：包括 mcp_server_name、mcp_tool_name
  • 对于 Skill 工具：包括 skill_name
  • 对于 Agent 工具或旧版 Task 工具：包括 subagent_type
• tool_input（当 OTEL_LOG_TOOL_DETAILS=1 时）：JSON 序列化后的工具实参。单个值超过 512 个字符时会被截断，完整载荷的上限约为 ~4 K 个字符。适用于所有工具，包括 MCP 工具。

API 请求事件

每次向 Claude 发出 API 请求时记录。

事件名称：claude_code.api_request

属性：

• 所有标准属性
• event.name："api_request"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• model：使用的模型（例如 "claude-sonnet-5"）
• cost_usd：预估成本（USD）
• duration_ms：请求持续时间（毫秒）
• input_tokens：输入 Token 数量
• output_tokens：输出 Token 数量
• cache_read_tokens：从缓存读取的 Token 数量
• cache_creation_tokens：用于创建缓存的 Token 数量
• request_id：响应的 request-id 请求头中的 Anthropic API 请求 ID，例如 "req_011..."。仅当 API 返回此值时才存在。
• speed："fast" 或 "normal"，表示是否启用了快速模式
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子智能体名称
• effort：应用于请求的 Effort 级别："low"、"medium"、"high"、"xhigh" 或 "max"。模型不支持 Effort 时无此属性。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的 Skill、插件、智能体和 MCP 归因信息。有关定义和隐去规则，请参阅成本计数器。

API 错误事件

向 Claude 发出的 API 请求失败时记录。

事件名称：claude_code.api_error

属性：

• 所有标准属性
• event.name："api_error"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• model：使用的模型（例如 "claude-sonnet-5"）
• error：错误消息
• status_code：以数字表示的 HTTP 状态码。连接失败等非 HTTP 错误没有此属性。
• duration_ms：请求持续时间（毫秒）
• attempt：尝试总次数，包括初始请求（1 表示未发生重试）
• request_id：响应的 request-id 请求头中的 Anthropic API 请求 ID，例如 "req_011..."。仅当 API 返回此值时才存在。
• speed："fast" 或 "normal"，表示是否启用了快速模式
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子智能体名称
• effort：应用于请求的 Effort 级别。模型不支持 Effort 时无此属性。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的 Skill、插件、智能体和 MCP 归因信息。有关定义和隐去规则，请参阅成本计数器。

API 拒绝事件

API 请求返回 stop_reason: "refusal" 时记录。拒绝发生在成功的响应流中，而不是以 HTTP 错误形式返回，因此不会触发 api_error 事件。借助此事件，可以跟踪拒绝频率，并按照与 api_request 和 api_error 相同的属性对拒绝进行分组。

事件名称：claude_code.api_refusal

属性：

• 所有标准属性
• event.name："api_refusal"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• model：请求中的模型标识符
• request_id：响应的 request-id 请求头中的 Anthropic API 请求 ID，例如 "req_011..."。仅当 API 返回此值时才存在。
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子智能体名称。有关定义，请参阅 api_request。
• speed：启用快速模式时为 "fast"，否则为 "normal"
• attempt：重试尝试序号。第一次尝试为 1。
• effort：应用于请求的 Effort 级别。模型不支持 Effort 时无此属性。
• server_fallback_hop：API 的服务端模型回退已使用其他模型重试此次拒绝，因而用户没有看到这次拒绝时为 true；请求最终以拒绝结束时为 false。如果回退模型也拒绝，同一轮交互既可能发出值为 true 的中间事件，也可能随后发出值为 false 的最终事件。
• has_category：API 响应携带的 stop_details.category 为 "cyber"、"bio"、"frontier_llm" 或 "reasoning_extraction" 时为 true；响应未携带类别或类别不在上述范围内时为 false。server_fallback_hop 为 true 时无此属性，因为中间回退块不包含 stop_details。
• has_explanation：API 响应携带 stop_details.explanation 时为 true，否则为 false。server_fallback_hop 为 true 时无此属性。
• category：API 响应中的 stop_details.category 值，为 "cyber"、"bio"、"frontier_llm" 或 "reasoning_extraction" 之一。仅当设置 OTEL_LOG_TOOL_DETAILS=1 且 has_category 为 true 时存在。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的 Skill、插件、智能体和 MCP 归因信息。有关定义和隐去规则，请参阅成本计数器。

API 请求正文事件

设置 OTEL_LOG_RAW_API_BODIES 后，每次 API 请求尝试都会记录。每次尝试发出一个事件，因此，使用调整后参数进行的每次重试都会产生单独的事件。

事件名称：claude_code.api_request_body

属性：

• 所有标准属性
• event.name："api_request_body"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• body：JSON 序列化的 Messages API 请求参数（系统 Prompt、消息、工具等），在 60 KB 处截断。之前助手交互轮次中的 extended-thinking 内容会被隐去。仅在直接记录模式（OTEL_LOG_RAW_API_BODIES=1）中发出。
• body_ref：指向 <dir>/<uuid>.request.json 文件的绝对路径，其中包含未截断的正文。仅在文件模式（OTEL_LOG_RAW_API_BODIES=file:<dir>）中发出。
• body_length：未截断的正文长度。当 OTEL_LOG_RAW_API_BODIES=file:<dir> 时以 UTF-8 字节计数；当值为 =1 时以 UTF-16 代码单元计数
• body_truncated：直接记录发生截断时为 "true"。在文件模式下以及未发生截断时无此属性。
• model：请求参数中的模型标识符
• query_source：发出请求的子系统（例如 "compact"）

API 响应正文事件

设置 OTEL_LOG_RAW_API_BODIES 后，每次 API 请求成功响应时都会记录。

事件名称：claude_code.api_response_body

属性：

• 所有标准属性
• event.name："api_response_body"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• body：JSON 序列化的 Messages API 响应（id、内容块、usage、停止原因），在 60 KB 处截断。extended-thinking 内容会被隐去。仅在直接记录模式（OTEL_LOG_RAW_API_BODIES=1）中发出。
• body_ref：指向 <dir>/<request_id>.response.json 文件的绝对路径，其中包含未截断的正文。仅在文件模式（OTEL_LOG_RAW_API_BODIES=file:<dir>）中发出。
• body_length：未截断的正文长度。当 OTEL_LOG_RAW_API_BODIES=file:<dir> 时以 UTF-8 字节计数；当值为 =1 时以 UTF-16 代码单元计数
• body_truncated：直接记录发生截断时为 "true"。在文件模式下以及未发生截断时无此属性。
• model：模型标识符
• query_source：发出请求的子系统
• request_id：响应的 request-id 请求头中的 Anthropic API 请求 ID，例如 "req_011..."。仅当 API 返回此值时才存在。

工具决定事件

作出工具权限决定（接受/拒绝）时记录。

事件名称：claude_code.tool_decision

属性：

• 所有标准属性
• event.name："tool_decision"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• tool_name：工具名称（例如 "Read"、"Edit"、"Write"、"NotebookEdit"）
• tool_use_id：此次工具调用的唯一标识符。它与传给 Hook 的 tool_use_id 一致，可用于关联 OTel 事件与 Hook 捕获的数据。
• decision："accept" 或 "reject"
• source：决定的来源：
  • "config"：根据项目设置、用户个人设置中的允许或拒绝规则、企业托管策略、--allowedTools 或 --disallowedTools 标志、当前权限模式、同一交互式 CLI 会话中较早 Prompt 授予的会话级权限，或工具本身是否安全，在不询问用户的情况下自动决定。该事件不会指明具体匹配了其中哪一种来源。
  • "hook"：由 PreToolUse 或 PermissionRequest Hook 返回决定。
  • "user_permanent"：用户在权限 Prompt 中选择“Yes, and don't ask again for ...”时发出；此操作会在用户个人设置中保存一条允许规则。在交互式 CLI 中，仅这次选择本身发出此值；之后匹配已保存规则的调用会改为发出 "config"。在 Agent SDK 或非交互式 -p 会话中，初始选择和后续规则匹配均发出 "user_permanent"。按接受处理。
  • "user_temporary"：用户在权限 Prompt 中选择“Yes”进行一次性批准，或在文件编辑/读取 Prompt 中选择某个“... during this session”选项时发出。在交互式 CLI 中，仅这次选择本身发出此值；之后由该会话级权限允许的调用会改为发出 "config"。在 Agent SDK 或非交互式 -p 会话中，初始选择和后续匹配均发出 "user_temporary"。按接受处理。
  • "user_abort"：用户未作答便关闭权限 Prompt 时发出。按拒绝处理。
  • "user_reject"：用户在 Prompt 中选择“No”时发出。在交互式 CLI 中，仅这次选择本身发出此值；之后匹配用户个人设置中拒绝规则的调用会改为发出 "config"。在 Agent SDK 或非交互式 -p 会话中，匹配个人设置中拒绝规则的调用会发出 "user_reject"。按拒绝处理。
• tool_parameters（当 OTEL_LOG_TOOL_DETAILS=1 时）：包含特定工具参数的 JSON 字符串。结构与工具结果事件相同，但不含 git_commit_id 等执行后字段。如果权限决定通过 updatedInput 重写了工具输入，已接受调用的此属性可能与 tool_result 不同。要查看被拒绝的具体命令，可以使用此属性，此时 decision 为 "reject"。
  • 对于 Bash 工具：包括 bash_command、full_command、timeout、description、dangerouslyDisableSandbox
  • 对于 WorkspaceBash 工具：包括 bash_command、full_command、timeout
  • 对于 MCP 工具：包括 mcp_server_name、mcp_tool_name
  • 对于 Skill 工具：包括 skill_name
  • 对于 Agent 工具或旧版 Task 工具：包括 subagent_type

权限模式更改事件

权限模式发生更改时记录，例如通过 Shift+Tab 循环切换、退出计划模式或进行自动模式 gate 检查。

事件名称：claude_code.permission_mode_changed

属性：

• 所有标准属性
• event.name："permission_mode_changed"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• from_mode：更改前的权限模式，例如 "default"、"plan"、"acceptEdits"、"auto" 或 "bypassPermissions"
• to_mode：更改后的权限模式
• trigger：触发更改的原因，为 "shift_tab"、"exit_plan_mode"、"auto_gate_denied" 或 "auto_opt_in" 之一。从 SDK 或 bridge 发起更改时无此属性

身份验证事件

/login 或 /logout 完成时记录。

事件名称：claude_code.auth

属性：

• 所有标准属性
• event.name："auth"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• action："login" 或 "logout"
• success："true" 或 "false"
• auth_method：身份验证方式，例如 "oauth"
• error_category：操作失败时的错误类别。绝不会包含原始错误消息
• status_code：操作因 HTTP 错误而失败时，以字符串表示的 HTTP 状态码

MCP 服务器连接事件

MCP 服务器连接、断开连接或连接失败时记录。

事件名称：claude_code.mcp_server_connection

属性：

• 所有标准属性
• event.name："mcp_server_connection"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• status："connected"、"failed" 或 "disconnected"
• transport_type：服务器传输方式，例如 "stdio"、"sse" 或 "http"
• server_scope：服务器的配置作用域，例如 "user"、"project" 或 "local"
• duration_ms：连接尝试的持续时间（毫秒）
• error_code：连接失败时的错误代码
• is_plugin：服务器由插件提供时为 true，否则为 false
• plugin_id_hash（当 is_plugin 为 true 时）：插件名称与插件市场的稳定哈希值，可在不披露名称的情况下按插件对事件分组
• plugin.name（当 is_plugin 为 true 时）：提供服务器的插件名称。对于第三方插件，除非设置 OTEL_LOG_TOOL_DETAILS=1，否则为字面字符串 "third-party"；这样可以避免第三方插件名称默认出现在日志中。来自 Anthropic 官方来源的插件始终按名称标识。plugin_id_hash 和 plugin.name 属性会传给你自己的监控后端，而不会发送给 Anthropic
• server_name（当 OTEL_LOG_TOOL_DETAILS=1 时）：配置的服务器名称
• error（当 OTEL_LOG_TOOL_DETAILS=1 时）：连接失败时的完整错误消息

内部错误事件

Claude Code 捕获到意外的内部错误时记录。只记录错误类名称和 errno 风格的代码，绝不会包含错误消息和堆栈跟踪。使用 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 时，或设置 DISABLE_ERROR_REPORTING 后，不会发出此事件。

事件名称：claude_code.internal_error

属性：

• 所有标准属性
• event.name："internal_error"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• error_name：错误类名称，例如 "TypeError" 或 "SyntaxError"
• error_code：错误中存在时的 Node.js errno 代码，例如 "ENOENT"

插件安装事件

通过 claude plugin install CLI 命令或交互式 /plugin UI 安装插件完成时记录。

事件名称：claude_code.plugin_installed

属性：

• 所有标准属性
• event.name："plugin_installed"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• marketplace.is_official：插件市场为 Anthropic 官方插件市场时为 "true"，否则为 "false"
• install.trigger："cli" 或 "ui"
• plugin.name：已安装插件的名称。对于第三方插件市场，仅当 OTEL_LOG_TOOL_DETAILS=1 时包含
• plugin.version：插件市场条目中声明的插件版本。对于第三方插件市场，仅当 OTEL_LOG_TOOL_DETAILS=1 时包含
• marketplace.name：插件的安装来源插件市场。对于第三方插件市场，仅当 OTEL_LOG_TOOL_DETAILS=1 时包含

插件加载事件

会话启动时，为每个已启用插件记录一次。可使用此事件盘点整个设备群中处于活跃状态的插件；它是记录安装操作本身的 plugin_installed 的补充。

事件名称：claude_code.plugin_loaded

属性：

• 所有标准属性
• event.name："plugin_loaded"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• plugin.name：插件名称。对于官方插件市场和内置捆绑包以外的插件，除非设置 OTEL_LOG_TOOL_DETAILS=1，否则值为 "third-party"
• marketplace.name：插件的安装来源插件市场（如果已知）。隐去条件与 plugin.name 相同时，隐去为 "third-party"
• 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：插件是否提供 Hook
• has_mcp：插件是否提供 MCP 服务器
• host_owned_mcp：SDK host 管理该插件的 MCP 连接、且 Claude Code 跳过读取插件 MCP 服务器配置时为 true，否则为 false。需要 Claude Code v2.1.172 或更高版本
• skill_path_count：插件声明的 Skill 目录数量
• command_path_count：插件声明的命令目录数量
• agent_path_count：插件声明的智能体目录数量
• safe_mode：会话通过 --safe-mode 启动时为 "true"，否则为 "false"。在安全模式下，此事件仅报告配置清单；插件的命令、Skill、Hook 和 MCP 服务器不会加载。需要 Claude Code v2.1.169 或更高版本

Skill 激活事件

调用 Skill 时记录，无论是 Claude 通过 Skill 工具调用，还是你将其作为 / 命令运行。

事件名称：claude_code.skill_activated

属性：

• 所有标准属性
• event.name："skill_activated"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• skill.name：Skill 名称。对于用户定义及第三方插件提供的 Skill，除非设置 OTEL_LOG_TOOL_DETAILS=1，否则值为占位符 "custom_skill"
• invocation_trigger：Skill 的触发方式（"user-slash"、"claude-proactive" 或 "nested-skill"）
• skill.source：Skill 的加载来源（例如 "bundled"、"userSettings"、"projectSettings"、"plugin"）
• skill.kind：Skill 为工作流 Skill 时为 "workflow"，否则无此属性
• plugin.name（当 OTEL_LOG_TOOL_DETAILS=1 或插件来自官方插件市场时）：Skill 由插件提供时的所属插件名称
• marketplace.name（当 OTEL_LOG_TOOL_DETAILS=1 或插件来自官方插件市场时）：Skill 由插件提供时，该插件的安装来源插件市场

@ 提及事件

Claude Code 解析 Prompt 中的 @ 提及时记录。并非每次提及都会发出事件：遇到权限被拒绝、文件过大、PDF 引用附件和目录列表失败等提前退出路径时，会直接返回而不记录事件。

事件名称：claude_code.at_mention

属性：

• 所有标准属性
• event.name："at_mention"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• mention_type：提及类型（"file"、"directory"、"agent"、"mcp_resource"）
• success：提及是否成功解析（"true" 或 "false"）

API 重试耗尽事件

API 请求在多次尝试后仍然失败时记录一次，与最终的 api_error 事件一同发出。

事件名称：claude_code.api_retries_exhausted

属性：

• 所有标准属性
• event.name："api_retries_exhausted"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• model：使用的模型
• error：最终错误消息
• status_code：以数字表示的 HTTP 状态码。连接失败等非 HTTP 错误没有此属性。
• total_attempts：尝试总次数
• total_retry_duration_ms：所有尝试的总实际耗时
• speed："fast" 或 "normal"

Hook 注册事件

会话启动时，为每个已配置 Hook 记录一次。可使用此事件盘点整个设备群中处于活跃状态的 Hook；它是记录每次执行的 hook_execution_start 和 hook_execution_complete 事件的补充。

事件名称：claude_code.hook_registered

属性：

• 所有标准属性
• event.name："hook_registered"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• hook_event：Hook 事件类型，例如 "PreToolUse" 或 "PostToolUse"
• hook_type：Hook 实现类型："command"、"prompt"、"mcp_tool"、"http" 或 "agent"
• hook_source：Hook 的定义位置："userSettings"、"projectSettings"、"localSettings"、"flagSettings"、"policySettings" 或 "pluginHook"
• safe_mode：会话通过 --safe-mode 启动时为 "true"，否则为 "false"。需要 Claude Code v2.1.169 或更高版本
• hook_matcher（当 OTEL_LOG_TOOL_DETAILS=1 时）：Hook 配置中的 matcher 字符串（如有设置）
• plugin.name（当 hook_source 为 "pluginHook" 时）：提供该 Hook 的插件名称。对于官方插件市场和内置捆绑包以外的插件，除非设置 OTEL_LOG_TOOL_DETAILS=1，否则值为 "third-party"
• plugin_id_hash（当 hook_source 为 "pluginHook" 时）：由插件名称和插件市场生成的确定性哈希值，仅发送给你配置的导出器。借助此值，可以统计不同的 Hook 来源插件，而无需记录插件名称

Hook 执行开始事件

某个 Hook 事件的一个或多个 Hook 开始执行时记录。

事件名称：claude_code.hook_execution_start

属性：

• 所有标准属性
• event.name："hook_execution_start"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• hook_event：Hook 事件类型，例如 "PreToolUse" 或 "PostToolUse"
• hook_name：包含 matcher 的完整 Hook 名称，例如 "PreToolUse:Write"
• num_hooks：匹配的 Hook 命令数量
• managed_only：仅允许托管策略 Hook 时为 "true"
• hook_source："policySettings" 或 "merged"
• safe_mode：会话通过 --safe-mode 启动时为 "true"，否则为 "false"。需要 Claude Code v2.1.169 或更高版本
• hook_definitions：JSON 序列化的 Hook 配置。仅当同时启用详细测试版追踪和 OTEL_LOG_TOOL_DETAILS=1 时包含

Hook 执行完成事件

某个 Hook 事件的所有 Hook 均完成时记录。

事件名称：claude_code.hook_execution_complete

属性：

• 所有标准属性
• event.name："hook_execution_complete"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• hook_event：Hook 事件类型
• hook_name：包含 matcher 的完整 Hook 名称
• num_hooks：匹配的 Hook 命令数量
• num_success：成功完成的数量
• num_blocking：返回阻止决定的数量
• num_non_blocking_error：失败但未阻止操作的数量
• num_cancelled：完成前被取消的数量
• total_duration_ms：所有匹配 Hook 的实际耗时
• managed_only：仅允许托管策略 Hook 时为 "true"
• hook_source："policySettings" 或 "merged"
• safe_mode：会话通过 --safe-mode 启动时为 "true"，否则为 "false"。需要 Claude Code v2.1.169 或更高版本
• hook_definitions：JSON 序列化的 Hook 配置。仅当同时启用详细测试版追踪和 OTEL_LOG_TOOL_DETAILS=1 时包含

Hook 插件指标事件

当官方插件市场插件的 Hook 发出每次调用的指标时记录。只有从 Anthropic 官方插件市场安装的插件才能发出此类事件；第三方插件市场的插件和用户配置的 Hook 不会发出。可通过自己的可观测性堆栈使用此事件，监控插件的发现率、成本和持续时间等行为。

事件名称：claude_code.hook_plugin_metrics

属性：

• 所有标准属性
• event.name："hook_plugin_metrics"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• plugin_id：<name>@<marketplace> 格式的插件标识符
• hook_event：发出指标的 Hook 事件类型
• 最多 20 个由插件发出的指标键。名称须匹配 ^[a-z][a-z0-9_]{0,39}$，值为布尔值或数字。

压缩事件

对话压缩完成时记录。

事件名称：claude_code.compaction

属性：

• 所有标准属性
• event.name："compaction"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• trigger："auto" 或 "manual"
• success："true" 或 "false"
• duration_ms：压缩持续时间
• pre_tokens：压缩前的大致 Token 数量
• post_tokens：压缩后的大致 Token 数量
• error：压缩失败时的错误消息
• precompute_reuse：仅当 trigger 为 "manual" 时设置。自动压缩可以在上下文窗口填满前在后台准备摘要，此属性用于记录 /compact 是否复用了预先准备的摘要。"hit" 表示已复用；"miss_custom_instructions"、"miss_hook" 和 "miss_not_ready" 分别表示未复用、改为重新计算摘要的原因。需要 Claude Code v2.1.153 或更高版本

反馈调查事件

显示会话质量调查或用户回答调查时记录。有关调查收集的内容及控制方式，请参阅会话质量调查。

事件名称：claude_code.feedback_survey

属性：

• 所有标准属性
• event.name："feedback_survey"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于确定会话内事件的顺序
• event_type：调查生命周期事件，例如 "appeared"、"responded" 或 "transcript_prompt_appeared"
• appearance_id：用于关联同一次调查所发出事件的唯一 ID
• survey_type：产生该事件的调查类型。"session" 表示“How is Claude doing?”评分 Prompt
• response：responded 事件中的用户选择
• enabled_via_override：设置 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL 时为 true。以布尔值而不是字符串发出。存在于 session 调查事件中。可按此属性筛选，以确认覆盖设置是否已应用到整个设备群

解读指标和事件数据

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

用量监控

成本监控

claude_code.cost.usage 指标可以帮助你：

• 跟踪团队或个人的用量趋势
• 找出需要优化的高用量会话
• 通过 skill.name、plugin.name 和 agent.name 属性，将支出归因到特定 Skill、插件或子智能体类型

警报与细分

可以考虑设置以下常见警报：

• 成本激增
• Token 消耗异常
• 特定用户的会话量过高

所有指标都可以按标准属性进行细分。model 属性可用于 claude_code.token.usage、claude_code.cost.usage，以及自 v2.1.172 起的 claude_code.lines_of_code.count。

由于一次会话可能跨越多个模型，因此，只有将 commit 与 Token 或成本指标按 session.id 联接，才能近似按模型细分 commit。请将 Token 或成本一侧筛选为 query_source 等于 "main" 的行，避免辅助请求和子智能体请求将会话中的 commit 归因给并未生成这些 commit 的模型。

检测重试耗尽

Claude Code 会在内部重试失败的 API 请求，并只在最终放弃后发出一个 claude_code.api_error 事件，因此，该事件本身就是相应请求的终止信号。中间的重试不会记录为单独事件。

事件的 attempt 属性记录尝试总次数。CLAUDE_CODE_MAX_RETRIES 的默认值为 10，上限为 15；自 v2.1.199 起，CLAUDE_CODE_RETRY_WATCHDOG 会提高默认值并取消上限。当请求因瞬时错误而耗尽所有重试时，attempt 等于实际生效限制加一：默认为 11；未设置 watchdog 时，绝不会超过 16。如果该值更低，则表示遇到了不可重试的错误，例如 400 响应。

要区分已经恢复的会话与停滞的会话，请按 session.id 对事件分组，并检查错误之后是否存在 api_request 事件。

事件分析

事件数据可以帮助你深入了解 Claude Code 交互：

工具使用模式：分析工具结果事件，以确定：

• 最常用的工具
• 工具成功率
• 工具平均执行时间
• 各工具类型的错误模式

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

审计安全事件

OpenTelemetry 事件是 Claude Code 活动的审计数据源。每个事件都带有身份属性，可将工具调用、MCP 活动和权限决定关联回触发它们的用户。OTLP 日志导出器可以把这些事件发送到任何带有 OTLP 接收器的安全信息和事件管理 (SIEM) 平台，也可以发送到 OpenTelemetry Collector，再由后者转发至 SIEM。

将操作归因到用户

每个事件的标准属性都包含已验证用户的身份：使用 Claude 账户登录时，包括 user.email、user.account_uuid、user.account_id 和 organization.id，另有 user.id 以及各会话的 session.id。user.id 是安装范围内的标识符；但在 Claude 应用网关会话中，它是网关所发 Token 中的 IdP subject。

因此，MCP 工具调用、Bash 命令和文件编辑都会归因到启动会话的开发者。Claude Code 不会以单独的服务账户身份操作；每个事件所记录的身份是开发者自己的 Claude 账户，或 Claude 应用网关会话中开发者的 IdP 身份。

当 Claude Code 使用直接 API key 进行身份验证，或者连接 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 时，会话中没有 Claude 账户，因此只会填充 user.id 和 session.id。在这些部署中，请自行通过 OTEL_RESOURCE_ATTRIBUTES 附加用户身份，并使用托管设置文件或启动包装程序为每位用户分别设置。Claude 应用网关会话无需这样做：如标准属性所述，CLI 会自动写入 IdP 身份。

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 和实参
• tool_decision：保留 tool_name，省略 tool_parameters
• mcp_server_connection：省略 server_name 和错误消息，但保留 is_plugin、plugin_id_hash 和 plugin.name；非 Anthropic 插件的名称会隐去为字面值 "third-party"，因此，即使未启用详细日志，仍可区分由不同插件提供的服务器

将安全问题映射到事件

构建检测规则时，请先找到要监控的信号，再在后端中查询相应事件和属性：

Claude Code 只发出原始事件流。异常检测、基线建立、跨会话关联和警报均由 SIEM 或可观测性后端负责。

将事件发送到 SIEM

将 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 指向 SIEM 的 OTLP 接收器，或指向会将数据转发到 SIEM 原生摄取 API 的 OpenTelemetry Collector。以下托管设置示例只导出事件，并启用完整工具详情，以审计 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、Grafana Cloud）：高级查询、可视化、警报

事件/日志后端

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

追踪后端

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

• 分布式追踪系统（例如 Jaeger、Zipkin、Grafana Tempo）：span 可视化、请求瀑布图、延迟分析
• 全功能可观测性平台（例如 Honeycomb、Datadog、Grafana Cloud）：追踪搜索，以及与指标和日志的关联

如果组织需要日活跃用户数/周活跃用户数/月活跃用户数 (DAU/WAU/MAU) 指标，请考虑支持高效唯一值查询的后端。

服务信息

导出所有指标和事件时，都会附带以下 resource 属性：

• 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 名称：com.anthropic.claude_code

ROI 衡量资源

如需全面了解如何衡量 Claude Code 的投资回报率，包括遥测设置、成本分析、生产力指标和自动报告，请参阅 Claude Code ROI 衡量指南。该仓库提供可直接使用的 Docker Compose 配置、Prometheus 和 OpenTelemetry 设置，以及用于生成生产力报告的模板，并可与 Linear 等工具集成。

安全与隐私

• 是否向你的后端导出 OpenTelemetry 数据由你选择，必须经过明确配置才会启用。有关 Anthropic 单独收集的运行遥测数据及其禁用方法，请参阅数据使用
• 指标和事件中不包含原始文件内容或代码片段。追踪 span 使用单独的数据路径：请参阅下面关于 OTEL_LOG_TOOL_CONTENT 的条目
• 通过 OAuth 进行身份验证时，遥测属性中会包含 user.email。如果组织对此有顾虑，请使用遥测后端筛选或隐去此字段
• 默认不收集用户 Prompt 内容，只记录 Prompt 长度。要包含 Prompt 内容，请设置 OTEL_LOG_USER_PROMPTS=1
• 默认不收集助手响应文本，只记录响应长度。要包含响应文本，请设置 OTEL_LOG_ASSISTANT_RESPONSES=1。和 Claude Code 的所有 OpenTelemetry 数据一样，响应文本只会发送到你配置的 OTel 端点，绝不会发送给 Anthropic。未设置此变量时，会回退使用 OTEL_LOG_USER_PROMPTS；因此，如果希望包含 Prompt 内容但不包含响应内容，请设置 OTEL_LOG_ASSISTANT_RESPONSES=0
• 默认不记录工具输入实参和参数。要包含这些内容，请设置 OTEL_LOG_TOOL_DETAILS=1。这些数据只会发送到你配置的 OTEL 端点，绝不会发送给 Anthropic。实参仍可能包含敏感值，请根据需要配置遥测后端，以筛选或隐去这些属性。启用后：
  • tool_result 和 tool_decision 事件会包含 tool_parameters 属性，其中带有 Bash 命令、MCP 服务器和工具名称，以及 Skill 名称。full_command 等字段不会截断
  • tool_result 事件还会包含 tool_input 属性，其中带有文件路径、URL、搜索模式和其他实参。单个值超过 512 个字符时会被截断，总长度上限约为 ~4 K 个字符
  • user_prompt 事件会包含自定义命令、插件命令和 MCP 命令逐字不变的 command_name
  • 追踪 span 会包含相同的 tool_input 属性，以及 file_path 等从输入派生的属性；截断方式与 tool_input 相同
• 默认不在追踪 span 中记录工具输入和输出内容。要包含这些内容，请设置 OTEL_LOG_TOOL_CONTENT=1。启用后，span 事件会包含完整的工具输入和输出内容，每个 span 在 60 KB 处截断。其中可能包含 Read 工具结果中的原始文件内容和 Bash 命令输出。请根据需要配置遥测后端，以筛选或隐去这些属性
• 默认不记录原始 Anthropic Messages API 请求和响应正文。要包含这些内容，请设置 OTEL_LOG_RAW_API_BODIES。设为 =1 时，每次 API 调用都会发出 api_request_body 和 api_response_body 日志事件，其 body 属性为 JSON 序列化的载荷，并在 60 KB 处截断。设为 =file:<dir> 时，未截断正文会写入该目录下的 .request.json 和 .response.json 文件，事件则携带 body_ref 路径，而不是直接包含正文。请使用日志收集器或 sidecar 传输该目录，而不要通过遥测流传输。在这两种模式下，正文都包含完整对话历史（系统 Prompt、之前的每一轮用户和助手交互、工具结果），因此，启用此项即表示同意披露其他 OTEL_LOG_* 内容标志可能披露的全部内容。无论其他设置如何，Claude 的 extended-thinking 内容始终会从这些正文中隐去

在 Amazon Bedrock 上监控 Claude Code

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