Claude Code 支援 OpenTelemetry (OTel) 指標和事件，用於監控和可觀測性。

所有指標都是透過 OpenTelemetry 標準指標協定匯出的時間序列資料，事件則透過 OpenTelemetry 的日誌/事件協定匯出。使用者有責任確保其指標和日誌後端已正確配置，且聚合粒度符合其監控需求。

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

​
快速開始

使用環境變數配置 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 設定。這允許在整個組織中集中控制遙測設定。有關設定如何應用的更多資訊，請參閱設定優先順序。

管理設定檔案位於：

  • 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_LOGS_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_LOGS_EXPORTER日誌/事件匯出器類型（逗號分隔）console、otlp
OTEL_EXPORTER_OTLP_PROTOCOLOTLP 匯出器協定（所有訊號）grpc、http/json、http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTOTLP 收集器端點（所有訊號）http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL指標協定（覆蓋一般設定）grpc、http/json、http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTOTLP 指標端點（覆蓋一般設定）http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL日誌協定（覆蓋一般設定）grpc、http/json、http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTLP 日誌端點（覆蓋一般設定）http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSOTLP 驗證標頭Authorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYmTLS 驗證的用戶端金鑰用戶端金鑰檔案路徑
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATEmTLS 驗證的用戶端憑證用戶端憑證檔案路徑
OTEL_METRIC_EXPORT_INTERVAL匯出間隔（毫秒）（預設：60000）5000、60000
OTEL_LOGS_EXPORT_INTERVAL日誌匯出間隔（毫秒）（預設：5000）1000、10000
OTEL_LOG_USER_PROMPTS啟用使用者提示內容記錄（預設：停用）1 啟用

​
指標基數控制

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

環境變數描述預設值停用範例
OTEL_METRICS_INCLUDE_SESSION_ID在指標中包含 session.id 屬性truefalse
OTEL_METRICS_INCLUDE_VERSION在指標中包含 app.version 屬性falsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUID在指標中包含 user.account_uuid 屬性truefalse

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

​
多團隊組織支援

擁有多個團隊或部門的組織可以使用 OTEL_RESOURCE_ATTRIBUTES 環境變數新增自訂屬性來區分不同群組：

# 新增用於團隊識別的自訂屬性
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

這些自訂屬性將包含在所有指標和事件中，讓您能夠：

  • 按團隊或部門篩選指標
  • 按成本中心追蹤成本
  • 建立特定團隊的儀表板
  • 為特定團隊設定警報

​
配置範例

# 控制台除錯（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.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.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）
terminal.type終端類型（例如 iTerm.app、vscode、cursor、tmux）偵測到時始終包含

​
指標

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.usageClaude Code 會話的成本USD
claude_code.token.usage使用的權杖數量tokens
claude_code.code_edit_tool.decision程式碼編輯工具權限決策計數count

​
指標詳細資訊

​
會話計數器

在每個會話開始時遞增。

屬性：

​
程式碼行數計數器

當新增或移除程式碼時遞增。

屬性：

​
拉取請求計數器

透過 Claude Code 建立拉取請求時遞增。

屬性：

​
提交計數器

透過 Claude Code 建立 git 提交時遞增。

屬性：

​
成本計數器

每次 API 請求後遞增。

屬性：

  • 所有標準屬性
  • model：模型識別碼（例如 “claude-3-5-sonnet-20241022”）

​
權杖計數器

每次 API 請求後遞增。

屬性：

  • 所有標準屬性
  • type：（"input"、"output"、"cacheRead"、"cacheCreation"）
  • model：模型識別碼（例如 “claude-3-5-sonnet-20241022”）

​
程式碼編輯工具決策計數器

當使用者接受或拒絕 Edit、MultiEdit、Write 或 NotebookEdit 工具使用時遞增。

屬性：

  • 所有標準屬性
  • tool：工具名稱（"Edit"、"MultiEdit"、"Write"、"NotebookEdit"）
  • decision：使用者決策（"accept"、"reject"）
  • language：編輯檔案的程式語言（例如 "TypeScript"、"Python"、"JavaScript"、"Markdown"）。對於無法識別的副檔名返回 "unknown"。

​
事件

Claude Code 透過 OpenTelemetry 日誌/事件匯出以下事件（當配置 OTEL_LOGS_EXPORTER 時）：

​
使用者提示事件

當使用者提交提示時記錄。

事件名稱：claude_code.user_prompt

屬性：

  • 所有標準屬性
  • event.name："user_prompt"
  • event.timestamp：ISO 8601 時間戳
  • prompt_length：提示長度
  • prompt：提示內容（預設已編輯，使用 OTEL_LOG_USER_PROMPTS=1 啟用）

​
工具結果事件

當工具完成執行時記錄。

事件名稱：claude_code.tool_result

屬性：

  • 所有標準屬性
  • event.name："tool_result"
  • event.timestamp：ISO 8601 時間戳
  • name：工具名稱
  • success："true" 或 "false"
  • duration_ms：執行時間（毫秒）
  • error：錯誤訊息（如果失敗）

​
API 請求事件

為每個對 Claude 的 API 請求記錄。

事件名稱：claude_code.api_request

屬性：

  • 所有標準屬性
  • event.name："api_request"
  • event.timestamp：ISO 8601 時間戳
  • model：使用的模型（例如 “claude-3-5-sonnet-20241022”）
  • cost_usd：估計成本（美元）
  • duration_ms：請求持續時間（毫秒）
  • input_tokens：輸入權杖數量
  • output_tokens：輸出權杖數量
  • cache_read_tokens：從快取讀取的權杖數量
  • cache_creation_tokens：用於快取建立的權杖數量

​
API 錯誤事件

當對 Claude 的 API 請求失敗時記錄。

事件名稱：claude_code.api_error

屬性：

  • 所有標準屬性
  • event.name："api_error"
  • event.timestamp：ISO 8601 時間戳
  • model：使用的模型（例如 “claude-3-5-sonnet-20241022”）
  • error：錯誤訊息
  • status_code：HTTP 狀態碼（如果適用）
  • duration_ms：請求持續時間（毫秒）
  • attempt：嘗試次數（用於重試請求）

​
工具決策事件

當做出工具權限決策（接受/拒絕）時記錄。

事件名稱：claude_code.tool_decision

屬性：

  • 所有標準屬性
  • event.name："tool_decision"
  • event.timestamp：ISO 8601 時間戳
  • tool_name：工具名稱（例如 “Read”、“Edit”、“MultiEdit”、“Write”、“NotebookEdit” 等）
  • decision："accept" 或 "reject"
  • source：決策來源 - "config"、"user_permanent"、"user_temporary"、"user_abort" 或 "user_reject"

​
解讀指標和事件資料

Claude Code 匯出的指標提供了對使用模式和生產力的寶貴見解。以下是一些您可以建立的常見視覺化和分析：

​
使用監控

指標分析機會
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 分段。

​
事件分析

事件資料提供了對 Claude Code 互動的詳細見解：

工具使用模式：分析工具結果事件以識別：

  • 最常使用的工具
  • 工具成功率
  • 平均工具執行時間
  • 按工具類型的錯誤模式

效能監控：追蹤 API 請求持續時間和工具執行時間以識別效能瓶頸。

​
後端考量

您選擇的指標和日誌後端將決定您可以執行的分析類型：

​
對於指標：

  • 時間序列資料庫（例如 Prometheus）：速率計算、聚合指標
  • 列式儲存（例如 ClickHouse）：複雜查詢、唯一使用者分析
  • 全功能可觀測性平台（例如 Honeycomb、Datadog）：進階查詢、視覺化、警報

​
對於事件/日誌：

  • 日誌聚合系統（例如 Elasticsearch、Loki）：全文搜尋、日誌分析
  • 列式儲存（例如 ClickHouse）：結構化事件分析
  • 全功能可觀測性平台（例如 Honeycomb、Datadog）：指標和事件之間的關聯

對於需要每日/每週/每月活躍使用者（DAU/WAU/MAU）指標的組織，請考慮支援高效唯一值查詢的後端。

​
服務資訊

所有指標都匯出時包含：

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

​
安全性/隱私考量

  • 遙測是選擇性的，需要明確配置
  • 敏感資訊如 API 金鑰或檔案內容絕不會包含在指標或事件中
  • 使用者提示內容預設已編輯 - 僅記錄提示長度。要啟用使用者提示記錄，請設定 OTEL_LOG_USER_PROMPTS=1