Claude Code官方文档监控OpenTelemetry

Claude Code 监控配置 - OpenTelemetry 部署完整教程

通过 OpenTelemetry 导出指标、事件和分布式跟踪，跨组织跟踪 Claude Code 使用情况、成本和工具活动。

发布于 2025年5月1日 · 阅读约 34 分钟

监控

了解如何为 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

ℹ️ 默认导出间隔为指标 60 秒和日志 5 秒。在设置期间，您可能希望使用更短的间隔用于调试目的。请记住为生产使用重置这些值。

有关完整配置选项，请参阅 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"
  }
}

ℹ️ 托管设置可以通过 MDM（移动设备管理）或其他设备管理解决方案分发。在托管设置文件中定义的环境变量具有高优先级，用户无法覆盖。

Claude Code 不会将 OTEL_* 环境变量传递给它生成的子进程，包括 Bash 工具、hooks、MCP 服务器和语言服务器。通过 Bash 工具运行的已进行 OpenTelemetry 检测的应用程序不会继承 Claude Code 的导出器端点或标头，因此如果该应用程序需要导出自己的遥测，请直接在命令中设置这些变量。

配置详情

常见配置变量

环境变量	描述	示例值
`CLAUDE_CODE_ENABLE_TELEMETRY`	启用遥测收集（必需）	`1`
`OTEL_METRICS_EXPORTER`	指标导出器类型，逗号分隔。使用 `none` 禁用	`console`、`otlp`、`prometheus`、`none`
`OTEL_LOGS_EXPORTER`	日志/事件导出器类型，逗号分隔。使用 `none` 禁用	`console`、`otlp`、`none`
`OTEL_EXPORTER_OTLP_PROTOCOL`	OTLP 导出器的协议，适用于所有信号	`grpc`、`http/json`、`http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT`	所有信号的 OTLP 收集器端点	`http://localhost:4317`
`OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`	指标协议，覆盖常规设置	`grpc`、`http/json`、`http/protobuf`
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	OTLP 指标端点，覆盖常规设置	`http://localhost:4318/v1/metrics`
`OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`	日志协议，覆盖常规设置	`grpc`、`http/json`、`http/protobuf`
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	OTLP 日志端点，覆盖常规设置	`http://localhost:4318/v1/logs`
`OTEL_EXPORTER_OTLP_HEADERS`	OTLP 的身份验证标头	`Authorization=Bearer token`
`OTEL_METRIC_EXPORT_INTERVAL`	导出间隔（毫秒）（默认：60000）	`5000`、`60000`
`OTEL_LOGS_EXPORT_INTERVAL`	日志导出间隔（毫秒）（默认：5000）	`1000`、`10000`
`OTEL_LOG_USER_PROMPTS`	启用用户提示内容的日志记录（默认：禁用）	`1` 启用
`OTEL_LOG_TOOL_DETAILS`	启用在工具事件和 trace span 属性中记录工具参数和输入参数：Bash 命令、MCP 服务器和工具名称、技能名称和工具输入。还在 `user_prompt` 事件上启用自定义、插件和 MCP 命令名称（默认：禁用）	`1` 启用
`OTEL_LOG_TOOL_CONTENT`	启用在 span 事件中记录工具输入和输出内容（默认：禁用）。需要 tracing。内容在 60 KB 处截断	`1` 启用
`OTEL_LOG_RAW_API_BODIES`	将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出（默认：禁用）。主体包括整个对话历史。启用此选项意味着同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 会揭示的所有内容	`1` 用于在 60 KB 处截断的内联主体，或 `file:<dir>` 用于磁盘上的未截断主体，事件中带有 `body_ref` 指针
`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`	指标时间性偏好（默认：`delta`）。如果您的后端期望累积时间性，请设置为 `cumulative`	`delta`、`cumulative`
`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`	刷新动态标头的间隔（默认：1740000ms / 29 分钟）	`900000`

mTLS 身份验证

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

协议	客户端证书变量	信任收集器的 CA
`http/protobuf`、`http/json`	`CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可选的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。请参阅网络配置	`NODE_EXTRA_CA_CERTS`
`grpc`	`OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或每个信号的变体，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以为每个信号使用不同的证书	`OTEL_EXPORTER_OTLP_CERTIFICATE`

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

指标基数控制

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

环境变量	描述	默认值	禁用示例
`OTEL_METRICS_INCLUDE_SESSION_ID`	在指标中包含 session.id 属性	`true`	`false`
`OTEL_METRICS_INCLUDE_VERSION`	在指标中包含 app.version 属性	`false`	`true`
`OTEL_METRICS_INCLUDE_ACCOUNT_UUID`	在指标中包含 user.account_uuid 和 user.account_id 属性	`true`	`false`

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

Traces（测试版）

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

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

环境变量	描述	示例值
`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`	启用 span 跟踪（必需）。也接受 `ENABLE_ENHANCED_TELEMETRY_BETA`	`1`
`OTEL_TRACES_EXPORTER`	Traces 导出器类型，逗号分隔。使用 `none` 禁用	`console`、`otlp`、`none`
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`	Traces 协议，覆盖 `OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`、`http/json`、`http/protobuf`
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	OTLP traces 端点，覆盖 `OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4318/v1/traces`
`OTEL_TRACES_EXPORT_INTERVAL`	Span 批量导出间隔（毫秒）（默认：5000）	`1000`、`10000`

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 运行的脚本和命令启用端到端分布式跟踪。

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

Span 层次结构

每个用户提示启动一个 claude_code.interaction 根 span。API 调用、工具调用和 hook 执行被记录为其子级。工具 span 有两个自己的子 span：一个用于等待权限决策所花费的时间，一个用于执行本身。当 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
    └── (Task 工具) 子代理 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

属性	描述	门控条件
`user_prompt`	提示文本。除非设置了门控条件，否则值为 `<REDACTED>`	`OTEL_LOG_USER_PROMPTS`
`user_prompt_length`	提示长度（字符数）
`interaction.sequence`	此会话中交互的基于 1 的计数器
`interaction.duration_ms`	轮次的实际时钟持续时间

claude_code.llm_request

属性	描述	门控条件
`model`	模型标识符
`gen_ai.system`	始终为 `anthropic`。OpenTelemetry GenAI 语义约定
`gen_ai.request.model`	与 `model` 相同的值。OpenTelemetry GenAI 语义约定
`query_source`	发出请求的子系统，例如 `repl_main_thread` 或子代理名称
`speed`	`fast` 或 `normal`
`llm_request.context`	`interaction`、`tool` 或 `standalone`，取决于父 span
`duration_ms`	包括重试的实际时钟持续时间
`ttft_ms`	首个令牌的时间（毫秒）
`input_tokens`	API 使用块中的输入令牌计数
`output_tokens`	输出令牌计数
`cache_read_tokens`	从提示缓存读取的令牌
`cache_creation_tokens`	写入提示缓存的令牌
`request_id`	来自 `request-id` 响应标头的 Anthropic API 请求 ID
`gen_ai.response.id`	与 `request_id` 相同的值。OpenTelemetry GenAI 语义约定
`client_request_id`	最后一次尝试的客户端生成的 `x-client-request-id`
`attempt`	为此请求进行的总尝试次数
`success`	`true` 或 `false`
`status_code`	请求失败时的 HTTP 状态代码
`error`	请求失败时的错误消息
`response.has_tool_call`	当响应包含工具使用块时为 `true`
`stop_reason`	API 响应 `stop_reason`，例如 `end_turn`、`tool_use`、`max_tokens`、`stop_sequence`、`pause_turn` 或 `refusal`
`gen_ai.response.finish_reasons`	与 `stop_reason` 相同的值，包装在字符串数组中。OpenTelemetry GenAI 语义约定

每次重试尝试也被记录为 gen_ai.request.attempt span 事件，具有 attempt 和 client_request_id 属性。

claude_code.tool

属性	描述	门控条件
`tool_name`	工具名称
`duration_ms`	包括权限等待和执行的实际时钟持续时间
`result_tokens`	工具结果的近似令牌大小
`file_path`	Read、Edit 和 Write 工具的目标文件路径	`OTEL_LOG_TOOL_DETAILS`
`full_command`	Bash 工具的命令字符串	`OTEL_LOG_TOOL_DETAILS`
`skill_name`	Skill 工具的技能名称	`OTEL_LOG_TOOL_DETAILS`
`subagent_type`	Task 工具的子代理类型	`OTEL_LOG_TOOL_DETAILS`

当 OTEL_LOG_TOOL_CONTENT=1 时，此 span 还记录一个 tool.output span 事件，其属性包含工具的输入和输出主体，在每个属性处截断为 60 KB。

动态标头

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

设置配置

添加到您的 .claude/settings.json：

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

脚本要求

脚本必须输出有效的 JSON，其中包含表示 HTTP 标头的字符串键值对：

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

刷新行为

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

多团队组织支持

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

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

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

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

⚠️ OTEL_RESOURCE_ATTRIBUTES 的重要格式要求：

OTEL_RESOURCE_ATTRIBUTES 环境变量使用逗号分隔的键=值对，具有严格的格式要求：

不允许空格：值不能包含空格。例如，user.organizationName=My Company 无效

格式：必须是逗号分隔的键=值对：key1=value1,key2=value2

允许的字符：仅 US-ASCII 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠

特殊字符：超出允许范围的字符必须进行百分比编码

示例配置

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

可用的指标和事件

标准属性

所有指标和事件共享这些标准属性：

属性	描述	控制方式
`session.id`	唯一的会话标识符	`OTEL_METRICS_INCLUDE_SESSION_ID`（默认：true）
`app.version`	当前 Claude Code 版本	`OTEL_METRICS_INCLUDE_VERSION`（默认：false）
`organization.id`	组织 UUID（已认证时）	可用时始终包含
`user.account_uuid`	账户 UUID（已认证时）	`OTEL_METRICS_INCLUDE_ACCOUNT_UUID`（默认：true）
`user.account_id`	账户 ID，采用与 Anthropic 管理 API 匹配的标记格式（已认证时），例如 `user_01BWBeN28...`	`OTEL_METRICS_INCLUDE_ACCOUNT_UUID`（默认：true）
`user.id`	匿名设备/安装标识符，按 Claude Code 安装生成	始终包含
`user.email`	用户电子邮件地址（通过 OAuth 认证时）	可用时始终包含
`terminal.type`	终端类型，例如 `iTerm.app`、`vscode`、`cursor` 或 `tmux`	检测到时始终包含

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

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

指标

Claude Code 导出以下指标：

指标名称	描述	单位
`claude_code.session.count`	启动的 CLI 会话计数	count
`claude_code.lines_of_code.count`	修改的代码行数计数	count
`claude_code.pull_request.count`	创建的拉取请求数	count
`claude_code.commit.count`	创建的 git 提交数	count
`claude_code.cost.usage`	Claude Code 会话的成本	USD
`claude_code.token.usage`	使用的令牌数	tokens
`claude_code.code_edit_tool.decision`	代码编辑工具权限决策计数	count
`claude_code.active_time.total`	总活跃时间（秒）	s

事件

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

claude_code.user_prompt - 当用户提交提示时记录
claude_code.tool_result - 当工具完成执行时记录
claude_code.api_request - 为每个对 Claude 的 API 请求记录
claude_code.api_error - 当对 Claude 的 API 请求失败时记录
claude_code.api_request_body - 当设置了 OTEL_LOG_RAW_API_BODIES 时，为每个 API 请求尝试记录
claude_code.api_response_body - 当设置了 OTEL_LOG_RAW_API_BODIES 时，为每个成功的 API 响应记录
claude_code.tool_decision - 当做出工具权限决策（接受/拒绝）时记录
claude_code.permission_mode_changed - 当权限模式更改时记录
claude_code.auth - 当 /login 或 /logout 完成时记录
claude_code.mcp_server_connection - 当 MCP 服务器连接、断开连接或连接失败时记录
claude_code.internal_error - 当 Claude Code 捕获意外的内部错误时记录
claude_code.plugin_installed - 当插件完成安装时记录
claude_code.skill_activated - 当调用技能时记录
claude_code.at_mention - 当 Claude Code 在提示中解析 @-提及时记录
claude_code.api_retries_exhausted - 当 API 请求在多次尝试后失败时记录一次
claude_code.hook_execution_start - 当一个或多个 hooks 开始为 hook 事件执行时记录
claude_code.hook_execution_complete - 当 hook 事件的所有 hooks 完成时记录
claude_code.compaction - 当对话压缩完成时记录

每个事件都包含详细的属性，如时间戳、序列、模型、令牌计数、错误代码等。每个属性的完整字段列表请参考 Anthropic 官方监控文档。

事件关联属性

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

属性	描述
`prompt.id`	UUID v4 标识符，链接处理单个用户提示时生成的所有事件

要跟踪由单个提示触发的所有活动，请按特定 prompt.id 值过滤您的事件。

ℹ️ prompt.id 有意从指标中排除，因为每个提示生成唯一的 ID，这会创建一个不断增长的时间序列数。仅将其用于事件级分析和审计跟踪。

解释指标和事件数据

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

使用情况监控

指标	分析机会
`claude_code.token.usage`	按 `type`（输入/输出）、用户、团队或模型分解
`claude_code.session.count`	跟踪随时间推移的采用和参与度
`claude_code.lines_of_code.count`	通过跟踪代码添加/删除来衡量生产力
`claude_code.commit.count` & `claude_code.pull_request.count`	了解对开发工作流的影响

成本监控

claude_code.cost.usage 指标有助于：

跟踪团队或个人的使用趋势
识别高使用会话以进行优化

ℹ️ 成本指标是近似值。有关官方计费数据，请参阅您的 API 提供商（Claude 控制台、Amazon Bedrock 或 Google Cloud Vertex）。

警报和分段

要考虑的常见警报：

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

所有指标都可以按 user.account_uuid、user.account_id、organization.id、session.id、model 和 app.version 进行分段。

检测重试耗尽

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

事件上的 attempt 属性记录进行的总尝试次数。大于 CLAUDE_CODE_MAX_RETRIES（默认 10）的值表示请求在瞬时错误上耗尽了所有重试。较低的值表示不可重试的错误，例如 400 响应。

事件分析

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

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

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

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

后端考虑事项

您选择的指标、日志和跟踪后端决定了您可以执行的分析类型：

对于指标

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

对于事件/日志

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

对于跟踪

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

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

服务信息

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

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 是一个单独的数据路径
通过 OAuth 认证时，user.email 包含在遥测属性中。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段
默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 OTEL_LOG_USER_PROMPTS=1
默认情况下不记录工具输入参数和参数。要包含它们，请设置 OTEL_LOG_TOOL_DETAILS=1
默认情况下，trace spans 中不记录工具输入和输出内容。要包含它，请设置 OTEL_LOG_TOOL_CONTENT=1
默认情况下不记录原始 Anthropic Messages API 请求和响应主体。要包含它们，请设置 OTEL_LOG_RAW_API_BODIES

在 Amazon Bedrock 上监控 Claude Code

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

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。