监控

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

通过 OpenTelemetry (OTel) 导出遥测数据，跨组织跟踪 Claude Code 使用情况、成本和工具活动。Claude Code 通过标准指标协议导出指标作为时间序列数据，通过日志/事件协议导出事件，以及可选地通过 traces 协议 导出分布式跟踪。配置您的指标、日志和跟踪后端以满足您的监控要求。

快速开始

使用环境变量配置 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 工具、hooks、MCP 服务器和语言服务器。通过 Bash 工具运行的已进行 OpenTelemetry 检测的应用程序不会继承 Claude Code 的导出器端点或标头，因此如果该应用程序需要导出自己的遥测，请直接在命令中设置这些变量。

配置详情

常见配置变量

mTLS 身份验证

您为 OTLP 导出器配置客户端证书的方式取决于用于该信号的 OTLP 协议，通过 OTEL_EXPORTER_OTLP_PROTOCOL 或每个信号的覆盖设置。相同的配置适用于指标、日志和跟踪。

对于 grpc，OpenTelemetry SDK 直接读取标准 OTLP 变量，因此设置每个信号指标变量的现有配置继续工作。

指标基数控制

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

这些变量有助于控制指标的基数，这会影响指标后端中的存储要求和查询性能。较低的基数通常意味着更好的性能和更低的存储成本，但分析的数据粒度较低。

Traces（测试版）

分布式跟踪导出 span，将每个用户提示链接到它触发的 API 请求和工具执行，因此您可以在跟踪后端中将完整请求视为单个 trace。

跟踪默认关闭。要启用它，请同时设置 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1，然后设置 OTEL_TRACES_EXPORTER 以选择 span 的发送位置。Traces 重用 常见 OTLP 配置 用于端点、协议、标头和 mTLS。

Spans 默认编辑用户提示文本、工具输入详情和工具内容。设置 OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1 和 OTEL_LOG_TOOL_CONTENT=1 以包含它们。

当跟踪处于活动状态时，Bash 和 PowerShell 子进程会自动继承包含活动工具执行 span 的 W3C trace 上下文的 TRACEPARENT 环境变量。这让任何读取 TRACEPARENT 的子进程可以在同一 trace 下将其自己的 span 作为父级，通过 Claude 运行的脚本和命令启用端到端分布式跟踪。

当跟踪处于活动状态时，如果 Claude Code 直接连接到 Anthropic API，每个模型请求都会携带一个 W3C traceparent 标头，设置为 claude_code.llm_request span 的上下文，API 的 traceresponse 标头被记录为 span 链接。这些一起通过任何兼容的中介将 Claude Code 的客户端 span 连接到服务器端跟踪。标头不会发送给第三方提供商。

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

在 Agent SDK 和使用 -p 启动的非交互式会话中，Claude Code 还在启动每个交互 span 时从其自己的环境中读取 TRACEPARENT 和 TRACESTATE。这让嵌入过程可以将其活动的 W3C trace 上下文传递到子进程中，以便 Claude Code 的 span 显示为调用者分布式跟踪的子级。交互式会话忽略入站 TRACEPARENT 以避免意外继承来自 CI 或容器环境的环境值。

Span 层次结构

每个用户提示启动一个 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                    (需要详细的测试版跟踪)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent 工具) 子代理 claude_code.llm_request / claude_code.tool span

在 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 时不会发出。

动态标头

对于需要动态身份验证的企业环境，您可以配置脚本来动态生成标头。动态标头仅适用于 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 会在以下位置报告错误：

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

刷新行为

标头助手脚本在启动时运行，之后定期运行以支持令牌刷新。默认情况下，脚本每 29 分钟运行一次。使用 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 环境变量自定义间隔。

多团队组织支持

具有多个团队或部门的组织可以使用 OTEL_RESOURCE_ATTRIBUTES 环境变量添加自定义属性以区分不同的组：

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

这些自定义属性将包含在所有指标和事件中，允许您：

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

Claude Code 将这些值作为属性附加到每个指标数据点和事件记录上，除了在 OTLP 资源块中发送它们。因为大多数指标后端将数据点属性公开为可查询的标签，您可以直接按自定义键对指标进行分组和过滤。自定义键永远不会覆盖 标准属性，例如 user.id 或 session.id：当键冲突时，Claude Code 保留内置值。

每个自定义键都成为每个指标系列上的标签，因此高基数值会增加指标后端中的存储成本。要仅在资源块中发送自定义属性并从数据点标签中省略它们，请设置 OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false。请参阅 指标基数控制。

示例配置

在运行 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 apps gateway 时，CLI 会使用来自网关会话的已认证身份标记导出：user.id 是 IdP 主体而不是匿名安装标识符，user.email 是已登录的电子邮件，user.groups 作为逗号分隔的字符串携带 IdP 组成员身份。每个导出还携带 identity.source: gateway-oidc。网关身份最后应用，因此通过 OTEL_RESOURCE_ATTRIBUTES 设置的 user.* 和 identity.* 键在网关会话上被忽略。

事件另外包含以下属性。这些永远不会附加到指标，因为它们会导致无限基数：

• prompt.id：UUID 将用户提示与所有后续事件关联到下一个提示。请参阅 事件关联属性。
• workspace.host_paths：在桌面应用中选择的主机工作区目录，作为字符串数组

指标

Claude Code 导出以下指标：

指标详情

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

会话计数器

在每个会话开始时递增。

属性：

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

代码行计数器

当添加或删除代码时递增。

属性：

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

拉取请求计数器

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

属性：

• 所有 标准属性

提交计数器

通过 Claude Code 创建 git 提交时递增。

属性：

• 所有 标准属性

成本计数器

在每个 API 请求后递增。

属性：

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

令牌计数器

在每个 API 请求后递增。

属性：

• 所有 标准属性
• type：（"input"、"output"、"cacheRead"、"cacheCreation"）
• model：模型标识符（例如，"claude-sonnet-5"）
• query_source：发出请求的子系统的类别。"main"、"subagent" 或 "auxiliary" 之一
• speed：当请求使用快速模式时为 "fast"。否则不存在
• effort：应用于请求的 努力级别。有关详情，请参阅 成本计数器。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的技能、插件、代理和 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" 用于键盘交互，"cli" 用于工具执行和 AI 响应

事件

Claude Code 通过 OpenTelemetry 日志/事件导出以下事件（当配置了 OTEL_LOGS_EXPORTER 时）：

事件关联属性

当用户提交提示时，Claude Code 可能会进行多个 API 调用并运行多个工具。prompt.id 属性让您将所有这些事件与触发它们的单个提示联系起来。

要跟踪由单个提示触发的所有活动，请按特定 prompt.id 值过滤您的事件。这会返回 user_prompt 事件、任何 api_request 事件以及处理该提示时发生的任何 tool_result 事件。

用户提示事件

当用户提交提示时记录。

事件名称：claude_code.user_prompt

属性：

• 所有 标准属性
• event.name："user_prompt"
• event.timestamp：ISO 8601 时间戳
• event.sequence：单调递增的计数器，用于在会话内排序事件
• prompt_length：提示的长度
• prompt：提示内容。默认为已编辑。设置 OTEL_LOG_USER_PROMPTS=1 以包含它
• command_name：当提示调用命令时的命令名称。内置和捆绑的命令名称（例如 compact 或 debug）按原样发出；别名（例如 reset）按输入方式发出而不是规范名称。自定义、插件和 MCP 命令名称折叠为 custom 或 mcp，除非设置了 OTEL_LOG_TOOL_DETAILS=1
• command_source：命令存在时的来源：builtin、custom 或 mcp。插件提供的命令报告为 custom

助手响应事件

在每个返回来自模型的文本内容的 API 请求后记录。仅包含响应的文本块；思考块和工具使用块被排除。{/* min-version: 2.1.193 */}需要 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 控制它，因此设置 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：此工具调用的唯一标识符。与传递给 hooks 的 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 命令成功时的提交 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：输入令牌数
• output_tokens：输出令牌数
• cache_read_tokens：从缓存读取的令牌数
• cache_creation_tokens：用于缓存创建的令牌数
• request_id：来自响应的 request-id 标头的 Anthropic API 请求 ID，例如 "req_011..."。仅当 API 返回时存在。
• speed："fast" 或 "normal"，指示是否启用了快速模式
• query_source：发出请求的子系统，例如 "repl_main_thread"、"compact" 或子代理名称
• effort：应用于请求的 努力级别："low"、"medium"、"high"、"xhigh" 或 "max"。当模型不支持努力时不存在。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的技能、插件、代理和 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：应用于请求的 努力级别。当模型不支持努力时不存在。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：请求的技能、插件、代理和 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：应用于请求的 努力级别。当模型不支持努力时不存在。
• server_fallback_hop：当 API 的服务器端模型回退已在不同模型上重试此拒绝时为 true，因此用户没有看到此特定拒绝。当请求以拒绝结束时为 false。单个轮次可以发出 true hop 事件和稍后的 false 最终事件，当回退模型也拒绝时。
• has_category：当 API 响应携带 stop_details.category 为 "cyber"、"bio"、"frontier_llm" 或 "reasoning_extraction" 时为 true。当响应没有类别或值在该集合之外时为 false。当 server_fallback_hop 为 true 时不存在，因为 hop 块不携带 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：请求的技能、插件、代理和 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 请求参数（系统提示、消息、工具等），在 60 KB 处截断。先前助手轮次中的扩展思考内容被编辑。仅在内联模式下发出（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、内容块、使用情况、停止原因），在 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：来自响应的 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：此工具调用的唯一标识符。与传递给 hooks 的 tool_use_id 匹配，允许在 OTel 事件和 hook 捕获的数据之间进行关联。
• decision："accept" 或 "reject"
• source：决策来源：
  • "config"：基于项目设置、用户个人设置中的允许规则、企业托管策略、--allowedTools 或 --disallowedTools 标志、活跃权限模式、来自同一交互式 CLI 会话中较早提示的会话范围授予或因为工具本身是安全的，自动决策而不提示。事件不指示这些来源中的哪一个匹配。
  • "hook"：PreToolUse 或 PermissionRequest hook 返回了决策。
  • "user_permanent"：当用户在权限提示时选择"是，并且不要再问..."时发出，将允许规则保存到其个人设置。在交互式 CLI 中，仅为该选择本身发出；与保存规则匹配的后续调用发出 "config"。在 Agent SDK 或非交互式 -p 会话中，初始选择和后续规则匹配都发出 "user_permanent"。视为接受。
  • "user_temporary"：当用户在权限提示时选择"是"，或在文件编辑或读取提示上选择"...仅在此会话期间"选项时发出。在交互式 CLI 中，仅为该选择本身发出；与该会话范围允许匹配的后续调用发出 "config"。在 Agent SDK 或非交互式 -p 会话中，选择和后续匹配都发出 "user_temporary"。视为接受。
  • "user_abort"：当用户关闭权限提示而不回答时发出。视为拒绝。
  • "user_reject"：当用户选择"否"时发出。在交互式 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 循环、退出 Plan Mode 或自动模式门控检查。

事件名称：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 或桥接时不存在

身份验证事件

当 /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 风格的代码。永远不包括错误消息和堆栈跟踪。在针对 Bedrock、Vertex 或 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：插件是否贡献 hooks
• has_mcp：插件是否贡献 MCP 服务器
• host_owned_mcp：当 SDK 主机管理此插件的 MCP 连接且 Claude Code 跳过读取插件的 MCP 服务器配置时为 true，否则为 false。{/* min-version: 2.1.172 */}需要 Claude Code v2.1.172 或更高版本
• skill_path_count：插件声明的技能目录数
• command_path_count：插件声明的命令目录数
• agent_path_count：插件声明的代理目录数
• safe_mode：当会话使用 --safe-mode 启动时为 "true"，否则为 "false"。在安全模式下，此事件仅报告配置的清单；插件的命令、技能、hooks 和 MCP 服务器不加载。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更高版本

技能激活事件

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

事件名称：claude_code.skill_activated

属性：

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

@提及事件

当 Claude Code 在提示中解析 @-提及时记录。并非每个提及都会发出事件：早期退出路径（例如权限拒绝、超大文件、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 记录一次。使用此事件来清点您的整个队伍中哪些 hooks 处于活跃状态，作为每次执行 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"。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更高版本
• hook_matcher（当 OTEL_LOG_TOOL_DETAILS=1 时）：hook 配置中的匹配器字符串（设置时）
• plugin.name（当 hook_source 是 "pluginHook" 时）：贡献插件的名称。对于官方市场外和内置捆绑的插件，除非 OTEL_LOG_TOOL_DETAILS=1，否则值为 "third-party"
• plugin_id_hash（当 hook_source 是 "pluginHook" 时）：插件名称和市场的确定性哈希，仅发送到您配置的导出器。让您计算不同的贡献插件数而无需记录其名称

Hook 执行开始事件

当一个或多个 hooks 开始为 hook 事件执行时记录。

事件名称：claude_code.hook_execution_start

属性：

• 所有 标准属性
• 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：当仅允许托管策略 hooks 时为 "true"
• hook_source："policySettings" 或 "merged"
• safe_mode：当会话使用 --safe-mode 启动时为 "true"，否则为 "false"。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更高版本
• hook_definitions：JSON 序列化的 hook 配置。仅当启用了详细的测试版跟踪和 OTEL_LOG_TOOL_DETAILS=1 时才包含

Hook 执行完成事件

当 hook 事件的所有 hooks 完成时记录。

事件名称：claude_code.hook_execution_complete

属性：

• 所有 标准属性
• 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：所有匹配 hooks 的实际时钟持续时间
• managed_only：当仅允许托管策略 hooks 时为 "true"
• hook_source："policySettings" 或 "merged"
• safe_mode：当会话使用 --safe-mode 启动时为 "true"，否则为 "false"。{/* min-version: 2.1.169 */}需要 Claude Code v2.1.169 或更高版本
• hook_definitions：JSON 序列化的 hook 配置。仅当启用了详细的测试版跟踪和 OTEL_LOG_TOOL_DETAILS=1 时才包含

Hook 插件指标事件

当官方市场插件 hook 发出每次调用指标时记录。仅从官方 Anthropic 市场安装的插件可以发出这些。第三方市场插件和用户配置的 hooks 不会发出到此事件。使用此事件从您自己的可观测性堆栈监控插件行为，例如查找率、成本和持续时间。

事件名称：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：压缩前的近似令牌计数
• post_tokens：压缩后的近似令牌计数
• error：压缩失败时的错误消息
• precompute_reuse：仅当 trigger 为 "manual" 时设置。自动压缩可以在上下文窗口填满之前在后台准备摘要，此属性记录 /compact 是否重用了该准备的摘要。"hit" 表示它被重用；"miss_custom_instructions"、"miss_hook" 和 "miss_not_ready" 给出了计算新摘要的原因。{/* min-version: 2.1.153 */}需要 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" 是"Claude 做得怎么样？"评分提示
• response：用户在 responded 事件上的选择
• enabled_via_override：当设置了 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL 时为 true。作为布尔值而不是字符串发出。在 session 调查事件上存在。过滤此属性以确认覆盖在整个队伍中应用

解释指标和事件数据

导出的指标和事件支持一系列分析：

使用情况监控

成本监控

claude_code.cost.usage 指标有助于：

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

警报和分段

要考虑的常见警报：

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

所有指标都可以按标准属性进行分段。model 属性在 claude_code.token.usage、claude_code.cost.usage 上可用，以及从 v2.1.172 开始，claude_code.lines_of_code.count 上也可用。代码行数或提交的按模型分解只能通过在 session.id 上与令牌或成本指标进行联接来近似，因为一个会话可以跨越多个模型。筛选令牌或成本端的行，使 query_source 为 "main"，以便辅助和子代理请求不会将会话的提交归属于未进行这些提交的模型。

检测重试耗尽

Claude Code 在内部重试失败的 API 请求，仅在放弃后才发出单个 claude_code.api_error 事件，因此事件本身是该请求的终端信号。中间重试尝试不会作为单独的事件记录。

事件上的 attempt 属性记录进行的总尝试次数。CLAUDE_CODE_MAX_RETRIES 默认为 10，上限为 15。当请求在瞬时错误上耗尽所有重试时，attempt 等于该有效限制加一：默认为 11，永远不超过 16。较低的值表示不可重试的错误，例如 400 响应。

要区分从一个恢复的会话与停滞的会话，按 session.id 分组事件，并检查错误后是否存在更晚的 api_request 事件。

事件分析

事件数据提供了对 Claude Code 交互的详细见解：

工具使用模式：分析工具结果事件以识别：

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

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

审计安全事件

OpenTelemetry 事件是 Claude Code 活动的审计数据源。每个事件都携带身份属性，将工具调用、MCP 活动和权限决策与触发它们的用户联系起来。OTLP 日志导出器可以将这些事件传递到任何具有 OTLP 接收器的安全信息和事件管理 (SIEM) 平台，或转发到您的 SIEM 的 OpenTelemetry Collector。

将属性操作归属于用户

每个事件上的 标准属性 包括已认证用户的身份：user.email、user.account_uuid、user.account_id 和 organization.id（使用 Claude 账户登录时），加上 user.id 和每会话的 session.id。user.id 是安装范围的标识符，除了在 Claude apps gateway 会话上，其中它是来自网关颁发的令牌的 IdP 主体。

MCP 工具调用、Bash 命令和文件编辑因此归属于启动会话的开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户，或开发人员在 Claude apps gateway 会话上的 IdP 身份。

当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Bedrock、Vertex AI 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 user.id 和 session.id。在这些部署中，使用 OTEL_RESOURCE_ATTRIBUTES 自己附加用户身份，通过 托管设置 文件或启动包装器按用户设置。Claude apps gateway 会话不需要任何这些：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) 指标的组织，请考虑支持高效唯一值查询的后端。

服务信息

所有指标和事件都使用以下资源属性导出：

• 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 上运行时出现）
• 仪表名称：com.anthropic.claude_code

ROI 测量资源

有关测量 Claude Code 投资回报率的综合指南，包括遥测设置、成本分析、生产力指标和自动化报告，请参阅 Claude Code ROI 测量指南。此存储库提供了现成的 Docker Compose 配置、Prometheus 和 OpenTelemetry 设置，以及用于生成与 Linear 等工具集成的生产力报告的模板。

安全和隐私

• OpenTelemetry 导出到您的后端是可选的，需要显式配置。有关 Anthropic 的单独操作遥测以及如何禁用它，请参阅 数据使用
• 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 OTEL_LOG_TOOL_CONTENT 项目符号
• 通过 OAuth 认证时，user.email 包含在遥测属性中。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段
• 默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 OTEL_LOG_USER_PROMPTS=1
• 默认情况下不收集助手响应文本。仅记录响应长度。要包含响应文本，请设置 OTEL_LOG_ASSISTANT_RESPONSES=1。与来自 Claude Code 的所有 OpenTelemetry 数据一样，响应文本仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。当此变量未设置时，OTEL_LOG_USER_PROMPTS 用作后备，因此如果您想要提示内容而不要响应内容，请设置 OTEL_LOG_ASSISTANT_RESPONSES=0
• 默认情况下不记录工具输入参数和参数。要包含它们，请设置 OTEL_LOG_TOOL_DETAILS=1。此数据仅发送到您配置的 OTEL 端点，永远不会发送到 Anthropic。参数仍可能包含敏感值，因此请根据需要配置您的遥测后端以过滤或编辑这些属性。启用后：
  • tool_result 和 tool_decision 事件包含 tool_parameters 属性，其中包含 Bash 命令、MCP 服务器和工具名称以及技能名称。full_command 等字段以未截断的形式发出
  • tool_result 事件另外包含 tool_input 属性，其中包含文件路径、URL、搜索模式和其他参数。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符
  • user_prompt 事件包含自定义、插件和 MCP 命令的逐字 command_name
  • Trace spans 包含相同的 tool_input 属性和输入派生属性（如 file_path），与 tool_input 的截断方式相同
• 默认情况下，trace spans 中不记录工具输入和输出内容。要包含它，请设置 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 而不是通过遥测流传输目录。在两种模式下，主体包含完整的对话历史（系统提示、每个先前的用户和助手轮次、工具结果），因此启用此选项意味着同意其他 OTEL_LOG_* 内容标志会揭示的所有内容。Claude 的扩展思考内容始终从这些主体中编辑，无论其他设置如何

在 Amazon Bedrock 上监控 Claude Code

有关 Amazon Bedrock 的 Claude Code 使用情况监控指南的详细信息，请参阅 Claude Code 监控实现 (Bedrock)。