监控

​

快速开始

# 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

​

管理员配置

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

​

托管设置如何锁定 OTLP 目标

• 端点：当您设置 OTEL_EXPORTER_OTLP_ENDPOINT 时，Claude Code 会删除每个开发者设置的每信号端点。开发者无法将一个信号指向不同的收集器，因此您不需要在托管设置中也设置每信号端点变量。
• 协议：当您设置 OTEL_EXPORTER_OTLP_PROTOCOL 时，Claude Code 会删除每个开发者设置的每信号协议。
• 凭证：当您设置 OTEL_EXPORTER_OTLP_HEADERS、OTEL_EXPORTER_OTLP_CLIENT_KEY 或 OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE 时，Claude Code 会删除开发者设置的该变量的每信号版本，以及每个开发者设置的端点变量（通用或每信号），因为这些凭证否则会到达托管设置未选择的收集器。
• 导出器选择器：OTEL_METRICS_EXPORTER、OTEL_LOGS_EXPORTER 和测试版 OTEL_TRACES_EXPORTER 遵循正常的每键优先级。开发者的设置仍然可以禁用信号或将其切换到控制台导出器，因此如果您需要锁定选择器，也请在托管设置中设置它们。在 管理员源 中，OTEL_LOGS_EXPORTER 遵循 遥测单元，而其他两个选择器按键合并。需要 Claude Code v2.1.223 或更高版本。
• 测试版追踪端点：当 详细测试版追踪 处于活动状态时，Claude Code 将日志和追踪导出到 BETA_TRACING_ENDPOINT 而不是通过日志和追踪导出器。因此，当这些托管设置中的任何一个决定任一信号的目标时，Claude Code 会删除开发者设置的 BETA_TRACING_ENDPOINT：
  • 通用或日志/追踪端点或凭证
  • 一个 otelHeadersHelper
  • 日志或追踪导出器选择器设置为 none、console 或空，这些值使信号远离收集器
  • CLAUDE_CODE_ENABLE_TELEMETRY 关闭
  仅限指标的端点或凭证不会删除它。在 v2.1.251 之前，开发者设置的 BETA_TRACING_ENDPOINT 会重定向详细测试版追踪导出的日志和追踪，即使托管设置固定了收集器。

​

配置详情

​

常见配置变量

​

mTLS 身份验证

​

指标基数控制

​

Traces（测试版）

​

跨度层次结构

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

​

跨度属性

• 对除 Read、Edit、Write、Bash、WebFetch、WebSearch 和 MCP 工具之外的任何工具的调用
• 返回除文件文本之外的任何内容的 Read，例如图像、PDF 或重新读取内容未更改的文件
• Edit 或 Write 调用，除非您也设置 OTEL_LOG_TOOL_DETAILS=1
• Claude Code 在运行期间移到后台、以便等待中的消息能够送达 Claude 的 WebFetch 或 WebSearch 调用。稍后到达的结果也不会被记录。要了解 Claude Code 何时移动调用，对于终端请参阅Claude Code 何时发送您排队的内容，对于 Agent SDK 会话请参阅 priority 字段

​

动态标头

​

设置配置

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

​

脚本要求

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

• 交互式会话中的警告通知，otelHeadersHelper failed; telemetry is not being exported，在助手首次失败时每个会话显示一次
• /status 输出
• 调试日志，当使用 --debug 运行或在会话中运行 /debug 后
• stderr，在使用 -p 启动的非交互式会话中

​

刷新行为

​

多团队组织支持

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

• 按团队或部门过滤指标
• 按成本中心跟踪成本
• 创建特定于团队的仪表板
• 为特定团队设置警报

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

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

​

将遥测归因到 Desktop SSH 会话

{
  "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_RESOURCE_ATTRIBUTES": "host.name=build-7"
  }
}

• 您在运行 Desktop 的计算机上设置了它：Desktop 不会将您在那里设置的值传递给 SSH 会话
• 您在登录文件中导出了它：只有登录 shell 会读取 /etc/profile 之类的文件。您在其中 export 的值会传递给从登录 shell 启动的 Claude Code。它不会传递到 Desktop SSH 会话，因为 Desktop 不通过登录 shell 启动 Claude Code。
• 某个值内部包含空格：此时 Claude Code 不会将任何键复制到事件或数据点上，也不会报告错误。从值中去掉空格。
• 其他来源已经设置了该变量：在桌面应用启动的会话中，启动环境中已设置的变量优先于设置文件。调试日志会列出每个被忽略的变量。当第三方 Desktop 部署在其提供的环境中指定 OTLP 端点时，该环境会带有 Desktop 自己的 OTEL_RESOURCE_ATTRIBUTES。

​

示例配置

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

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_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 Tag 的遥测

• 服务器管理的设置：将它们添加到您组织的服务器管理的设置的 env 块中。Claude Code 在启动时会在服务器管理的设置适用的任何地方获取这些设置，这包括您用户的机器和除 Claude Tag 频道会话外的云会话。Claude Tag 会话不会接收您的服务器管理的设置，因此此路由不会配置它们。
• 环境的变量：将它们添加到云环境的环境变量中，以仅配置在该环境中运行的会话。这是到达 Claude Tag 会话的路由。

• 让会话到达收集器：Claude Code 通过会话的网络发送导出，因此它是否到达您的 OTEL_EXPORTER_OTLP_ENDPOINT 中的主机取决于环境的网络访问级别。如果会话无法在您选择的级别上到达收集器的域，请将域添加到环境的允许列表，因为没有服务器管理的设置会将域添加到环境的网络允许列表。
• Claude Tag 频道使用组织级别的环境：频道会话在组织级别的环境中运行，而不是成员的个人环境中，因此请在共享环境上进行允许列表和任何环境变量更改，该环境设置为您组织的默认环境或固定到频道。
• Cowork 单独配置：如表面覆盖表所示，Cowork 会话不会接收服务器管理的设置，因此服务器管理的 env 块不会配置其遥测。

​

将遥测属性分配给云会话

• 识别 Claude Tag 会话：设置 OTEL_METRICS_INCLUDE_ENTRYPOINT=true，如指标基数控制下所述。指标随后会携带 app.entrypoint，其值对于 Claude Tag 会话为 claude-in-slack。
• 添加自定义属性：在设置这些会话的其他 OTEL_* 变量的同一位置设置 OTEL_RESOURCE_ATTRIBUTES。如果您改为在环境的设置脚本中 export 它，该值不会到达 Claude Code：设置脚本是在 Claude Code 启动前运行的单独 Bash 脚本，它导出的变量随之结束。

​

可用的指标和事件

​

标准属性

• prompt.id：将用户提示词与其后直到下一个提示词之前的所有事件关联起来的 UUID。请参阅事件关联属性。
• workspace.host_paths：在桌面应用中选择的主机工作区目录，以字符串数组形式表示
• workflow.run_id：运行标识符，以 wf_ 为前缀，出现在属于某次 Workflow 工具运行的 Agent 所发出的 API 和工具事件上。按某个 workflow.run_id 过滤事件即可重建该次运行的 API 请求和工具结果。该标识符涵盖工作流脚本生成的 Agent，以及这些 Agent 进一步生成的任何 Agent，例如 skill 调用。它与 Workflow 工具结果中报告的运行标识符一致。其他所有事件上均不存在该属性。
• workflow.name：工作流的名称，即其脚本的 meta.name，与 workflow.run_id 一起发出。当运行执行未经修改的内置脚本时，内置工作流名称按原样显示。用户编写的名称（包括内置脚本的编辑副本）会被替换为 custom，除非设置了 OTEL_LOG_TOOL_DETAILS=1。

​

仓库属性

​

指标

​

指标详情

​

会话计数器

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

​

代码行数计数器

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

​

Pull Request 计数器

• 所有标准属性

​

提交计数器

• 所有标准属性

​

成本计数器

• 所有标准属性
• model：模型标识符（例如 “claude-sonnet-5”）
• query_source：发出请求的子系统类别。取值为 "main"、"subagent" 或 "auxiliary" 之一
• speed：当请求使用快速模式时为 "fast"。否则不存在
• effort：应用于请求的 effort 级别："low"、"medium"、"high"、"xhigh" 或 "max"。当 Claude Code 未发送 effort 级别时不存在，例如在不支持 effort 的模型上。
• agent.name：发出请求的子代理类型。内置 Agent 名称和来自官方市场插件的 Agent 按原样显示。其他用户定义的 Agent 名称会被替换为 "custom"。当请求不是由命名的子代理类型发出时不存在。
• skill.name：请求活跃的 skill，由 Skill 工具或 / 命令设置，或由生成的子代理继承。内置、捆绑、用户定义以及官方市场插件的 skill 名称按原样显示。第三方插件的 skill 名称会被替换为 "third-party"。当没有活跃的 skill 时不存在。
• plugin.name：当活跃的 skill 或子代理由插件提供时，为所属插件。官方市场插件名称按原样显示。第三方插件名称会被替换为 "third-party"。当 skill 和子代理都没有所属插件时不存在。
• marketplace.name：所属插件的安装来源市场。即使设置了 OTEL_LOG_TOOL_DETAILS=1，也仅针对官方市场插件发出。否则不存在。
• mcp_server.name：此请求所使用的工具结果对应的 MCP 服务器。内置、claude.ai 代理以及官方注册表的服务器名称按原样显示。用户配置的服务器名称会被替换为 "custom"。当请求未使用任何 MCP 工具结果时不存在。在 v2.1.222 之前，Claude Code 会在 MCP 工具调用之后的每个请求上设置此属性，而不仅仅是在使用了工具结果的请求上，因此在您升级后，聚合此属性的仪表板会显示数值下降。
• mcp_tool.name：此请求所使用的结果对应的 MCP 工具，其编辑和版本行为与 mcp_server.name 相同。当请求未使用任何 MCP 工具结果时不存在。

​

Token 计数器

• 所有标准属性
• type：（"input"、"output"、"cacheRead"、"cacheCreation"）。"input" 类型不包括从提示词缓存读取或写入提示词缓存的 token，这些 token 计入 "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、插件、Agent 和 MCP 归因。有关定义和编辑行为，请参阅成本计数器。

​

代码编辑工具决策计数器

• 所有标准属性
• 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"。

​

活跃时间计数器

• 所有标准属性
• type："user" 表示键盘交互，"cli" 表示工具执行和 AI 回复

​

事件

​

事件关联属性

• user_prompt、assistant_response 和 api_response_body 上的 message.uuid
• API 事件上的 request_id，在会话记录的 assistant 条目中持久保存为 requestId
• tool_result 和 tool_decision 事件上的 tool_use_id

​

用户提示词事件

• 所有标准属性
• event.name："user_prompt"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• prompt_length：提示词的长度
• prompt：提示词内容。默认已编辑。设置 OTEL_LOG_USER_PROMPTS=1 以包含它
• prompt_text：与 prompt 相同的值，在相同的条件下编辑。将带点的属性名称存储为嵌套对象的后端会将 prompt.id 读取为名为 prompt 的对象中的 id，从而可能丢失提示词字符串。在这种情况下请改为读取 prompt_text。需要 Claude Code v2.1.287 或更高版本
• message.uuid：生成的用户消息的 UUID，与持久保存的会话记录条目相匹配。在命令分派上不存在，因为命令分派可能产生零条或多条消息。需要 Claude Code v2.1.214 或更高版本
• command_name：当提示词调用命令时的命令名称。内置和捆绑的命令名称（例如 compact 或 debug）按原样发出；别名（例如 reset）按输入的形式发出，而不是规范名称。自定义、插件和 MCP 命令名称会折叠为 custom 或 mcp，除非设置了 OTEL_LOG_TOOL_DETAILS=1
• command_source：存在命令时命令的来源：builtin、custom 或 mcp。插件提供的命令报告为 custom

​

助手回复事件

• 所有标准属性
• 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 控制，因此如果要在启用提示词日志记录的同时保持回复被编辑，请设置 OTEL_LOG_ASSISTANT_RESPONSES=0
• model：模型标识符（例如 “claude-sonnet-5”）
• request_id：API 请求 ID，详见事件关联属性
• message.uuid：响应的最后一个会话记录条目的 UUID。API 响应按每个内容块一个会话记录条目进行持久保存；这是最后一个条目，下一轮次的 parentUuid 从它链接。需要 Claude Code v2.1.214 或更高版本
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子代理名称

​

工具结果事件

• 所有标准属性
• 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 工具）
• vcs.ref.head.revision、vcs.ref.head.name、vcs.ref.head.type（当 OTEL_LOG_TOOL_DETAILS=1 时）：由 Bash 或 PowerShell 工具运行的成功 git commit 的提交身份。vcs.ref.head.revision 是提交 SHA，vcs.ref.head.name 是提交所在的分支，vcs.ref.head.type 为 branch。当提交是在分离的 HEAD 上进行时，名称和类型会被省略。需要 Claude Code v2.1.269 或更高版本
• tool_parameters（当 OTEL_LOG_TOOL_DETAILS=1 时）：包含工具特定参数的 JSON 字符串。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，即使标志关闭也会包含 mcp_server_name/mcp_tool_name 对，这与工具决策事件中由主机编写的例外情况相同，需要 Claude Code v2.1.214 或更高版本。参数因工具而异：
  • 对于 Bash 工具：包括 bash_command、full_command、timeout、description 和 dangerouslyDisableSandbox，并在 git commit 命令成功时包括 git_commit_id 和 git_branch。当该提交是会话工作目录的 HEAD 时，git_commit_id 是完整的提交 SHA，否则是 git 的缩写 SHA。git_branch 是提交所在的分支，在分离的 HEAD 上省略
  • 对于桌面应用的工作区 Bash 工具（它也将 tool_name 报告为 Bash）：仅包括 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 个字符的单个值会被截断，完整的 JSON 数据限制在约 4 K 个字符以内。适用于所有工具，包括 MCP 工具。

​

API 请求事件

• 所有标准属性
• event.name："api_request"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• model：使用的模型（例如 “claude-sonnet-5”）
• cost_usd：以美元计的估算成本
• cost_usd_micros：以百万分之一美元计的估算成本，以整数形式发出
• duration_ms：请求持续时间（以毫秒为单位）
• input_tokens：输入 token 数量，不包括从提示词缓存读取或写入提示词缓存的 token
• output_tokens：输出 token 数量
• cache_read_tokens：从缓存读取的 token 数量
• cache_creation_tokens：用于创建缓存的 token 数量
• request_id：API 请求 ID，例如 "req_011..."，详见事件关联属性。
• client_request_id：客户端生成的 UUID，作为 x-client-request-id 请求头发送；有关它何时存在，请参阅事件关联属性表。需要 Claude Code v2.1.214 或更高版本
• speed："fast" 或 "normal"，表示快速模式是否处于活跃状态
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子代理名称
• effort：应用于请求的 effort 级别："low"、"medium"、"high"、"xhigh" 或 "max"。当 Claude Code 未发送 effort 级别时不存在，例如在不支持 effort 的模型上。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的 skill、插件、Agent 和 MCP 归因。有关定义和编辑行为，请参阅成本计数器。

​

API 错误事件

• 所有标准属性
• event.name："api_error"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• model：使用的模型（例如 “claude-sonnet-5”）
• error：错误消息
• status_code：以数字表示的 HTTP 状态码。对于非 HTTP 错误（例如连接失败）不存在。
• duration_ms：请求持续时间（以毫秒为单位）
• attempt：已进行的尝试次数，包括初始请求。检测重试耗尽说明了计数何时重新开始
• request_id：API 请求 ID，例如 "req_011..."，详见事件关联属性。
• client_request_id：客户端生成的 UUID，作为 x-client-request-id 请求头发送。即使超时或连接错误等失败从未产生服务器 request_id，它也可用；有关它何时存在，请参阅事件关联属性表。需要 Claude Code v2.1.214 或更高版本
• speed："fast" 或 "normal"，表示快速模式是否处于活跃状态
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子代理名称
• effort：应用于请求的 effort 级别。当 Claude Code 未发送 effort 级别时不存在，例如在不支持 effort 的模型上。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的 skill、插件、Agent 和 MCP 归因。有关定义和编辑行为，请参阅成本计数器。

​

API 拒绝事件

• 所有标准属性
• event.name："api_refusal"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• model：来自请求的模型标识符
• request_id：API 请求 ID，例如 "req_011..."，详见事件关联属性。
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子代理名称。有关定义，请参阅 api_request。
• speed：当快速模式处于活跃状态时为 "fast"，否则为 "normal"
• attempt：重试尝试次数。第一次尝试为 1。
• effort：应用于请求的 effort 级别。当 Claude Code 未发送 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、插件、Agent 和 MCP 归因。有关定义和编辑行为，请参阅成本计数器。

​

API 请求体事件

• 所有标准属性
• event.name："api_request_body"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• body：JSON 序列化的 Messages API 请求参数，例如系统提示词、消息和工具，在内容限制处截断（默认 60 KB）。之前 assistant 轮次中的扩展思考内容会被编辑。仅在内联模式（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"）
• request_body_id：标识此次尝试请求体的 UUID。成功的那次尝试对应的 api_response_body 事件携带相同的值，因此您可以将响应与产生它的确切请求配对。需要 Claude Code v2.1.274 或更高版本

​

API 响应体事件

• 所有标准属性
• event.name："api_response_body"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• body：JSON 序列化的 Messages API 响应，包括 id、内容块、用量和停止原因，在内容限制处截断（默认 60 KB）。扩展思考内容会被编辑。仅在内联模式（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：API 请求 ID，例如 "req_011..."，详见事件关联属性。
• request_body_id：此响应所对应的 api_request_body 事件的 request_body_id。需要 Claude Code v2.1.274 或更高版本
• message.id：API 为响应分配的消息 ID，即响应体的 id 字段。需要 Claude Code v2.1.274 或更高版本
• message.uuid：响应的最后一个会话记录条目的 UUID。它与 request_body_id 一起，将会话记录消息与其背后的请求体和响应体关联起来。需要 Claude Code v2.1.274 或更高版本

​

工具决策事件

• 所有标准属性
• 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"
• tool_source：始终存在。工具的来源，取值为由 CLI 定义的封闭值集合。需要 Claude Code v2.1.214 或更高版本
  • "builtin"：CLI 自身的工具
  • "mcp"：一般的 MCP 服务器
  • "sdk_host_builtin_mcp"：内置于 Claude Desktop 本身的进程内服务器，位于 Claude Desktop 拥有的会话中。当会话是 Claude Desktop 从其自身的入口点之一（claude-desktop、claude-desktop-3p 或 local-agent）启动的，且不是嵌套子会话时，Claude Desktop 拥有该会话；嵌套会话（包括 Claude Code 自身生成的会话）将这些服务器报告为 "mcp"
• source：决策的来源：
  • "config"：无需询问即自动决定，依据为项目设置、用户个人设置中的允许或拒绝规则、企业托管策略、--allowedTools 或 --disallowedTools 标志、当前的权限模式、同一交互式 CLI 会话中先前提示所授予的会话作用域权限，或者因为该工具本身是安全的。该事件不会指明匹配的是这些来源中的哪一个。当权限提示请求本身失败时，Claude Code 也会报告 "config"，例如当 Agent SDK 的 canUseTool 回调或 --permission-prompt-tool 工具返回无效结果时，或者当请求挂起期间输入流关闭时。在 v2.1.216 之前，Claude Code 将这些失败报告为 "user_reject"。
  • "hook"：由 PreToolUse 或 PermissionRequest hook 返回了决策。
  • "user_permanent"：当用户在权限提示中选择 “Yes, and don’t ask again for …” 时发出，这会将一条允许规则保存到其个人设置中。在交互式 CLI 中，仅针对该选择本身发出；之后匹配已保存规则的调用改为发出 "config"。在 Agent SDK 或非交互式 -p 会话中，初始选择和之后的规则匹配都会发出 "user_permanent"。视为接受。
  • "user_temporary"：当用户在权限提示中选择 “Yes” 进行一次性批准，或在文件编辑或读取提示中选择授予本会话剩余时间访问权限的选项时发出。在交互式 CLI 中，仅针对该选择本身发出；之后由该会话作用域授权允许的调用改为发出 "config"。在 Agent SDK 或非交互式 -p 会话中，该选择和之后的匹配都会发出 "user_temporary"。视为接受。
  • "user_abort"：当用户未作答便关闭权限提示时发出。在 Agent SDK 和非交互式 -p 会话中，这包括在 canUseTool 或 --permission-prompt-tool 权限请求挂起期间中断轮次；在 v2.1.216 之前，Claude Code 将这种中断报告为 "user_reject"。视为拒绝。
  • "user_reject"：当用户在被询问时选择 “No” 时发出。在交互式 CLI 中，仅针对该选择本身发出；匹配用户个人设置中拒绝规则的调用改为发出 "config"。在 Agent SDK 或非交互式 -p 会话中，匹配个人设置中拒绝规则的调用会发出 "user_reject"。视为拒绝。
• tool_parameters（当 OTEL_LOG_TOOL_DETAILS=1 时）：包含工具特定参数的 JSON 字符串。形式与工具结果事件相同，但不含执行后的字段，例如 git_commit_id。如果权限决策通过 updatedInput 重写了工具输入，则对于被接受的调用，其值可能与 tool_result 不同。当 decision 为 "reject" 时，可使用此属性查看被拒绝的是哪个命令。
  • 对于 "sdk_host_builtin_mcp" 工具：即使 OTEL_LOG_TOOL_DETAILS 关闭，也会包含 mcp_server_name 和 mcp_tool_name，因为这些名称由主机应用程序定义；如果没有它们，在默认流中将无法对这些内置服务器的被拒绝调用进行归因。对于用户配置的 MCP 服务器，事件的 tool_name 始终是字面量 "mcp_tool"，并且服务器和工具名称仅在标志开启时出现在 tool_parameters 中；参数内容在任何情况下都需要该标志。需要 Claude Code v2.1.214 或更高版本
  • 对于 Bash 工具：包括 bash_command、full_command、timeout、description、dangerouslyDisableSandbox。桌面应用的工作区 bash 工具也将 tool_name 报告为 Bash，但仅包括 bash_command、full_command 和 timeout
  • 对于 MCP 工具：包括 mcp_server_name、mcp_tool_name
  • 对于 Skill 工具：包括 skill_name
  • 对于 Agent 工具或旧版 Task 工具：包括 subagent_type

​

权限模式变更事件

• 所有标准属性
• 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 时不存在

​

身份验证事件

• 所有标准属性
• 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 服务器连接事件

• 所有标准属性
• 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 时）：插件名称和市场的稳定哈希，用于在不暴露名称的情况下按插件对事件进行分组。Claude Code 按照插件已加载事件中描述的方式计算它
• 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 时）：连接失败时的完整错误消息

​

内部错误事件

• 所有标准属性
• event.name："internal_error"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• error_name：错误类名，例如 "TypeError" 或 "SyntaxError"
• error_code：错误上存在时的 Node.js errno 代码，例如 "ENOENT"

​

插件已安装事件

• 所有标准属性
• 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 时包含

​

插件已加载事件

• 所有标准属性
• 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"、"community"、"org"、"user-local" 或 "default-bundle"
• enabled_via：插件被启用的方式："default-enable"、"org-policy"、"admin-install"、"seed-mount" 或 "user-install"。"admin-install" 值表示该插件在 Organization settings > Plugins & skills 中被设置为您组织的必需或自动安装插件。在 v2.1.246 之前，Claude Code 将这些插件报告为 "user-install" 或 "seed-mount"
• plugin_id_hash：插件名称和市场的确定性哈希，仅发送到您配置的导出器。使您能够在不记录名称的情况下统计整个设备群中加载的不同第三方插件的数量。对于从 claude.ai 同步的插件，Claude Code 会将插件名称与 claude.ai 为该插件报告的市场名称一起进行哈希，否则与 synced 一起进行哈希。在 v2.1.246 之前，Claude Code 在哈希中不使用 claude.ai 报告的市场名称
• has_hooks：插件是否提供 hook
• has_mcp：插件是否提供 MCP 服务器
• host_owned_mcp：当 SDK 主机管理此插件的 MCP 连接且 Claude Code 跳过了读取插件的 MCP 服务器配置时为 true，否则为 false
• skill_path_count：插件声明的 skill 目录数量
• command_path_count：插件声明的命令目录数量
• agent_path_count：插件声明的 Agent 目录数量
• safe_mode：当会话使用 --safe-mode 启动时为 "true"，否则为 "false"。在安全模式下，此事件仅报告已配置的清单；插件的命令、skill、hook 和 MCP 服务器不会加载。需要 Claude Code v2.1.169 或更高版本

​

Skill 已激活事件

• 所有标准属性
• 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 由插件提供时，所属插件的安装来源市场

​

@ 提及事件

• 所有标准属性
• event.name："at_mention"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• mention_type：提及的类型（"file"、"directory"、"agent"、"mcp_resource"、"peer"）。"peer" 值表示您提及了您的另一个 Claude Code 会话。需要 Claude Code v2.1.232 或更高版本
• success：提及是否成功解析（"true" 或 "false"）

​

API 重试耗尽事件

• 所有标准属性
• 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 已注册事件

• 所有标准属性
• 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 配置中的匹配器字符串（如果设置了的话）
• plugin.name（当 hook_source 为 "pluginHook" 时）：提供该 hook 的插件名称。对于官方市场和内置捆绑包之外的插件，除非设置了 OTEL_LOG_TOOL_DETAILS=1，否则值为 "third-party"
• plugin_id_hash（当 hook_source 为 "pluginHook" 时）：插件名称和市场的确定性哈希，仅发送到您配置的导出器。使您能够在不记录名称的情况下统计提供 hook 的不同插件的数量。Claude Code 按照插件已加载事件中描述的方式计算它

​

Hook 执行开始事件

• 所有标准属性
• event.name："hook_execution_start"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• hook_event：hook 事件类型，例如 "PreToolUse" 或 "PostToolUse"
• hook_name：包含匹配器的完整 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 配置。仅当同时启用了详细 beta 追踪和 OTEL_LOG_TOOL_DETAILS=1 时包含

​

Hook 执行完成事件

• 所有标准属性
• event.name："hook_execution_complete"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• hook_event：hook 事件类型
• hook_name：包含匹配器的完整 hook 名称
• num_hooks：匹配的 hook 命令数量
• num_success：成功完成的数量
• num_blocking：返回阻止决策的数量
• num_non_blocking_error：失败但未阻止的数量
• num_cancelled：在完成前被取消的数量
• total_duration_ms：所有匹配 hook 的挂钟持续时间
• stdout_chars：成功执行的匹配 hook 的 stdout 总字符数。需要 Claude Code v2.1.280 或更高版本
• additional_context_chars：匹配 hook 返回的 additionalContext 总字符数。需要 Claude Code v2.1.280 或更高版本
• system_message_chars：匹配 hook 返回的 systemMessage 总字符数。需要 Claude Code v2.1.280 或更高版本
• initial_user_message_chars：匹配 hook 返回的 initialUserMessage 总字符数。需要 Claude Code v2.1.280 或更高版本
• num_outputs_persisted：超过 10,000 字符上限并被 Claude Code 保存到文件中的 hook 输出数量。需要 Claude Code v2.1.280 或更高版本
• managed_only：当仅允许托管策略 hook 时为 "true"
• hook_source："policySettings" 或 "merged"
• safe_mode：当会话使用 --safe-mode 启动时为 "true"，否则为 "false"。需要 Claude Code v2.1.169 或更高版本
• hook_definitions：JSON 序列化的 hook 配置。仅当同时启用了详细 beta 追踪和 OTEL_LOG_TOOL_DETAILS=1 时包含

​

Hook 插件指标事件

• 所有标准属性
• 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}$。值为布尔值或数字。

​

上下文压缩事件

• 所有标准属性
• 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" 时，或针对空闲压缩（其 trigger 报告为 "auto"）时设置。自动压缩可以在上下文窗口填满之前在后台准备摘要，此属性记录压缩是否重用了该预先准备的摘要。"hit" 表示已重用；"miss_custom_instructions"、"miss_hook" 和 "miss_not_ready" 给出改为重新计算摘要的原因

​

子代理完成事件

• 所有标准属性
• event.name："subagent_completed"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• agent_type：子代理类型。内置 Agent 名称以及来自官方市场插件的 Agent 会原样显示；除非设置了 OTEL_LOG_TOOL_DETAILS=1，否则其他 Agent 名称会被替换为 "custom"
• agent.source：Agent 定义的来源：built-in、plugin，或定义自定义 Agent 的设置来源，例如 userSettings 或 projectSettings
• is_built_in：该子代理是否为内置 Agent 类型
• is_async：该子代理是否在后台运行
• total_tokens：子代理最后一个 API 请求的 token 占用量：即该单个请求的输入、缓存创建、缓存读取和输出 token，大致相当于子代理完成时的上下文大小。并非整个运行过程的总和
• total_tool_uses：子代理在整个运行过程中进行的工具调用次数
• duration_ms：运行时间（毫秒）
• model：子代理被解析为运行的模型
• final_model：生成子代理最终回复的模型；在运行中途发生切换（例如回退）后，该值与 model 不同。需要 Claude Code v2.1.212 或更高版本
• model_swapped：是否有多个模型处理了该子代理的请求。需要 Claude Code v2.1.212 或更高版本
• plugin_id_hash、plugin.name：对于由插件提供的 Agent 存在。官方市场插件名称会原样显示；除非设置了 OTEL_LOG_TOOL_DETAILS=1，否则其他插件名称会被替换为 "third-party"

​

反馈调查事件

• 所有标准属性
• 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?” 评分提示
• response：用户在 responded 事件中的选择
• enabled_via_override：设置了 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL 时为 true。以布尔值而非字符串形式发出。存在于 session 调查事件中。可按此属性筛选，以确认该覆盖已在整个设备群中生效

​

保留清理事件

• 所有标准属性
• event.name："retention_sweep"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• result：清理已运行时为 "complete"，Claude Code 暂停清理时为 "skipped"
• period_days：合并后设置中的 cleanupPeriodDays 值（以天为单位），如果没有任何来源设置该值，则为 30。在 skipped 事件中，为清理本应使用的值，根据 Claude Code 能够读取的设置来源计算得出
• used_default：没有可读取的设置来源设置 cleanupPeriodDays 时为 "true"，否则为 "false"。在 complete 事件中，"true" 表示应用了 30 天的默认值
• skip_reason：Claude Code 暂停清理的原因。仅在 result 为 "skipped" 时存在：
  • "user_source_disabled"：用户设置被排除（例如通过 --setting-sources 标志或 SDK 的 settingSources 选项），且没有已启用的来源提供 cleanupPeriodDays
  • "settings_unknowable"：某个设置文件无法读取或解析，因此 cleanupPeriodDays 或 desktopSessionCleanupPeriodDays 可能被设置为 Claude Code 无法看到的值
  • "settings_invalid_key_set"：设置存在验证错误，且显式设置了 cleanupPeriodDays 或 desktopSessionCleanupPeriodDays，因此回退到默认值可能会违背该设置删除或保留文件
• transcripts_deleted：清理删除的会话记录数量，即顶层的 ~/.claude/projects/*/*.jsonl 文件
• transcripts_exempted_desktop：已超过保留期限、但清理根据 Claude Desktop 和 Cowork 规则予以保留的会话记录数量。这些不计入 files_past_cutoff。需要 Claude Code v2.1.248 或更高版本
• session_files_deleted：会话文件清理删除的文件数量：会话记录加上每个会话的配套文件，例如附属文件、录制文件和工具结果
• artifacts_deleted：清理在其覆盖的数据目录中删除的项目总数，包括会话文件。某些清理会将整个被删除的目录树计为一项，少数清理过程不会计入该计数器，因此应将该值视为下限，而非精确的文件数量
• files_retained_fresh：已检查并因仍在保留期限内而保留的文件。只有逐文件清理会统计这些文件，因此该值为下限；非零值是正常的稳定状态
• files_past_cutoff：早于保留期限、但清理未能删除的文件，例如由于权限错误或文件被占用。该计数还包括清理在 skills/synced/ 或 plugins/synced/ 下发现的每个过期文件夹，无论是否将该文件夹移至回收站。除这些文件夹外，大于零的值表示有文件超出了配置的保留期限仍然存在；零并不能证明没有此类文件，因为删除整个目录失败时会计入 error_count
• error_count：清理在列出或删除文件时遇到的错误数量

​

托管设置解析事件

• 在托管设置、用户设置或 --settings 的 env 块中设置，或在启动 Claude Code 的环境中设置。项目设置或本地设置中的值不会启用它，因为克隆的仓库可以写入这些设置。
• 服务器托管设置可以设置它，而无需显示安全批准对话框，因为该变量只是将您组织自己的脱敏策略添加到您组织已在接收的事件中。

• 所有标准属性
• event.name："managed_settings_resolved"
• event.timestamp：ISO 8601 时间戳
• event.sequence：用于对事件排序的按进程计数器，详见事件关联属性
• managed_settings.trigger：会话开始事件为 "startup"；托管设置或策略辅助程序的状态在会话后期发生变化时为 "change"；托管设置策略阻止会话时为 "refused"。仅当某个属性与上次发送的事件不同时，Claude Code 才会发送 change 事件；即使 OTEL_LOG_MANAGED_SETTINGS 处于关闭状态，设置值的变化也会计入
• error.type：Claude Code 停止会话的原因。仅存在于 refused 事件中：
  • "helper_failed"：策略辅助程序运行失败
  • "policy_invalid"：托管设置包含阻止 Claude Code 启动的错误，或某个管理员来源因读取被拒绝以外的原因加载失败，导致 Claude Code 无法检查组织登录或提供商强制要求
  • "provider_not_allowed"：会话将使用托管 allowedProviders 列表不允许的 API 提供商，或将某个提供商的流量发送到该列表不允许的主机。需要 Claude Code v2.1.285 或更高版本
  • "consent_rejected"：用户拒绝了服务器托管设置的安全批准对话框
  • "force_refresh_failed"：forceRemoteSettingsRefresh 所要求的设置获取失败
  • "gateway_rejected"：Claude apps gateway 对托管设置加载返回了 HTTP 403
  • "version_below_minimum"：此版本的 Claude Code 低于 requiredMinimumVersion 或高于 requiredMaximumVersion
  • "_OTHER"：Claude apps gateway 托管设置加载因其他原因失败
• managed_settings.sources：提供至少一个策略键的每个托管来源，按优先级从高到低排列，包括在 first-wins 下其键不生效的来源。取值为："remote"；"plist" 或 "hklm" 表示 MDM 或操作系统级策略；"file" 表示托管设置文件和附加文件；"parent" 表示由嵌入宿主提供设置；"hkcu" 表示 Claude Code 读取的 Windows HKCU 注册表值。仅包含控制键的来源或 Claude Code 无法读取的来源不会列出。以字符串数组形式发出，没有托管来源提供策略键时为空
• managed_settings.source_behavior：Claude Code 读取到的 managedSourcesBehavior 值，为 "first-wins" 或 "merge"。没有来源设置该键时为 "first-wins"
• managed_settings.helper.state：所选 MDM 或文件来源所配置的策略辅助程序的状态：
  • "ok"：辅助程序的输出用作托管设置
  • "bad_path"、"not_a_file"、"exit_nonzero"、"timed_out"、"oversize"、"parse_failed"、"envelope_invalid" 或 "schema_rejected"：辅助程序上次运行失败。辅助程序故障介绍了这些情况
  • "none"：未配置辅助程序，或配置辅助程序的来源不是 MDM 策略或托管设置文件
• managed_settings.helper.applied：辅助程序自身的输出用作托管设置时为 "output"，否则为 "none"
• managed_settings.helper.entry：Claude Code 选择了 policyHelper 时为 "policyHelper"。未选择辅助程序时不存在
• managed_settings.helper.path：辅助程序配置的 path。只要 Claude Code 选择了辅助程序即存在，无论是否设置了 OTEL_LOG_MANAGED_SETTINGS
• managed_settings.resolved_sha256（当 OTEL_LOG_MANAGED_SETTINGS=1 时）：脱敏前已解析托管设置的 SHA-256，序列化为键按递归排序且不含空白的 JSON。摘要相同的机器运行相同的策略。Claude Code 仅在选择启用时发送摘要，因为较短的策略可以通过对猜测值进行哈希来还原。没有解析出托管设置时不存在，在 refused 事件中也不存在
• managed_settings.settings（当 OTEL_LOG_MANAGED_SETTINGS=1 时）：以 JSON 字符串形式表示的已解析托管设置的名称和结构，其中的值已脱敏。在 refused 事件中不存在。Claude Code 根据其设置 schema 构建该值：
  • schema 声明的设置名称会被导出，schema 未声明的键会被省略
  • 布尔值、数字以及 schema 限定为固定选项集的字符串值（例如 permissions.defaultMode）按原样导出。sandbox.network.httpProxyPort 和 sandbox.network.socksProxyPort 导出为 "[REDACTED]"
  • 其他所有字符串，例如 model、apiKeyHelper、每个 env 值、每个 URL 以及每个命令，均导出为 "[REDACTED]"
  • 映射的条目名称（例如 env 变量名和插件 ID）按原样导出。schema 未对其条目定义类型的设置（例如 vimInsertModeRemaps）导出为单个 "[REDACTED]"，sandbox.ignoreViolations 导出为其路径列表的列表，不含命令模式
  • 列表保留其长度，每个条目按相同规则脱敏
  • 当工具内置于此版本的 Claude Code 中，或是 mcp__ 引用（例如 mcp__jira__create_issue）时，permissions.allow、permissions.deny 或 permissions.ask 规则导出为其工具名称，内容脱敏，例如 Read([REDACTED])。其他任何规则导出为 "[REDACTED]"
  • hook 遵循相同的规则，因此固定选项字段和数值字段（例如 type 和 timeout）会显示，而每个命令、URL、matcher 和 if 条件均导出为 "[REDACTED]"
  例如，包含 apiKeyHelper、两个 env 变量和一条拒绝规则的托管设置导出为 {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}。 Claude Code 会在 UTF-8 编码 8 KB 处截断该值，截断后的值不是有效的 JSON
• managed_settings.settings_truncated（当存在 managed_settings.settings 时）：Claude Code 在 8 KB 处截断了 managed_settings.settings 时为 true，否则为 false。以布尔值而非字符串形式发出

​

解释指标和事件数据

​

使用情况监控

​

成本监控

• 跟踪团队或个人的使用趋势
• 识别高使用会话以进行优化
• 通过 skill.name、plugin.name 和 agent.name 属性将支出归属于特定技能、插件或子代理类型

​

警报和分段

• 成本激增
• 异常的令牌消耗
• 来自特定用户的高会话量

​

检测重试耗尽

​

事件分析

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

​

将输入 token 映射到 OpenTelemetry GenAI 语义约定

• claude_code.llm_request span 和 api_request 事件上的 input_tokens
• claude_code.token.usage 指标的 "input" 类型

• 从 span 或事件：将 input_tokens、cache_read_tokens 和 cache_creation_tokens 相加
• 从 claude_code.token.usage 指标：将其 "input"、"cacheRead" 和 "cacheCreation" 类型相加

• cache_read_tokens 映射到 gen_ai.usage.cache_read.input_tokens
• cache_creation_tokens 映射到 gen_ai.usage.cache_write.input_tokens。旧版本的约定将缓存写入属性命名为 gen_ai.usage.cache_creation.input_tokens，因此请使用您的后端所期望的名称。

​

审计安全事件

​

将属性操作归属于用户

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

​

审计 MCP 活动

• tool_result：保留 mcp_server_scope 和一个对用户配置的服务器编辑为字面值 "mcp_tool" 的 tool_name，省略参数内容。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，它还保留 tool_parameters 内的 mcp_server_name/mcp_tool_name 对，与 tool_decision 相同的主机编写异常，需要 Claude Code v2.1.214 或更高版本
• tool_decision：保留 tool_source 和一个对用户配置的服务器编辑为字面值 "mcp_tool" 的 tool_name，省略参数内容。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，它还保留 tool_parameters 内的 mcp_server_name/mcp_tool_name 对；tool_source 和名称对都需要 Claude Code v2.1.214 或更高版本
• mcp_server_connection：省略 server_name 和错误消息，但保留 is_plugin、plugin_id_hash 和 plugin.name，非 Anthropic 插件名称被编辑为字面值 "third-party"，因此插件提供的服务器在没有详细日志的情况下仍然可以区分

​

将安全问题映射到事件

​

将出站路径映射到托管控制项和事件

• allowedHttpHookUrls：条目会在各设置文件之间合并，因此开发人员可以向空的托管列表中添加条目。由 allowManagedHooksOnly 决定哪些 hook 运行
• managed-mcp.json：要关闭 MCP，请参阅 完全禁用 MCP。要确认 Claude Code 读取了该文件，请参阅 验证配置
• Hook 事件：Claude Code 对每个 hook 事件记录一次 hook_execution_start 和 hook_execution_complete，涵盖所有匹配的 hook。仅靠 OTEL_LOG_TOOL_DETAILS=1 不会记录 HTTP hook 的 URL。hook 配置只出现在 hook_definitions 中，而这还需要启用详细的 beta 追踪

​

检查保留清理

• 没有人启动 Claude Code：不会运行清理，机器会保留其数据直到下次启动
• 会话保持打开：Claude Code 每个会话最多运行一次清理
• 会话提前结束：会话退出时尚未完成的清理不会发出任何事件，因意外错误而停止的清理也不会

​

将事件发送到 SIEM

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

​

后端考虑事项

​

用于指标的后端

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

​

用于事件和日志的后端

• 日志聚合系统：全文搜索、日志分析
• 列式存储：结构化事件分析
• 全功能可观测性平台：指标和事件之间的关联

​

用于跟踪的后端

• 分布式跟踪系统：Span 可视化、请求瀑布、延迟分析
• 全功能可观测性平台：跟踪搜索和与指标和日志的关联

​

服务信息

• service.name：终端会话为 claude-code，从 Claude Desktop 应用中的代码选项卡启动的本地会话为 claude-code-desktop
• service.version：当前 Claude Code 版本，或本地代码选项卡会话的 Desktop 应用版本
• os.type：操作系统类型（例如，linux、darwin、windows）
• os.version：操作系统版本字符串
• host.arch：主机架构（例如，amd64、arm64）
• wsl.version：WSL 版本号（仅在 Windows Subsystem for Linux 上运行时出现）
• 仪表名称：com.anthropic.claude_code

​

ROI 测量资源

​

安全和隐私

• OpenTelemetry 导出到您的后端是可选的，需要显式配置。有关 Anthropic 的单独操作遥测以及如何禁用它，请参阅 数据使用
• 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 OTEL_LOG_TOOL_CONTENT 项目符号
• 通过 OAuth 认证时，user.email 包含在遥测属性中，仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段
• 默认情况下不收集用户提示词内容。仅记录提示词长度。要包含提示词内容，请设置 OTEL_LOG_USER_PROMPTS=1。启用后：
  • user_prompt 事件在两个属性中携带提示词文本：prompt 和 prompt_text。如果您在收集器中按属性名称删除或屏蔽该事件的提示词文本，请在规则中同时指定这两个属性 此 OpenTelemetry Collector attributes 处理器会在列出它的管道中删除这两个属性：
    processors:
      attributes/drop-prompt-text:
        actions:
          - key: prompt
            action: delete
          - key: prompt_text
            action: delete
    
  • 启用追踪后，claude_code.interaction span 在其 user_prompt 属性中携带提示词文本
  • 在详细的 beta 追踪下，spans 还会携带每个请求发送的新用户消息、工具结果和系统提醒、系统提示词文本以及模型输出。详细 beta 追踪下的内容属性列出了每个属性。claude_code.system_prompt 事件携带完整的系统提示词
• 默认情况下不收集助手响应文本。仅记录响应长度。要包含响应文本，请设置 OTEL_LOG_ASSISTANT_RESPONSES=1。与来自 Claude Code 的所有 OpenTelemetry 数据一样，响应文本仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。当此变量未设置时，会回退到 OTEL_LOG_USER_PROMPTS，因此如果您希望事件中包含提示词内容而不包含响应内容，请设置 OTEL_LOG_ASSISTANT_RESPONSES=0。在详细的 beta 追踪下，claude_code.llm_request span 仍会在 response.model_output 中携带模型输出，该属性遵循 OTEL_LOG_USER_PROMPTS 而非此变量
• 默认情况下不记录工具输入参数和参数。要包含它们，请设置 OTEL_LOG_TOOL_DETAILS=1。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，tool_decision 和 tool_result 携带 mcp_server_name/mcp_tool_name 对，即主机编写的名称而非参数内容，即使关闭该标志也是如此。此异常需要 Claude Code v2.1.214 或更高版本。此数据仅发送到您配置的 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
  • 成本和 token 计数器以及 api_request、api_error 和 api_refusal 事件在其归属属性中携带真实的 Agent、skill、插件和 MCP 服务器以及工具名称
  • claude_code.tool span 携带输入派生属性（如 file_path）。在详细的 beta 追踪下，它还携带 tool_input 属性
• 默认情况下，trace spans 中不记录工具内容。要包含它，请设置 OTEL_LOG_TOOL_CONTENT=1。claude_code.tool span 随后携带一个 tool.output span 事件，其中包含原始文件内容、Bash 命令输出以及 MCP 工具、WebFetch 和 WebSearch 返回的内容，在内容限制处截断（默认为 60 KB）每个属性。来自 MCP 工具、WebFetch 和 WebSearch 的结果需要 Claude Code v2.1.283 或更高版本。工具内容也通过 new_context 到达 spans，其门控因 span 而异。根据需要配置您的遥测后端以过滤或编辑这些属性
• 默认情况下不记录原始 Anthropic Messages API 请求和响应主体。要包含它们，请在您的 shell、用户设置或托管设置中设置 OTEL_LOG_RAW_API_BODIES。在 项目和本地设置 中被忽略。主体包含完整的对话历史，包括系统提示、每个先前的用户和助手轮次以及工具结果，因此启用此选项意味着同意其他 OTEL_LOG_* 内容标志会揭示的所有内容。Claude Code 始终从这些主体中编辑 Claude 的扩展思考内容，无论其他设置如何。您设置的值决定了 Claude Code 如何传递主体：
  • 使用 =1 时，Claude Code 为每个 API 调用发出 api_request_body 和 api_response_body 日志事件。事件的 body 属性携带 JSON 序列化的有效负载，在内容限制处截断（默认为 60 KB）
  • 使用 =file:<dir> 时，Claude Code 将未截断的主体写入该目录下的 .request.json 和 .response.json 文件，事件携带 body_ref 路径而不是内联主体。使用日志收集器或 sidecar 传输目录，而不是通过遥测流 对于每个成功的响应，Claude Code 还会在该目录中的 index.jsonl 中追加一行，将响应文件链接到生成它的请求文件以及它成为的记录消息。每行不包含任何消息内容，API 响应主体事件部分列出了其字段。索引文件需要 Claude Code v2.1.274 或更高版本

​

在 Amazon Bedrock 上监控 Claude Code