OpenTelemetry 支援目前處於測試階段，細節可能會有所變更。

Claude Code 中的 OpenTelemetry

Claude Code 支援 OpenTelemetry (OTel) 指標用於監控和可觀測性。本文檔說明如何為 Claude Code 啟用和配置 OTel。

所有指標都是通過 OpenTelemetry 的標準指標協議導出的時間序列數據。使用者有責任確保其指標後端正確配置，並且聚合粒度符合其監控需求。

快速入門

使用環境變數配置 OpenTelemetry：

# 1. 啟用遙測
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 選擇導出器
export OTEL_METRICS_EXPORTER=otlp       # 選項：otlp, prometheus, 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. 用於調試：減少導出間隔（默認：600000ms/10分鐘）
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 秒

# 6. 運行 Claude Code
claude

默認導出間隔為 10 分鐘。在設置過程中，您可能希望使用較短的間隔進行調試。請記得在生產環境中重置此設置。

有關完整配置選項，請參閱 OpenTelemetry 規範。

管理員配置

管理員可以通過管理設置文件為所有用戶配置 OpenTelemetry 設置。這允許在整個組織中集中控制遙測設置。有關設置如何應用的更多信息，請參閱配置層次結構。

管理設置文件位於：

macOS：/Library/Application Support/ClaudeCode/managed-settings.json
Linux：/etc/claude-code/managed-settings.json

管理設置配置示例：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

管理設置可以通過 MDM（移動設備管理）或其他設備管理解決方案進行分發。在管理設置文件中定義的環境變數具有較高的優先級，用戶無法覆蓋。

配置詳情

常用配置變數

環境變數	描述	示例值
`CLAUDE_CODE_ENABLE_TELEMETRY`	啟用遙測收集（必需）	`1`
`OTEL_METRICS_EXPORTER`	要使用的導出器類型（逗號分隔）	`console`, `otlp`, `prometheus`
`OTEL_EXPORTER_OTLP_PROTOCOL`	OTLP 導出器的協議	`grpc`, `http/json`, `http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP 收集器端點	`http://localhost:4317`
`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`	導出間隔（毫秒，默認：10000）	`5000`, `60000`

指標基數控制

以下環境變數控制指標中包含哪些屬性，以管理基數：

環境變數	描述	默認值	禁用示例
`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 屬性	`true`	`false`

這些變數有助於控制指標的基數，這會影響指標後端的存儲需求和查詢性能。較低的基數通常意味著更好的性能和更低的存儲成本，但分析數據的粒度較低。

配置示例

# 控制台調試（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

可用指標

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

指標詳情

所有指標共享這些標準屬性：

session.id：唯一會話標識符（由 OTEL_METRICS_INCLUDE_SESSION_ID 控制）
app.version：當前 Claude Code 版本（由 OTEL_METRICS_INCLUDE_VERSION 控制）
organization.id：組織 UUID（已認證時）
user.account_uuid：帳戶 UUID（已認證時，由 OTEL_METRICS_INCLUDE_ACCOUNT_UUID 控制）

1. 會話計數器

在每個會話開始時發出。

2. 代碼行計數器

在添加或刪除代碼時發出。

附加屬性：type（"added" 或 "removed"）

3. 拉取請求計數器

通過 Claude Code 創建拉取請求時發出。

4. 提交計數器

通過 Claude Code 創建 git 提交時發出。

5. 成本計數器

在每次 API 請求後發出。

附加屬性：model

6. 令牌計數器

在每次 API 請求後發出。

附加屬性：type（"input"、"output"、"cacheRead"、"cacheCreation"）和 model

解讀指標數據

這些指標提供了使用模式、生產力和成本的洞察：

使用監控

指標	分析機會
`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 提供商（Anthropic Console、AWS Bedrock 或 Google Cloud Vertex）。

警報和分段

需要考慮的常見警報：

成本突增
異常的令牌消耗
特定用戶的高會話量

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

後端考慮因素

後端類型	最適合
時間序列數據庫（Prometheus）	速率計算、聚合指標
列式存儲（ClickHouse）	複雜查詢、唯一用戶分析
可觀測性平台（Honeycomb、Datadog）	高級查詢、可視化、警報

對於 DAU/WAU/MAU 指標，選擇支持高效唯一值查詢的後端。

服務信息

所有指標都導出有：

服務名稱：claude-code
服務版本：當前 Claude Code 版本
計量器名稱：com.anthropic.claude_code

安全考慮因素

遙測是選擇性加入的，需要明確配置
敏感信息如 API 密鑰或文件內容永遠不會包含在指標中

Claude Code

​Claude Code 中的 OpenTelemetry

​快速入門

​管理員配置

​配置詳情

​常用配置變數

​指標基數控制

​配置示例

​可用指標

​指標詳情

​1. 會話計數器

​2. 代碼行計數器

​3. 拉取請求計數器

​4. 提交計數器

​5. 成本計數器

​6. 令牌計數器

​解讀指標數據

​使用監控

​成本監控

​警報和分段

​後端考慮因素

​服務信息

​安全考慮因素

Claude Code 中的 OpenTelemetry

快速入門

管理員配置

配置詳情

常用配置變數

指標基數控制

配置示例

可用指標

指標詳情

1. 會話計數器

2. 代碼行計數器

3. 拉取請求計數器

4. 提交計數器

5. 成本計數器

6. 令牌計數器

解讀指標數據

使用監控

成本監控

警報和分段

後端考慮因素

服務信息

安全考慮因素