{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后进一步探索。

# 监控

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

通过 OpenTelemetry（OTel）导出遥测数据，跟踪组织中 Claude Code 的使用情况、成本和工具活动。Claude Code 通过标准指标协议导出时间序列数据的指标，通过日志/事件协议导出事件，以及可选地通过[跟踪协议](#traces-beta)导出分布式跟踪。根据你的监控需求配置指标、日志和跟踪后端。

## 快速开始

使用环境变量配置 OpenTelemetry：

```bash theme={null}
# 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
```

<Note>
  默认导出间隔为指标 60 秒，日志 5 秒。设置期间，你可能需要使用更短的间隔进行调试。记住在生产使用时重置这些值。
</Note>

关于完整的配置选项，请参阅 [OpenTelemetry 规范](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options)。

## 管理员配置

管理员可以通过[托管设置文件](/en/settings#settings-files)为所有用户配置 OpenTelemetry 设置。这允许在整个组织中集中控制遥测设置。关于设置如何应用的更多信息，请参阅[设置优先级](/en/settings#settings-precedence)。

托管设置配置示例：

```json theme={null}
{
  "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"
  }
}
```

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

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`                             | 启用工具参数和输入参数的日志记录（默认：禁用）                                                                                                                                                                                                                                                             | `1` 以启用                                                                                                                   |
| `OTEL_LOG_TOOL_CONTENT`                             | 启用 span 事件中工具输入和输出内容的日志记录（默认：禁用）。需要[跟踪](#traces-beta)。内容在 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`。参阅[网络配置](/en/network-config#mtls-authentication)                      | `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`            |

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

### 跟踪（测试版）

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

跟踪默认关闭。要启用它，同时设置 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然后设置 `OTEL_TRACES_EXPORTER` 选择 span 发送位置。跟踪复用[常见 OTLP 配置](#common-configuration-variables)中的端点、协议、头信息和 [mTLS](#mtls-authentication)。

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

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

当跟踪活跃时，Bash 和 PowerShell 子进程自动继承包含活动工具执行 span 的 W3C 跟踪上下文的 `TRACEPARENT` 环境变量。这允许任何读取 `TRACEPARENT` 的子进程将其自己的 span 置于同一跟踪下，实现通过 Claude 运行的脚本和命令的端到端分布式跟踪。

当跟踪活跃且 Claude Code 直接连接到 Anthropic API 时，每个模型请求携带设置为 `claude_code.llm_request` span 上下文的 W3C `traceparent` 头，API 的 `traceresponse` 头被记录为 span 链接。这些共同将 Claude Code 的客户端 span 通过任何合规的中间件连接到服务端跟踪。该头不会发送给第三方提供商。

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

#### Span 层级

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

```text theme={null}
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 携带[标准属性](#standard-attributes)加上与其名称匹配的 `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` 或子代理名称                                      |          |
| `agent_id`                       | 发出请求的子代理或队友的标识符。主会话上不存在                            |          |
| `parent_agent_id`                | 生成此代理的代理标识符。主会话和直接从中生成的代理上不存在    |          |
| `speed`                          | `fast` 或 `normal`                                                                                                    |          |
| `llm_request.context`            | `interaction`、`tool` 或 `standalone`，取决于父 span                                                   |          |
| `duration_ms`                    | 包括重试在内的挂钟持续时间                                                                                 |          |
| `ttft_ms`                        | 首个 token 的时间（毫秒）                                                                                   |          |
| `input_tokens`                   | API 使用块中的输入 token 计数                                                                            |          |
| `output_tokens`                  | 输出 token 计数                                                                                                    |          |
| `cache_read_tokens`              | 从提示缓存读取的 token                                                                                         |          |
| `cache_creation_tokens`          | 写入提示缓存的 token                                                                                        |          |
| `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 语义约定                       |          |

每次重试尝试也记录为带有 `attempt` 和 `client_request_id` 属性的 `gen_ai.request.attempt` span 事件。

**`claude_code.tool`**

| 属性         | 描述                                                                                                        | 门控条件                |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `tool_name`       | 工具名称                                                                                                          |                         |
| `duration_ms`     | 包括权限等待和执行在内的挂钟持续时间                                                        |                         |
| `result_tokens`   | 工具结果的近似 token 大小                                                                          |                         |
| `agent_id`        | 运行工具的子代理或队友的标识符。主会话上不存在                               |                         |
| `parent_agent_id` | 生成此代理的代理标识符。主会话和直接从中生成的代理上不存在 |                         |
| `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 处截断。

**`claude_code.tool.blocked_on_user`**

| 属性     | 描述                                                               | 门控条件 |
| ------------- | ------------------------------------------------------------------------- | -------- |
| `duration_ms` | 等待权限决定的时间                            |          |
| `decision`    | `accept` 或 `reject`                                                      |          |
| `source`      | 决定来源，匹配[工具决定事件](#tool-decision-event) |          |

**`claude_code.tool.execution`**

| 属性     | 描述                                                                                                                                       | 门控条件                |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `duration_ms` | 运行工具正文的时间                                                                                                                  |                         |
| `success`     | `true` 或 `false`                                                                                                                                 |                         |
| `error`       | 执行失败时的错误类别字符串，如 `Error:ENOENT` 或 `ShellError`。设置门控时包含完整错误消息 | `OTEL_LOG_TOOL_DETAILS` |

**`claude_code.hook`**

此 span 仅在详细测试版跟踪活跃时发出，这除了上述跟踪导出器配置外还需要 `ENABLE_BETA_TRACING_DETAILED=1` 和 `BETA_TRACING_ENDPOINT`。在交互式 CLI 会话中，这还需要你的组织被列入该功能的允许列表。Agent SDK 和非交互式 `-p` 会话不受门控。仅设置 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 时不会发出。

| 属性                | 描述                                      | 门控条件                |
| ------------------------ | ------------------------------------------------ | ----------------------- |
| `hook_event`             | Hook 事件类型，如 `PreToolUse`            |                         |
| `hook_name`              | 完整 hook 名称，如 `PreToolUse:Write`       |                         |
| `num_hooks`              | 执行的匹配 hook 命令数量        |                         |
| `hook_definitions`       | JSON 序列化的 hook 配置               | `OTEL_LOG_TOOL_DETAILS` |
| `duration_ms`            | 所有匹配 hooks 的挂钟持续时间        |                         |
| `num_success`            | 成功完成的 hooks 计数       |                         |
| `num_blocking`           | 返回阻止决定的 hooks 计数 |                         |
| `num_non_blocking_error` | 未阻止但失败的 hooks 计数      |                         |
| `num_cancelled`          | 完成前取消的 hooks 计数       |                         |

<Note>
  其他内容承载属性（如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`）仅在详细测试版跟踪活跃时发出。它们不是稳定 span schema 的一部分。`user_system_prompt` 还需要 `OTEL_LOG_USER_PROMPTS=1`。它仅携带你通过 `systemPrompt` SDK 选项或 `--system-prompt` 和 `--append-system-prompt` 标志提供的系统提示文本，在 60 KB 处截断，并且每个会话发出一次而非每次请求。
</Note>

### 动态头信息

对于需要动态认证的企业环境，你可以配置脚本动态生成头信息。动态头信息仅适用于 `http/protobuf` 和 `http/json` 协议。`grpc` 导出器仅使用静态 `OTEL_EXPORTER_OTLP_HEADERS` 值。

#### 设置配置

添加到你的 `.claude/settings.json`：

```json theme={null}
{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}
```

值可以是可执行文件的路径（包括包含空格的路径），或带参数的 shell 命令行。在 Windows 上，值始终通过 shell 运行，因此在 JSON 值中为包含空格的路径加上引号。

#### 脚本要求

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

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

如果助手失败或打印的输出不符合这些要求，Claude Code 会在以下位置报告错误：

* `/doctor` 输出
* 使用 [`--debug`](/en/cli-reference#cli-flags) 运行时或在会话中运行 `/debug` 后的调试日志
* 使用 `-p` 启动的非交互式会话中的 stderr

#### 刷新行为

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

### 多团队组织支持

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

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

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

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

<Warning>
  **OTEL\_RESOURCE\_ATTRIBUTES 的重要格式要求：**

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

  * **不允许空格**：值不能包含空格。例如 `user.organizationName=My Company` 无效
  * **格式**：必须是逗号分隔的键=值对：`key1=value1,key2=value2`
  * **允许的字符**：仅限 US-ASCII 字符，不包括控制字符、空白、双引号、逗号、分号和反斜杠
  * **特殊字符**：允许范围外的字符必须百分比编码

  **示例：**

  ```bash theme={null}
  # 无效 - 包含空格
  export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

  # 有效 - 使用下划线或 camelCase 代替
  export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
  export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

  # 有效 - 需要时百分比编码特殊字符
  export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
  ```

  注意：用引号包裹值不会转义空格。例如 `org.name="My Company"` 导致字面值 `"My Company"`（包含引号），而非 `My Company`。
</Warning>

### 示例配置

在运行 `claude` 之前设置这些环境变量。每个块显示不同导出器或部署场景的完整配置：

```bash theme={null}
# 控制台调试（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，直到下一个提示。参阅[事件关联属性](#event-correlation-attributes)。
* `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`             | 使用的 token 数量                           | tokens |
| `claude_code.code_edit_tool.decision` | 代码编辑工具权限决定计数 | count  |
| `claude_code.active_time.total`       | 总活跃时间（秒）                    | s      |

### 指标详情

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

#### 会话计数器

在每个会话开始时递增。

**属性**：

* 所有[标准属性](#standard-attributes)
* `start_type`：会话的启动方式。`"fresh"`、`"resume"` 或 `"continue"` 之一

#### 代码行数计数器

在代码添加或移除时递增。

**属性**：

* 所有[标准属性](#standard-attributes)
* `type`：（`"added"`、`"removed"`）

#### 拉取请求计数器

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

**属性**：

* 所有[标准属性](#standard-attributes)

#### 提交计数器

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

**属性**：

* 所有[标准属性](#standard-attributes)

#### 成本计数器

每次 API 请求后递增。

**属性**：

* 所有[标准属性](#standard-attributes)
* `model`：模型标识符（例如 "claude-sonnet-4-6"）
* `query_source`：发出请求的子系统类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一
* `speed`：请求使用快速模式时为 `"fast"`。否则不存在
* `effort`：应用于请求的[努力级别](/en/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。模型不支持 effort 时不存在
* `agent.name`：发出请求的子代理类型。内置代理名称和来自官方市场插件的代理原样显示。其他用户定义的代理名称替换为 `"custom"`。请求不由命名子代理类型发出时不存在
* `skill.name`：请求活跃的技能，由 Skill 工具、`/` 命令设置，或由生成的子代理继承。内置、捆绑、用户定义和官方市场插件技能名称原样显示。第三方插件技能名称替换为 `"third-party"`。没有技能活跃时不存在
* `plugin.name`：活跃技能或子代理由插件提供时的所有者插件。官方市场插件名称原样显示。第三方插件名称替换为 `"third-party"`。技能和子代理都没有所有者插件时不存在
* `marketplace.name`：安装所有者插件的市场。仅对官方市场插件发出。否则不存在。

#### Token 计数器

每次 API 请求后递增。

**属性**：

* 所有[标准属性](#standard-attributes)
* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）
* `model`：模型标识符（例如 "claude-sonnet-4-6"）
* `query_source`：发出请求的子系统类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一
* `speed`：请求使用快速模式时为 `"fast"`。否则不存在
* `effort`：应用于请求的[努力级别](/en/model-config#adjust-effort-level)。详情参阅[成本计数器](#cost-counter)。
* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`：请求的技能、插件和代理归因。定义和编辑行为参阅[成本计数器](#cost-counter)。

#### 代码编辑工具决定计数器

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

**属性**：

* 所有[标准属性](#standard-attributes)
* `tool_name`：工具名称（`"Edit"`、`"Write"`、`"NotebookEdit"`）
* `decision`：用户决定（`"accept"`、`"reject"`）
* `source`：决定来源。`"config"`、`"hook"`、`"user_permanent"`、`"user_temporary"`、`"user_abort"` 或 `"user_reject"` 之一。每个值的含义参阅[工具决定事件](#tool-decision-event)。
* `language`：编辑文件的编程语言，如 `"TypeScript"`、`"Python"`、`"JavaScript"` 或 `"Markdown"`。无法识别的文件扩展名返回 `"unknown"`。

#### 活跃时间计数器

跟踪实际活跃使用 Claude Code 的时间，不包括空闲时间。此指标在用户交互（输入、阅读响应）和 CLI 处理（工具执行、AI 响应生成）期间递增。

**属性**：

* 所有[标准属性](#standard-attributes)
* `type`：键盘交互为 `"user"`，工具执行和 AI 响应为 `"cli"`

### 事件

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

#### 事件关联属性

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

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

要跟踪单个提示触发的所有活动，按特定 `prompt.id` 值过滤你的事件。这会返回处理该提示时的 user\_prompt 事件、任何 api\_request 事件和任何 tool\_result 事件。

<Note>
  `prompt.id` 被故意排除在指标之外，因为每个提示生成唯一 ID，这会创建不断增长的时间序列数量。仅将其用于事件级分析和审计跟踪。
</Note>

#### 用户提示事件

用户提交提示时记录。

**事件名称**：`claude_code.user_prompt`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

#### 工具结果事件

工具完成执行时记录。如果工具调用被拒绝则不发出；参阅[工具决定事件](#tool-decision-event)了解拒绝。

**事件名称**：`claude_code.tool_result`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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"` 之一。每个值的含义参阅[工具决定事件](#tool-decision-event)。仅限拒绝的来源 `"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）
  * 对于 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`
  * 对于 Skill 工具：包括 `skill_name`
  * 对于 Task 工具：包括 `subagent_type`
* `tool_input`（当 `OTEL_LOG_TOOL_DETAILS=1`）：JSON 序列化的工具参数。超过 512 个字符的单个值被截断，完整载荷限制在约 4 K 字符。适用于所有工具包括 MCP 工具。

#### API 请求事件

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

**事件名称**：`claude_code.api_request`

**属性**：

* 所有[标准属性](#standard-attributes)
* `event.name`：`"api_request"`
* `event.timestamp`：ISO 8601 时间戳
* `event.sequence`：会话内排序事件的单调递增计数器
* `model`：使用的模型（例如 "claude-sonnet-4-6"）
* `cost_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`：应用于请求的[努力级别](/en/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。模型不支持 effort 时不存在。

#### API 错误事件

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

**事件名称**：`claude_code.api_error`

**属性**：

* 所有[标准属性](#standard-attributes)
* `event.name`：`"api_error"`
* `event.timestamp`：ISO 8601 时间戳
* `event.sequence`：会话内排序事件的单调递增计数器
* `model`：使用的模型（例如 "claude-sonnet-4-6"）
* `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`：应用于请求的[努力级别](/en/model-config#adjust-effort-level)。模型不支持 effort 时不存在。

#### API 请求正文事件

设置 `OTEL_LOG_RAW_API_BODIES` 时记录每次 API 请求尝试。每次尝试发出一个事件，因此使用调整参数的重试各自产生自己的事件。

**事件名称**：`claude_code.api_request_body`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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"`：用户在权限提示中选择"Yes, and don't ask again for ..."时发出，这会将允许规则保存到个人设置中。在交互式 CLI 中，仅对该选择本身发出；匹配保存规则的后续调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，初始选择和后续规则匹配都发出 `"user_permanent"`。视为接受。
  * `"user_temporary"`：用户在权限提示中选择"Yes"进行一次性批准，或在文件编辑或读取提示中选择"... during this session"选项之一时发出。在交互式 CLI 中，仅对该选择本身发出；该会话范围授权允许的后续调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，选择和后续匹配都发出 `"user_temporary"`。视为接受。
  * `"user_abort"`：用户在不回答的情况下关闭权限提示时发出。视为拒绝。
  * `"user_reject"`：用户在提示中选择"No"时发出。在交互式 CLI 中，仅对该选择本身发出；匹配用户个人设置中拒绝规则的调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，匹配个人设置中拒绝规则的调用发出 `"user_reject"`。视为拒绝。

#### 权限模式更改事件

权限模式更改时记录，例如从 `Shift+Tab` 循环、退出计划模式或自动模式门控检查。

**事件名称**：`claude_code.permission_mode_changed`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`：连接失败时的错误代码
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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 服务器
* `skill_path_count`：插件声明的技能目录数量
* `command_path_count`：插件声明的命令目录数量
* `agent_path_count`：插件声明的代理目录数量

#### 技能激活事件

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

**事件名称**：`claude_code.skill_activated`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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"`）
* `plugin.name`（当 `OTEL_LOG_TOOL_DETAILS=1` 或插件来自官方市场时）：技能由插件提供时的所有者插件名称
* `marketplace.name`（当 `OTEL_LOG_TOOL_DETAILS=1` 或插件来自官方市场时）：安装所有者插件的市场（技能由插件提供时）

#### @提及事件

Claude Code 解析提示中的 `@` 提及时记录。不是每次提及都会发出事件：权限拒绝、超大文件、PDF 引用附件和目录列表失败等早期退出路径返回时不记录。

**事件名称**：`claude_code.at_mention`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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"`
* `hook_matcher`（当 `OTEL_LOG_TOOL_DETAILS=1`）：hook 配置中的 matcher 字符串（设置时）
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `event.name`：`"hook_execution_start"`
* `event.timestamp`：ISO 8601 时间戳
* `event.sequence`：会话内排序事件的单调递增计数器
* `hook_event`：Hook 事件类型，如 `"PreToolUse"` 或 `"PostToolUse"`
* `hook_name`：完整 hook 名称（包括 matcher），如 `"PreToolUse:Write"`
* `num_hooks`：匹配的 hook 命令数量
* `managed_only`：仅允许托管策略 hooks 时为 `"true"`
* `hook_source`：`"policySettings"` 或 `"merged"`
* `hook_definitions`：JSON 序列化的 hook 配置。仅在详细测试版跟踪和 `OTEL_LOG_TOOL_DETAILS=1` 都启用时包含

#### Hook 执行完成事件

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

**事件名称**：`claude_code.hook_execution_complete`

**属性**：

* 所有[标准属性](#standard-attributes)
* `event.name`：`"hook_execution_complete"`
* `event.timestamp`：ISO 8601 时间戳
* `event.sequence`：会话内排序事件的单调递增计数器
* `hook_event`：Hook 事件类型
* `hook_name`：完整 hook 名称（包括 matcher）
* `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"`
* `hook_definitions`：JSON 序列化的 hook 配置。仅在详细测试版跟踪和 `OTEL_LOG_TOOL_DETAILS=1` 都启用时包含

#### Hook 插件指标事件

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

**事件名称**：`claude_code.hook_plugin_metrics`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`

**属性**：

* 所有[标准属性](#standard-attributes)
* `event.name`：`"compaction"`
* `event.timestamp`：ISO 8601 时间戳
* `event.sequence`：会话内排序事件的单调递增计数器
* `trigger`：`"auto"` 或 `"manual"`
* `success`：`"true"` 或 `"false"`
* `duration_ms`：压缩持续时间
* `pre_tokens`：压缩前的近似 token 计数
* `post_tokens`：压缩后的近似 token 计数
* `error`：压缩失败时的错误消息

#### 反馈调查事件

会话质量调查显示或回答时记录。参阅[会话质量调查](/en/data-usage#session-quality-surveys)了解调查收集什么以及如何控制它们。

**事件名称**：`claude_code.feedback_survey`

**属性**：

* 所有[标准属性](#standard-attributes)
* `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`](/en/env-vars) 时为 `true`。作为布尔值发出，而非字符串。存在于 `session` 调查事件上。在此属性上过滤以确认覆盖在部署中应用

## 解释指标和事件数据

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

### 使用监控

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

### 成本监控

`claude_code.cost.usage` 指标有助于：

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

<Note>
  成本指标是近似值。关于官方计费数据，请参考你的 API 提供商（Claude Console、Amazon Bedrock 或 Google Cloud Vertex）。
</Note>

### 警报和细分

需要考虑的常见警报：

* 成本峰值
* 异常 token 消耗
* 特定用户的高会话量

所有指标可以按 `user.account_uuid`、`user.account_id`、`organization.id`、`session.id`、`model` 和 `app.version` 细分。

### 检测重试耗尽

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

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

要区分恢复的会话和停滞的会话，按 `session.id` 分组事件并检查错误之后是否存在后续 `api_request` 事件。

### 事件分析

事件数据提供 Claude Code 交互的详细洞察：

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

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

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

## 审计安全事件

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

### 将操作归因到用户

每个事件上的[标准属性](#standard-attributes)包含认证用户的身份：使用 Claude 账户登录时的 `user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`，加上安装范围的 `user.id` 和每会话的 `session.id`。

MCP 工具调用、Bash 命令和文件编辑因此归因于启动会话的开发者。Claude Code 不在单独的服务账户下操作；每个事件上记录的身份是开发者自己的 Claude 账户。

当 Claude Code 使用直接 API 密钥认证，或针对 Bedrock、Vertex AI 或 Microsoft Foundry 认证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，通过 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过[托管设置](#administrator-configuration)文件或启动包装器按用户设置：

```bash theme={null}
export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."
```

### 审计 MCP 活动

要捕获 MCP 服务器活动的完整调用详情，启用日志导出器并设置 `OTEL_LOG_TOOL_DETAILS=1`。每个 MCP 操作随后产生结构化事件，携带服务器名称、工具名称和调用参数以及标准身份属性：

| 事件                   | 它为 MCP 记录什么                                                                                                                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp_server_connection` | 服务器连接、断开连接和连接失败，带有 `server_name`、`transport_type`、`server_scope` 和错误详情                                                                          |
| `tool_result`           | 每个 MCP 工具调用，带有 `tool_name` 和 `mcp_server_scope`、包含 `mcp_server_name` 和 `mcp_tool_name` 的 `tool_parameters` 载荷，以及包含调用参数的 `tool_input` 载荷 |
| `tool_decision`         | 调用是被允许还是拒绝，以及决定来自配置、hook 还是用户                                                                                             |

没有 `OTEL_LOG_TOOL_DETAILS` 时，`tool_result` 事件仍携带 `tool_name` 和 `mcp_server_scope` 但省略 `mcp_server_name`/`mcp_tool_name` 分解和参数，`mcp_server_connection` 事件省略 `server_name` 和错误消息。

### 将安全问题映射到事件

构建检测规则时，查找你想监控的信号并在后端查询相应的事件和属性：

| 信号                                    | 事件                                        | 关键属性                                               |
| ----------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
| 工具调用被允许或拒绝，以及被谁  | `tool_decision`                              | `decision`、`source`、`tool_name`                            |
| 权限模式升级                | `permission_mode_changed`                    | `from_mode`、`to_mode`、`trigger`                            |
| 策略 hook 阻止了操作             | `hook_execution_complete`                    | `hook_event`、`num_blocking`                                 |
| 登录、登出和认证失败 | `auth`                                       | `action`、`success`、`error_category`                        |
| MCP 服务器连接或失败             | `mcp_server_connection`                      | `status`、`server_name`、`error_code`                        |
| 插件安装及其来源           | `plugin_installed`                           | `plugin.name`、`marketplace.name`、`marketplace.is_official` |
| 运行的命令和访问的文件            | `tool_result`（`OTEL_LOG_TOOL_DETAILS=1`） | `tool_parameters`、`tool_input`                              |

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

### 将事件发送到 SIEM

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

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

## 后端考虑

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

### 指标

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

### 事件/日志

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

### 跟踪

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

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

对于需要每日/每周/每月活跃用户（DAU/WAU/MAU）指标的组织，考虑支持高效唯一值查询的后端。

## 服务信息

所有指标和事件导出时带有以下资源属性：

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

## ROI 测量资源

关于 Claude Code 投资回报率测量的综合指南（包括遥测设置、成本分析、生产力指标和自动化报告），请参阅 [Claude Code ROI 测量指南](https://github.com/anthropics/claude-code-monitoring-guide)。该仓库提供即用型 Docker Compose 配置、Prometheus 和 OpenTelemetry 设置，以及与 Linear 等工具集成的生产力报告模板。

## 安全和隐私

* 向你的后端导出 OpenTelemetry 是可选的，需要显式配置。关于 Anthropic 的单独运营遥测以及如何禁用它，请参阅[数据使用](/en/data-usage#telemetry-services)
* 原始文件内容和代码片段不包含在指标或事件中。跟踪 span 是单独的数据路径：参阅下方的 `OTEL_LOG_TOOL_CONTENT` 项
* 通过 OAuth 认证时，`user.email` 包含在遥测属性中。如果你的组织对此有顾虑，请与你的遥测后端合作过滤或编辑此字段
* 用户提示内容默认不收集。仅记录提示长度。要包含提示内容，设置 `OTEL_LOG_USER_PROMPTS=1`
* 工具输入参数和参数默认不记录。要包含它们，设置 `OTEL_LOG_TOOL_DETAILS=1`。启用后，`tool_result` 事件包含带有 Bash 命令、MCP 服务器和工具名称以及技能名称的 `tool_parameters` 属性，加上带有文件路径、URL、搜索模式和其他参数的 `tool_input` 属性。`user_prompt` 事件包含自定义、插件和 MCP 命令的逐字 `command_name`。跟踪 span 包含相同的 `tool_input` 属性和从输入派生的属性如 `file_path`。超过 512 个字符的单个值被截断，总量限制在约 4 K 字符，但参数可能仍包含敏感值。根据需要配置你的遥测后端过滤或编辑这些属性
* 工具输入和输出内容默认不在跟踪 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 而非通过遥测流传输该目录。在两种模式下，正文包含完整对话历史（系统提示、每个先前的用户和助手轮次、工具结果），因此启用此选项即表示同意其他 `OTEL_LOG_*` 内容标志会暴露的所有内容。Claude 的扩展思考内容始终从这些正文中编辑，无论其他设置如何

## 在 Amazon Bedrock 上监控 Claude Code

关于 Amazon Bedrock 的详细 Claude Code 使用监控指导，请参阅 [Claude Code 监控实施（Bedrock）](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)。