通俗版 Claude Code 文档

结构照原 docs，内容改成真能照着做的人话版。
查看原始文档 目录顺序与官方保持一致

Usage and costs

监控使用

看团队都怎么用，哪儿最耗、哪儿最常用。

页面信息

对应原页

Monitoring

页面性质

第三方中文解释页

使用建议

先看人话解释，再对照原页命令和代码

这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。

如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。

这一页先讲明白

这页讲怎么盯团队使用情况，看看谁在用、怎么用、用得多不多。

不是为了盯人，而是为了心里有账。

这像看仓库出入账。你不一定要天天盯，但总得知道粮食去哪了。

对团队来说，监控使用情况能帮助你发现浪费、卡点和高频需求。

没有这些数，后面谈优化和控成本都容易拍脑袋。

先看最关键的几项：活跃度、用量、异常峰值。

别收一堆数据却不看，监控的价值在于拿来做决策。

如果目标是控成本，就把这页和 Costs 一起看。

终端里敲

原页关键片段：Quick start

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp       # Options: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Options: otlp, console, none

# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds (default: 5000ms)

# 6. Run Claude Code
claude
改配置

原页关键片段：Administrator configuration

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "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"
  }
}
目录怎么摆

原页关键片段：Traces (beta)

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Task tool) subagent claude_code.llm_request / claude_code.tool spans
改配置

原页关键片段：Dynamic headers 1

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}
终端里敲

原页关键片段：Dynamic headers 2

看到这里，别光点头，下面这条命令先跑起来再说。

#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"
终端里敲

原页关键片段：Multi-team organization support 1

看到这里，别光点头，下面这条命令先跑起来再说。

# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
关键片段

原页关键片段：Multi-team organization support 2

"Multi-team organization support"这一段里最要紧的原始写法在下面，先看它怎么落地。

# ❌ Invalid - contains spaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valid - use underscores or camelCase instead
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valid - percent-encode special characters if needed
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
关键片段

原页关键片段：Example configurations

先看下面这块原始片段，等会儿再回头看解释会顺得多。

# Console debugging (1-second intervals)
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

# Multiple exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Different endpoints/backends for metrics and logs
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

# Metrics only (no events/logs)
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

# Events/logs only (no metrics)
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
关键片段

原页关键片段：Attribute actions to users

下面这块是这一段最值钱的原文样板，先对着看一眼。

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

原页关键片段：Send events to a SIEM

想把这条规矩固定住，就把下面这块老老实实写进去。

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

预留广告位

正文中段响应式广告 等你后面真接 AdSense，这里再放正式广告。

Documentation Index

这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Quick start

这一段是在把 OpenTelemetry using environment variables: 配起来、配稳当。你主要盯住在哪儿改、怎么写、改完怎么看它真生效。

如果你看到环境变量或 settings.json，意思通常都是：这不是会话里临时喊一声就行，而是要把开关真正写进环境或配置。

终端里敲

Quick start

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp       # Options: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Options: otlp, console, none

# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds (default: 5000ms)

# 6. Run Claude Code
claude

Administrator configuration

这一块主要是在说"Administrator configuration"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

改配置

Administrator configuration

想把这条规矩固定住，就把下面这块老老实实写进去。

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

Configuration details

这里不是让你背"Configuration details"这个词，而是让你看它真干活时怎么使。

Common configuration variables

这里不是让你背"Common configuration variables"这个词，而是让你看它真干活时怎么使。

mTLS authentication

这一段主要是在把"mTLS authentication"讲实，不是只摆个标题给你看。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Metrics cardinality control

这段看着像个标题，其实是在说"Metrics cardinality control"管到哪儿。

如果你看到环境变量或 settings.json，意思通常都是：这不是会话里临时喊一声就行，而是要把开关真正写进环境或配置。

Traces (beta)

看到这里，就把"Traces (beta)"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

目录怎么摆

Traces (beta)

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Task tool) subagent claude_code.llm_request / claude_code.tool spans

Dynamic headers

这一块主要是在说"Dynamic headers"真到手上该怎么用，哪里最容易踩坑。

如果你看到环境变量或 settings.json，意思通常都是：这不是会话里临时喊一声就行，而是要把开关真正写进环境或配置。

改配置

Dynamic headers 1

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}
终端里敲

Dynamic headers 2

看到这里，别光点头，下面这条命令先跑起来再说。

#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Multi-team organization support

这一块主要是在说"Multi-team organization support"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

终端里敲

Multi-team organization support 1

看到这里，别光点头，下面这条命令先跑起来再说。

# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
关键片段

Multi-team organization support 2

"Multi-team organization support"这一段里最要紧的原始写法在下面，先看它怎么落地。

# ❌ Invalid - contains spaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valid - use underscores or camelCase instead
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valid - percent-encode special characters if needed
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Example configurations

这里是样板段。重点不是全文照抄，而是学它怎么把职责、步骤和边界写清楚。

如果你看到环境变量或 settings.json，意思通常都是：这不是会话里临时喊一声就行，而是要把开关真正写进环境或配置。

关键片段

Example configurations

先看下面这块原始片段，等会儿再回头看解释会顺得多。

# Console debugging (1-second intervals)
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

# Multiple exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Different endpoints/backends for metrics and logs
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

# Metrics only (no events/logs)
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

# Events/logs only (no metrics)
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

Available metrics and events

这一段主要是在把"Available metrics and events"讲实，不是只摆个标题给你看。

Standard attributes

这一段主要是在把"Standard attributes"讲实，不是只摆个标题给你看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Metrics

看到这里，就把"Metrics"当成一件真要上手的活来看。

Metric details

这里不是让你背"Metric details"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Events

这一块主要是在说"Events"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Interpret metrics and events data

这里主要是在交代"Interpret metrics and events data"这一块会碰到哪些事。

Usage monitoring

看到这里，就把"Usage monitoring"当成一件真要上手的活来看。

Cost monitoring

别把这段只当成标题看，它其实是在给"Cost monitoring"划边界。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Alerting and segmentation

看到这里，就把"Alerting and segmentation"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Detect retry exhaustion

看到这里，就把"Detect retry exhaustion"当成一件真要上手的活来看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Event analysis

这里主要是在交代"Event analysis"这一块会碰到哪些事。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Audit security events

这一段主要是在把"Audit security events"讲实，不是只摆个标题给你看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Attribute actions to users

这种内容最怕想当然，老老实实照它列的格式走最稳。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

关键片段

Attribute actions to users

下面这块是这一段最值钱的原文样板，先对着看一眼。

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

Audit MCP activity

这一段主要是在把"Audit MCP activity"讲实，不是只摆个标题给你看。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Map security questions to events

这一段更像在讲判断条件，什么时候该上，什么时候先别急。把触发条件看清，比背标题更重要。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Send events to a SIEM

这一块主要是在说"Send events to a SIEM"真到手上该怎么用，哪里最容易踩坑。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

改配置

Send events to a SIEM

想把这条规矩固定住，就把下面这块老老实实写进去。

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

Backend considerations

这一块主要是在说"Backend considerations"真到手上该怎么用，哪里最容易踩坑。

For metrics

这里不是让你背"For metrics"这个词，而是让你看它真干活时怎么使。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

For events/logs

这一段主要是在把"For events/logs"讲实，不是只摆个标题给你看。

For traces

这一段是在帮你从几个选项里挑 a backend that supports distributed trace storage and span correlation:。重点不只是知道有哪些，更是看代价和场景。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

照着做一遍

如果你不想来回翻，就先照这几步顺着做。

每做完一步就看一下结果，再决定要不要继续往下。

终端里敲

第 1 步：Quick start

这一段不是只让你理解意思，下面这条命令就是现在要跑的。

# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp       # Options: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Options: otlp, console, none

# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds (default: 5000ms)

# 6. Run Claude Code
claude
改配置

第 2 步：Administrator configuration

想把这条规矩固定住，就把下面这块老老实实写进去。

{
  "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"
  }
}
目录怎么摆

第 3 步：Traces (beta)

这一段主要是认目录和文件摆放位置。先把地方放对，后面才不容易串。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Task tool) subagent claude_code.llm_request / claude_code.tool spans
改配置

第 4 步：Dynamic headers 1

想把这条规矩固定住，就把下面这块老老实实写进去。

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

一眼看懂这一页

先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。

Monitoring
   |
   v
这是 Usage and costs 里的一摊要紧活
   |
   v
先弄懂，再下手

文末提醒

这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。

人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。

预留广告位

文末横幅广告 适合放在文章读完以后，不抢首屏注意力。