监控 - Claude Code Docs

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

快速开始

使用环境变量配置 OpenTelemetry：

# 1. 启用遥测
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 选择导出器（两者都是可选的 - 仅配置您需要的）
export OTEL_METRICS_EXPORTER=otlp       # 选项：otlp、prometheus、console
export OTEL_LOGS_EXPORTER=otlp          # 选项：otlp、console

# 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_ENABLE_TELEMETRY`	启用遥测收集（必需）	`1`
`OTEL_METRICS_EXPORTER`	指标导出器类型（逗号分隔）	`console`、`otlp`、`prometheus`
`OTEL_LOGS_EXPORTER`	日志/事件导出器类型（逗号分隔）	`console`、`otlp`
`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_EXPORTER_OTLP_METRICS_CLIENT_KEY`	mTLS 身份验证的客户端密钥	客户端密钥文件的路径
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE`	mTLS 身份验证的客户端证书	客户端证书文件的路径
`OTEL_METRIC_EXPORT_INTERVAL`	导出间隔（毫秒）（默认：60000）	`5000`、`60000`
`OTEL_LOGS_EXPORT_INTERVAL`	日志导出间隔（毫秒）（默认：5000）	`1000`、`10000`
`OTEL_LOG_USER_PROMPTS`	启用用户提示内容的日志记录（默认：禁用）	`1` 启用
`OTEL_LOG_TOOL_DETAILS`	启用在工具事件中记录工具输入参数、MCP 服务器/工具名称和技能名称（默认：禁用）	`1` 启用
`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`	指标时间性偏好（默认：`delta`）。如果您的后端期望累积时间性，请设置为 `cumulative`	`delta`、`cumulative`
`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`	刷新动态标头的间隔（默认：1740000ms / 29 分钟）	`900000`

指标基数控制

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

环境变量	描述	默认值	禁用示例
`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`

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

动态标头

对于需要动态身份验证的企业环境，您可以配置脚本来动态生成标头：

设置配置

添加到您的 .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 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠
特殊字符：超出允许范围的字符必须进行百分比编码

示例：

# ❌ 无效 - 包含空格
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ 有效 - 改用下划线或驼峰式大小写
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。

示例配置

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

指标详情

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

会话计数器

在每个会话开始时递增。属性：

所有标准属性

代码行计数器

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

所有标准属性
type：（"added"、"removed"）

拉取请求计数器

通过 Claude Code 创建拉取请求时递增。属性：

所有标准属性

提交计数器

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

所有标准属性

成本计数器

在每个 API 请求后递增。属性：

所有标准属性
model：模型标识符（例如，“claude-sonnet-4-6”）

令牌计数器

在每个 API 请求后递增。属性：

所有标准属性
type：（"input"、"output"、"cacheRead"、"cacheCreation"）
model：模型标识符（例如，“claude-sonnet-4-6”）

代码编辑工具决策计数器

当用户接受或拒绝 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`	UUID v4 标识符，链接处理单个用户提示时生成的所有事件

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

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

用户提示事件

当用户提交提示时记录。 事件名称：claude_code.user_prompt 属性：

所有标准属性
event.name："user_prompt"
event.timestamp：ISO 8601 时间戳
event.sequence：单调递增的计数器，用于在会话内排序事件
prompt_length：提示的长度
prompt：提示内容（默认为已编辑，使用 OTEL_LOG_USER_PROMPTS=1 启用）

工具结果事件

当工具完成执行时记录。 事件名称：claude_code.tool_result 属性：

所有标准属性
event.name："tool_result"
event.timestamp：ISO 8601 时间戳
event.sequence：单调递增的计数器，用于在会话内排序事件
tool_name：工具的名称
success："true" 或 "false"
duration_ms：执行时间（毫秒）
error：错误消息（如果失败）
decision_type："accept" 或 "reject"
decision_source：决策来源 - "config"、"hook"、"user_permanent"、"user_temporary"、"user_abort" 或 "user_reject"
tool_result_size_bytes：工具结果的大小（字节）
mcp_server_scope：MCP 服务器范围标识符（用于 MCP 工具）
tool_parameters：包含工具特定参数的 JSON 字符串（如果可用）
- 对于 Bash 工具：包括 bash_command、full_command、timeout、description、dangerouslyDisableSandbox 和 git_commit_id（git commit 命令成功时的提交 SHA）
- 对于 MCP 工具（当 OTEL_LOG_TOOL_DETAILS=1 时）：包括 mcp_server_name、mcp_tool_name
- 对于 Skill 工具（当 OTEL_LOG_TOOL_DETAILS=1 时）：包括 skill_name
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-4-6”）
cost_usd：USD 估计成本
duration_ms：请求持续时间（毫秒）
input_tokens：输入令牌数
output_tokens：输出令牌数
cache_read_tokens：从缓存读取的令牌数
cache_creation_tokens：用于缓存创建的令牌数
speed："fast" 或 "normal"，指示是否启用了快速模式

API 错误事件

当对 Claude 的 API 请求失败时记录。 事件名称：claude_code.api_error 属性：

所有标准属性
event.name："api_error"
event.timestamp：ISO 8601 时间戳
event.sequence：单调递增的计数器，用于在会话内排序事件
model：使用的模型（例如，“claude-sonnet-4-6”）
error：错误消息
status_code：HTTP 状态代码（字符串形式），或 "undefined" 用于非 HTTP 错误
duration_ms：请求持续时间（毫秒）
attempt：尝试次数（对于重试的请求）
speed："fast" 或 "normal"，指示是否启用了快速模式

工具决策事件

当做出工具权限决策（接受/拒绝）时记录。 事件名称：claude_code.tool_decision 属性：

所有标准属性
event.name："tool_decision"
event.timestamp：ISO 8601 时间戳
event.sequence：单调递增的计数器，用于在会话内排序事件
tool_name：工具的名称（例如，“Read”、“Edit”、“Write”、“NotebookEdit”）
decision："accept" 或 "reject"
source：决策来源 - "config"、"hook"、"user_permanent"、"user_temporary"、"user_abort" 或 "user_reject"

解释指标和事件数据

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

使用情况监控

指标	分析机会
`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 控制台、AWS Bedrock 或 Google Cloud Vertex）。

警报和分段

要考虑的常见警报：

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

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

事件分析

事件数据提供了对 Claude Code 交互的详细见解： 工具使用模式：分析工具结果事件以识别：

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

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

后端考虑事项

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

对于指标

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

对于事件/日志

日志聚合系统（例如，Elasticsearch、Loki）：全文搜索、日志分析
列式存储（例如，ClickHouse）：结构化事件分析
全功能可观测性平台（例如，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 上运行时出现）
仪表名称：com.anthropic.claude_code

ROI 测量资源

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

安全和隐私

遥测是可选的，需要显式配置
原始文件内容和代码片段不包含在指标或事件中。工具执行事件在 tool_parameters 字段中包含 bash 命令和文件路径，这可能包含敏感值。如果您的命令可能包含机密，请配置您的遥测后端以过滤或编辑 tool_parameters
通过 OAuth 认证时，user.email 包含在遥测属性中。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段
默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 OTEL_LOG_USER_PROMPTS=1
默认情况下不记录工具输入参数。要包含它们，请设置 OTEL_LOG_TOOL_DETAILS=1。启用后，tool_result 事件包含 MCP 服务器/工具名称和技能名称，以及包含文件路径、URL、搜索模式和其他参数的 tool_input 属性。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符，但参数仍可能包含敏感值。根据需要配置您的遥测后端以过滤或编辑 tool_input

在 Amazon Bedrock 上监控 Claude Code

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

管理

​快速开始

​管理员配置

​配置详情

​常见配置变量

​指标基数控制

​动态标头

​设置配置

​脚本要求

​刷新行为

​多团队组织支持

​示例配置

​可用的指标和事件

​标准属性

​指标

​指标详情

​会话计数器

​代码行计数器

​拉取请求计数器

​提交计数器

​成本计数器

​令牌计数器

​代码编辑工具决策计数器

​活跃时间计数器

​事件

​事件关联属性

​用户提示事件

​工具结果事件

​API 请求事件

​API 错误事件

​工具决策事件

​解释指标和事件数据

​使用情况监控

​成本监控

​警报和分段

​事件分析

​后端考虑事项

​对于指标

​对于事件/日志

​服务信息

​ROI 测量资源

​安全和隐私

​在 Amazon Bedrock 上监控 Claude Code

快速开始

管理员配置

配置详情

常见配置变量

指标基数控制

动态标头

设置配置

脚本要求

刷新行为

多团队组织支持

示例配置

可用的指标和事件

标准属性

指标

指标详情

会话计数器

代码行计数器

拉取请求计数器

提交计数器

成本计数器

令牌计数器

代码编辑工具决策计数器

活跃时间计数器

事件

事件关联属性

用户提示事件

工具结果事件

API 请求事件

API 错误事件

工具决策事件

解释指标和事件数据

使用情况监控

成本监控

警报和分段

事件分析

后端考虑事项

对于指标

对于事件/日志

服务信息

ROI 测量资源

安全和隐私

在 Amazon Bedrock 上监控 Claude Code