監控 - Anthropic

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 和 WSL：/etc/claude-code/managed-settings.json
Windows：C:\ProgramData\ClaudeCode\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_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_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`

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

動態標頭

對於需要動態驗證的企業環境，您可以配置腳本來動態產生標頭：

設定配置

新增到您的 .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)\"}"

重要限制

標頭僅在啟動時獲取，而非在執行時期間。 這是由於 OpenTelemetry 匯出器架構限制。對於需要頻繁權杖重新整理的情況，請使用 OpenTelemetry Collector 作為代理，它可以重新整理自己的標頭。

多團隊組織支援

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

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

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

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

OTEL_RESOURCE_ATTRIBUTES 的重要格式要求：OTEL_RESOURCE_ATTRIBUTES 環境變數遵循 W3C Baggage 規範，該規範有嚴格的格式要求：

不允許空格：值不能包含空格。例如，user.organizationName=My Company 是無效的
格式：必須是逗號分隔的 key=value 對：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"

注意：引用整個 key=value 對（例如 "key=value with spaces"）不受 OpenTelemetry 規範支援，會導致屬性前綴引號。

配置範例

# 控制台除錯（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.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-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 的時間（非閒置時間）。此指標在使用者互動期間遞增，例如輸入提示或接收回應。屬性：

所有標準屬性

事件

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 時間戳
tool_name：工具名稱
success："true" 或 "false"
duration_ms：執行時間（毫秒）
error：錯誤訊息（如果失敗）
decision："accept" 或 "reject"
source：決策來源 - "config"、"user_permanent"、"user_temporary"、"user_abort" 或 "user_reject"
tool_parameters：包含工具特定參數的 JSON 字串（可用時）
- 對於 Bash 工具：包含 bash_command、full_command、timeout、description、sandbox

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）指標的組織，請考慮支援高效唯一值查詢的後端。

服務資訊

所有指標和事件都使用以下資源屬性匯出：

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 等工具整合的生產力報告範本。

安全/隱私考量

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

開始使用

使用 Claude Code 建構

Claude 程式碼 SDK

部署

管理

配置

參考

資源

​快速開始

​管理員配置

​配置詳細資訊

​常見配置變數

​指標基數控制

​動態標頭

​設定配置

​腳本需求

​重要限制

​多團隊組織支援

​配置範例

​可用指標和事件

​標準屬性

​指標

​指標詳細資訊

​會話計數器

​程式碼行數計數器

​拉取請求計數器

​提交計數器

​成本計數器

​權杖計數器

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

​活動時間計數器

​事件

​使用者提示事件

​工具結果事件

​API 請求事件

​API 錯誤事件

​工具決策事件

​解釋指標和事件資料

​使用監控

​成本監控

​警報和分段

​事件分析

​後端考量

​對於指標：

​對於事件/日誌：

​服務資訊

​ROI 測量資源

​安全/隱私考量

快速開始

管理員配置

配置詳細資訊

常見配置變數

指標基數控制

動態標頭

設定配置

腳本需求

重要限制

多團隊組織支援

配置範例

可用指標和事件

標準屬性

指標

指標詳細資訊

會話計數器

程式碼行數計數器

拉取請求計數器

提交計數器

成本計數器

權杖計數器

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

活動時間計數器

事件

使用者提示事件

工具結果事件

API 請求事件

API 錯誤事件

工具決策事件

解釋指標和事件資料

使用監控

成本監控

警報和分段

事件分析

後端考量

對於指標：

對於事件/日誌：

服務資訊

ROI 測量資源

安全/隱私考量