監控

​

快速開始

# 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

​

管理員配置

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

​

配置詳情

​

常見配置變數

​

指標基數控制

​

動態標頭

​

設定配置

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

​

指令碼需求

#!/bin/bash
# 範例：多個標頭
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​

重新整理行為

​

多團隊組織支援

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

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

# ❌ 無效 - 包含空格
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"

​

配置範例

# 控制台除錯（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

​

可用的指標和事件

​

標準屬性

• prompt.id：UUID 將使用者提示與所有後續事件關聯到下一個提示。請參閱事件關聯屬性。
• workspace.host_paths：在桌面應用程式中選擇的主機工作區目錄，作為字串陣列

​

指標

​

指標詳情

​

工作階段計數器

• 所有標準屬性

​

程式碼行計數器

• 所有標準屬性
• type：（"added"、"removed"）

​

提取請求計數器

• 所有標準屬性

​

提交計數器

• 所有標準屬性

​

成本計數器

• 所有標準屬性
• model：模型識別碼（例如，“claude-sonnet-4-6”）

​

權杖計數器

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

​

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

• 所有標準屬性
• 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"。

​

活躍時間計數器

• 所有標準屬性
• type："user" 用於鍵盤互動，"cli" 用於工具執行和 AI 回應

​

事件

​

事件關聯屬性

​

使用者提示事件

• 所有標準屬性
• event.name："user_prompt"
• event.timestamp：ISO 8601 時間戳
• event.sequence：單調遞增計數器，用於排序工作階段內的事件
• prompt_length：提示的長度
• prompt：提示內容（預設為編輯，使用 OTEL_LOG_USER_PROMPTS=1 啟用）

​

工具結果事件

• 所有標準屬性
• 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 請求事件

• 所有標準屬性
• event.name："api_request"
• event.timestamp：ISO 8601 時間戳
• event.sequence：單調遞增計數器，用於排序工作階段內的事件
• model：使用的模型（例如，“claude-sonnet-4-6”）
• cost_usd：估計成本（美元）
• duration_ms：請求持續時間（毫秒）
• input_tokens：輸入權杖數
• output_tokens：輸出權杖數
• cache_read_tokens：從快取讀取的權杖數
• cache_creation_tokens：用於快取建立的權杖數
• speed："fast" 或 "normal"，指示是否啟用了快速模式

​

API 錯誤事件

• 所有標準屬性
• 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"，指示是否啟用了快速模式

​

工具決定事件

• 所有標準屬性
• 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"

​

解釋指標和事件資料

​

使用情況監控

​

成本監控

• 追蹤跨團隊或個人的使用趨勢
• 識別高使用量工作階段以進行最佳化

​

警報和分段

• 成本尖峰
• 異常的權杖消耗
• 來自特定使用者的高工作階段量

​

事件分析

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

​

後端考量

​

對於指標

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

​

對於事件/日誌

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

​

服務資訊

• 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 測量資源

​

安全性和隱私

• 遙測是選擇加入的，需要明確配置
• 原始檔案內容和程式碼片段不包含在指標或事件中。工具執行事件在 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