詳細測試版追蹤下的內容屬性

這些屬性出現在以下跨度上，由以下閘門控制 命名屬性在詳細測試版追蹤之上需要的變數。長於內容限制（預設值 60 KB）的值會被截斷。

在詳細測試版追蹤下且設定 OTEL_LOG_USER_PROMPTS=1 時，Claude Code 也會發出 claude_code.system_prompt 事件，攜帶完整的系統提示詞，並在內容限制處截斷。它會在工作階段首次傳送每個不同的系統提示詞時到達，並在壓縮後再次到達。

動態標頭

對於需要動態驗證的企業環境，您可以設定指令碼以動態產生標頭。動態標頭僅適用於 http/protobuf 和 http/json 協議。使用 grpc 協議，Claude Code 僅使用靜態標頭變數 OTEL_EXPORTER_OTLP_HEADERS 及其每個信號的變體。

設定設定

新增至您的 .claude/settings.json，將路徑替換為您自己的指令碼：

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

該值可以是可執行檔的路徑，包括包含空格的路徑，或帶有引數的殼層命令列。在 Windows 上，該值始終透過殼層執行，因此在 JSON 值內引用包含空格的路徑。

指令碼需求

指令碼必須輸出有效的 JSON，其中包含代表 HTTP 標頭的字串鍵值對：

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

如果協助程式失敗或列印不符合這些需求的輸出，匯出會失敗，您的遙測後端在協助程式再次運作之前不會從工作階段接收任何內容。Claude Code 在以下位置報告失敗：

• 互動式工作階段中的警告通知，otelHeadersHelper failed; telemetry is not being exported，在協助程式首次失敗時每個工作階段顯示一次
• /status 輸出
• 偵錯日誌，當使用 --debug 執行或在工作階段中執行 /debug 後
• stderr，在使用 -p 啟動的非互動式工作階段中

重新整理行為

標頭協助程式指令碼在啟動時執行，之後定期執行以支援令牌重新整理。預設情況下，指令碼每 29 分鐘執行一次。使用 CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 環境變數自訂間隔。

多團隊組織支援

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

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

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

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

Claude Code 將這些值作為屬性附加到每個指標資料點和事件記錄，除了在 OTLP 資源區塊中傳送它們。因為大多數指標後端將資料點屬性公開為可查詢的標籤，您可以直接按自訂金鑰分組和篩選指標。除了 vcs.* 儲存庫屬性，自訂金鑰永遠不會覆蓋標準屬性，例如 user.id 或 session.id：當金鑰衝突時，Claude Code 會保留內建值。

每個自訂金鑰都會成為每個指標系列上的標籤，因此高基數值會增加指標後端中的儲存成本。若要僅在資源區塊中傳送自訂屬性並從資料點標籤中省略它們，請設定 OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false。請參閱指標基數控制。

範例設定

在執行 claude 之前設定這些環境變數。下面的每個案例都顯示完整的設定，每個變數都在常見設定變數下描述。若要確認設定生效，請在啟動工作階段後檢查您的後端是否有 claude_code.session.count 指標；快速入門涵蓋僅日誌驗證以及當沒有任何內容到達時要檢查的內容。

用於主控台偵錯，匯出間隔為 1 秒：

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

用於透過 gRPC 的 OTLP：

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，從 http://localhost:9464/metrics 抓取：

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

在自託管環境上，工作階段僅在執行器的預設容量為 1 時繫結連接埠 9464。在更高的容量下，執行器改為在其自己的 /metrics 端點上重新公開工作階段計數器和量表。

若要將指標傳送到多個匯出器：

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

雲端工作階段和 Claude Tag 的遙測

雲端工作階段（包括 Claude Tag 頻道工作階段）在雲端環境中執行，而不是在使用者的裝置上執行，因此裝置上的受管設定檔或 shell 設定檔不會設定其遙測。對於在 Anthropic 代管環境中的工作階段，本節涵蓋設定遙測變數的位置、如何使收集器可從環境存取，以及如何在匯出的資料中區分雲端和 Claude Tag 工作階段。

若要從這些工作階段匯出遙測，請使用與管理員設定範例相同的金鑰，在下列兩個位置之一設定 CLAUDE_CODE_ENABLE_TELEMETRY 和 OTEL_* 變數：

• 伺服器受管設定：將它們新增至組織的伺服器受管設定的 env 區塊。Claude Code 在伺服器受管設定適用的任何位置啟動時會擷取這些設定，包括使用者的機器和 Claude Tag 頻道工作階段以外的雲端工作階段。Claude Tag 工作階段不會接收伺服器受管設定，因此此路由不會設定它們。
• 環境的變數：將它們新增至雲端環境的環境變數，以僅設定在該環境中執行的工作階段。這是到達 Claude Tag 工作階段的路由。

任何使用環境的人都可以讀取其變數，因此不要在其中放置憑證，例如 OTEL_EXPORTER_OTLP_HEADERS 中的收集器 token。環境上的網路密鑰也無法幫助，因為 Claude Code 自己的遙測匯出是永遠不會取得密鑰的請求之一。如果收集器需要憑證，請改為透過伺服器受管設定設定整個匯出，因為當您在該處設定憑證時，Claude Code 會移除在受管設定外設定的端點變數。

在為雲端工作階段設定遙測時，請記住這些限制：

• 讓工作階段到達收集器：Claude Code 透過工作階段的網路傳送匯出，因此它是否到達 OTEL_EXPORTER_OTLP_ENDPOINT 中的主機取決於環境的網路存取層級。如果工作階段無法在您選擇的層級到達收集器的網域，請將網域新增至環境的允許清單，因為沒有伺服器受管設定會將網域新增至環境的網路允許清單。
• Claude Tag 頻道使用組織層級環境：頻道工作階段在組織層級環境中執行，而不是成員的個人環境，因此請在設定為組織預設或釘選到頻道的共用環境上進行允許清單和任何環境變數變更。
• Cowork 單獨設定：如表面涵蓋表所示，Cowork 工作階段不會接收伺服器受管設定，因此伺服器受管 env 區塊不會設定其遙測。

將遙測歸因於雲端工作階段

根據預設，來自雲端工作階段的指標和事件會帶有標準屬性，包括 session.id、ccr.session.id 和 organization.id，因此您可以按工作階段或組織篩選，無需額外設定。ccr.session.id 值是工作階段的 CLAUDE_CODE_REMOTE_SESSION_ID。若要將其轉換為工作階段的文字記錄 URL，請參閱將輸出連結回工作階段。

若要更詳細地歸因遙測，請使用這些選項：

• 識別 Claude Tag 工作階段：設定 OTEL_METRICS_INCLUDE_ENTRYPOINT=true，如指標基數控制下所述。指標隨後會帶有 app.entrypoint，其值對於 Claude Tag 工作階段為 claude-in-slack。
• 新增自訂屬性：在設定這些工作階段的其他 OTEL_* 變數的相同位置設定 OTEL_RESOURCE_ATTRIBUTES。如果您改為在環境的設定指令碼中 export 它，該值不會到達 Claude Code：設定指令碼是在 Claude Code 啟動前執行的單獨 Bash 指令碼，它匯出的變數會隨著它結束。

在 Claude Tag 頻道工作階段中，Claude 作為組織的共用身分而不是任何成員工作，因此不要依賴 user.* 屬性來識別誰標記了 Claude。

可用的指標與事件

標準屬性

所有指標與事件皆共用以下標準屬性：

在透過 /login 登入 Claude apps 閘道的工作階段中，CLI 會以經過身分驗證的身分標記匯出資料：user.id 為 IdP subject，user.email 為登入的電子郵件，而 user.groups 則以逗號分隔的字串承載 IdP 群組成員資格。每次匯出也會帶有 identity.source: gateway-oidc。閘道身分會最後套用，因此在這些工作階段中，透過 OTEL_RESOURCE_ATTRIBUTES 設定的 user.* 與 identity.* 鍵會被忽略。

關於透過閘道連線的 Claude Desktop 與 Cowork 工作階段上的身分屬性，請參閱閘道 telemetry 參考。

事件還會額外包含以下屬性。這些屬性永遠不會附加到指標上，因為它們會導致無上限的基數：

• prompt.id：將使用者提示詞與其後直到下一個提示詞之前的所有事件相關聯的 UUID。請參閱事件關聯屬性。
• workspace.host_paths：在桌面應用程式中選取的主機工作區目錄，以字串陣列表示
• workflow.run_id：執行識別碼，前綴為 wf_，出現在隸屬於 Workflow 工具執行的 agent 所發出的 API 與工具事件上。以單一 workflow.run_id 篩選事件，即可重建該次執行的 API 請求與工具結果。此識別碼涵蓋工作流程腳本所產生的 agent，以及這些 agent 再產生的任何 agent，例如 skill 呼叫。它與 Workflow 工具結果中回報的執行識別碼相符。在所有其他事件上皆不存在。需要 Claude Code v2.1.202 或更新版本
• workflow.name：工作流程名稱，即其腳本的 meta.name，與 workflow.run_id 一同發出。當執行的是未經修改的內建腳本時，內建工作流程名稱會原樣出現。使用者撰寫的名稱（包括內建腳本的編輯副本）會被替換為 custom，除非設定了 OTEL_LOG_TOOL_DETAILS=1。需要 Claude Code v2.1.202 或更新版本

儲存庫屬性

設定 OTEL_METRICS_INCLUDE_REPOSITORY=true，即可以工作階段儲存庫的身分標記指標與事件，讓共用的收集器能按儲存庫歸屬使用量。需要 Claude Code v2.1.269 或更新版本。

Claude Code 會在每個工作階段中從儲存庫的 origin 遠端衍生這些屬性一次。當儲存庫的 HTTPS 與 SSH 遠端指向相同的主機與相同的路徑時（如 GitHub、GitLab 與 Bitbucket Cloud），兩者會產生相同的值：

值會轉為小寫，且遠端 URL 中的憑證、查詢字串與片段永遠不會出現在其中。當工作階段沒有 origin 遠端、遠端不是 URL 形式，或唯一包含的儲存庫是您的家目錄時，這些屬性會被省略。

若要從雲端工作階段取得這些屬性，請在其雲端環境上設定遙測變數，包括 OTEL_METRICS_INCLUDE_REPOSITORY。同時也請在該環境的網路存取中允許您收集器的網域。

您在 OTEL_RESOURCE_ATTRIBUTES 中宣告的 vcs.* 鍵會取代該鍵的衍生值。若您宣告了 vcs.repository.url.full，Claude Code 將永遠不會讀取遠端，且只會回報您宣告的鍵。

若同一儲存庫的 HTTPS 與 SSH 複製回報不同的值（例如在自行託管的安裝中，HTTPS 複製 URL 帶有 SSH URL 所沒有的路徑前綴），請在 OTEL_RESOURCE_ATTRIBUTES 中宣告 vcs.repository.url.full，以及您希望回報的所有其他 vcs.* 鍵。如此一來，每個複製都會回報您宣告的身分。

這些屬性只會流向您自己的匯出器；Anthropic 的遙測會捨棄所有 vcs.* 鍵。

指標

Claude Code 會匯出以下指標。「單位」欄顯示附加到每個指標的 OpenTelemetry 單位字串；計數類指標不帶單位。

當 prometheus 是 OTEL_METRICS_EXPORTER 中列出的唯一匯出器時，Claude Code 會從匯出的指標中省略 USD、tokens 與 s 單位，使抓取結果保持為有效的 Prometheus 文字格式。指標名稱不會改變，而結合多個匯出器的設定（例如 otlp,prometheus）會保留單位。在 v2.1.216 之前，Prometheus 抓取結果包含僅適用於 OpenMetrics 的 # UNIT 行，部分抓取器會拒絕這些行。

指標詳細資訊

每個指標都包含上方列出的標準屬性。帶有額外情境特定屬性的指標會在下方註明。

工作階段計數器

在每個工作階段開始時遞增。

屬性：

• 所有標準屬性
• start_type：工作階段的啟動方式。為 "fresh"、"resume"、"continue" 或 "agents_view" 之一。"agents_view" 值代表 claude agents 儀表板程序，這是使用者啟動的本機 UI，而非對話工作階段。在您的儀表板中篩選此值，即可將 UI 程序啟動與對話工作階段區分開來。

程式碼行數計數器

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

屬性：

• 所有標準屬性
• type：（"added"、"removed"）
• model：進行變更之模型的模型識別碼（例如 "claude-sonnet-5"）

Pull request 計數器

當 Claude Code 透過 shell 命令或 MCP 工具建立 pull request 或 merge request 時遞增。

屬性：

• 所有標準屬性

提交計數器

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

屬性：

• 所有標準屬性

成本計數器

在每次 API 請求之後遞增。

agent.name、skill.name、plugin.name、mcp_server.name 與 mcp_tool.name 屬性預設都會將部分名稱遮蔽為 "custom" 或 "third-party" 預留值。若您設定了 OTEL_LOG_TOOL_DETAILS=1，它們會改為帶有實際名稱。在 v2.1.273 之前，即使設定了 OTEL_LOG_TOOL_DETAILS=1，成本與 token 計數器以及 api_request、api_error 與 api_refusal 事件仍帶有遮蔽後的值。

屬性：

• 所有標準屬性
• model：模型識別碼（例如 "claude-sonnet-5"）
• query_source：發出請求之子系統的類別。為 "main"、"subagent" 或 "auxiliary" 之一
• speed：當請求使用快速模式時為 "fast"。否則不存在
• effort：套用於請求的 effort 等級："low"、"medium"、"high"、"xhigh" 或 "max"。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。
• agent.name：發出請求的 subagent 類型。內建 agent 名稱以及來自官方市集外掛的 agent 會原樣出現。其他使用者定義的 agent 名稱會被替換為 "custom"。當請求並非由具名的 subagent 類型發出時不存在。
• skill.name：該請求作用中的 skill，由 Skill 工具或 / 命令設定，或由產生的 subagent 繼承。內建、隨附、使用者定義及官方市集外掛的 skill 名稱會原樣出現。第三方外掛的 skill 名稱會被替換為 "third-party"。當沒有作用中的 skill 時不存在。
• plugin.name：當作用中的 skill 或 subagent 由外掛提供時，為其所屬外掛。官方市集外掛名稱會原樣出現。第三方外掛名稱會被替換為 "third-party"。當 skill 與 subagent 皆沒有所屬外掛時不存在。
• marketplace.name：所屬外掛的安裝來源市集。即使設定了 OTEL_LOG_TOOL_DETAILS=1，也只會針對官方市集外掛發出。否則不存在。
• mcp_server.name：此請求所使用之工具結果所屬的 MCP 伺服器。內建、經由 claude.ai 代理及官方登錄檔的伺服器名稱會原樣出現。使用者設定的伺服器名稱會被替換為 "custom"。當請求未使用任何 MCP 工具結果時不存在。在 v2.1.222 之前，Claude Code 會在 MCP 工具呼叫之後的每個請求上設定此屬性，而不僅限於使用工具結果的請求，因此彙總此屬性的儀表板在您升級後會出現下降。
• mcp_tool.name：此請求所使用之結果所屬的 MCP 工具，其遮蔽與版本行為與 mcp_server.name 相同。當請求未使用任何 MCP 工具結果時不存在。

Token 計數器

在每次 API 請求之後遞增。

屬性：

• 所有標準屬性
• type：（"input"、"output"、"cacheRead"、"cacheCreation"）。"input" 類型不包含從提示詞快取讀取或寫入的 token，這些會計入 "cacheRead" 與 "cacheCreation"
• model：模型識別碼（例如 "claude-sonnet-5"）
• query_source：發出請求之子系統的類別。為 "main"、"subagent" 或 "auxiliary" 之一
• speed：當請求使用快速模式時為 "fast"。否則不存在
• effort：套用於請求的 effort 等級。詳細資訊請參閱成本計數器。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱成本計數器。

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

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

屬性：

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

活躍時間計數器

追蹤實際主動使用 Claude Code 所花費的時間，不包括閒置時間。此指標會在使用者互動期間（例如輸入與閱讀回應）以及 CLI 處理期間（例如工具執行與 AI 回應產生）遞增。

屬性：

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

事件

Claude Code 會透過 OpenTelemetry logs/events 匯出以下事件（當設定了 OTEL_LOGS_EXPORTER 時）：

事件關聯屬性

當使用者提交提示詞時，Claude Code 可能會進行多次 API 呼叫並執行數個工具。prompt.id 屬性可讓您將所有這些事件連結回觸發它們的單一提示詞。

若要追蹤由單一提示詞觸發的所有活動，請以特定的 prompt.id 值篩選您的事件。這會傳回處理該提示詞期間發生的 user_prompt 事件、任何 api_request 事件以及任何 tool_result 事件。

event.sequence 在每次 Claude Code 程序啟動時從 0 開始，並在該程序的整個生命週期中遞增。它在 /clear（會指派新的 session.id）之後仍會持續計數。若您在不分叉的情況下繼續工作階段，工作階段會保留其 session.id，但其 event.sequence 值會取自繼續該工作階段的程序，因此在同一工作階段中，較晚的事件可能帶有比較早事件更低的值，或重複某個值。若要排序工作階段的事件，請依 event.timestamp 排序，並使用 event.sequence 排序具有相同時間戳記的事件。

為了進行訊息層級的重建，每個事件類別都帶有一個與工作階段逐字稿中欄位相符的鍵。逐字稿項目格式是 Claude Code 內部使用的，且會在版本之間變更，因此依這些欄位進行聯結的管線可能會在任何版本發行時中斷；請將這些聯結視為特定版本的行為，而非穩定的約定：

• user_prompt、assistant_response 與 api_response_body 上的 message.uuid
• API 事件上的 request_id，在逐字稿的助理項目中保存為 requestId
• tool_result 與 tool_decision 事件上的 tool_use_id

使用者提示詞事件

在提交提示詞時記錄，包括 Claude Code 自行開始的回合。

事件名稱：claude_code.user_prompt

屬性：

• 所有標準屬性
• event.name："user_prompt"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• prompt_length：提示詞長度
• prompt：提示詞內容。預設會遮蔽。設定 OTEL_LOG_USER_PROMPTS=1 即可包含
• prompt_text：與 prompt 相同的值，並在相同條件下遮蔽。將帶點的屬性名稱儲存為巢狀物件的後端，會將 prompt.id 讀取為名為 prompt 之物件內的 id，因而可能遺失提示詞字串。在這種情況下，請改為讀取 prompt_text。需要 Claude Code v2.1.287 或更新版本
• message.uuid：產生之使用者訊息的 UUID，與保存的逐字稿項目相符。在命令分派上不存在，因為命令分派可能產生零或多則訊息。需要 Claude Code v2.1.214 或更新版本
• command_name：當提示詞呼叫命令時的命令名稱。內建與隨附的命令名稱（例如 compact 或 debug）會原樣發出；別名（例如 reset）會依輸入的形式發出，而非標準名稱。自訂、外掛與 MCP 命令名稱會收斂為 custom 或 mcp，除非設定了 OTEL_LOG_TOOL_DETAILS=1
• command_source：存在時為命令的來源：builtin、custom 或 mcp。外掛提供的命令會回報為 custom

助理回應事件

在每次從模型傳回文字內容的 API 請求之後記錄。僅包含回應的文字區塊；思考區塊與工具使用區塊會被排除。

事件名稱：claude_code.assistant_response

屬性：

• 所有標準屬性
• event.name："assistant_response"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• response_length：回應文字的長度（字元數）
• response：回應文字，在內容上限（預設 60 KB）處截斷。預設會遮蔽為 <REDACTED>。設定 OTEL_LOG_ASSISTANT_RESPONSES=1 即可包含。當 OTEL_LOG_ASSISTANT_RESPONSES 未設定時，改由 OTEL_LOG_USER_PROMPTS 控制，因此若要在開啟提示詞日誌記錄的同時保持回應遮蔽，請設定 OTEL_LOG_ASSISTANT_RESPONSES=0
• model：模型識別碼（例如 "claude-sonnet-5"）
• request_id：API 請求 ID，說明請參閱事件關聯屬性
• message.uuid：回應之最後一筆逐字稿項目的 UUID。API 回應會依每個內容區塊保存為一筆逐字稿項目；此為最後一筆，下一個回合的 parentUuid 會從此項目串接。需要 Claude Code v2.1.214 或更新版本
• query_source：發出請求的子系統，例如 "repl_main_thread"、"compact" 或 subagent 名稱

工具結果事件

在工具完成執行時記錄。若工具呼叫遭拒絕則不會發出；關於拒絕，請參閱工具決定事件。

事件名稱：claude_code.tool_result

屬性：

• 所有標準屬性
• event.name："tool_result"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• tool_name：工具名稱
• tool_use_id：此次工具呼叫的唯一識別碼。與傳遞給 hook 的 tool_use_id 相符，可讓 OTel 事件與 hook 擷取的資料相互關聯。
• success："true" 或 "false"
• duration_ms：執行時間（毫秒）
• error_type：工具失敗時的錯誤類別字串，例如 "Error:ENOENT" 或 "ShellError"
• error（當 OTEL_LOG_TOOL_DETAILS=1 時）：工具失敗時的完整錯誤訊息
• decision_type：一律為 "accept"，因為此事件只會在工具執行後發出。遭拒絕的呼叫不會產生工具結果
• decision_source：權限決定的來源。為 "config"、"hook"、"user_permanent" 或 "user_temporary" 之一。各值的意義請參閱工具決定事件。僅適用於拒絕的來源 "user_abort" 與 "user_reject" 永遠不會出現在此事件上。
• tool_input_size_bytes：JSON 序列化後之工具輸入的大小（位元組）
• tool_result_size_bytes：工具結果的大小（位元組）
• mcp_server_scope：MCP 伺服器範圍識別碼（適用於 MCP 工具）
• vcs.ref.head.revision、vcs.ref.head.name、vcs.ref.head.type（當 OTEL_LOG_TOOL_DETAILS=1 時）：由 Bash 或 PowerShell 工具執行之成功 git commit 的提交身分。vcs.ref.head.revision 為提交 SHA，vcs.ref.head.name 為提交所在的分支，而 vcs.ref.head.type 為 branch。當提交是在 detached HEAD 上進行時，名稱與類型會被省略。需要 Claude Code v2.1.269 或更新版本
• tool_parameters（當 OTEL_LOG_TOOL_DETAILS=1 時）：包含工具特定參數的 JSON 字串。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，即使旗標關閉也會包含 mcp_server_name/mcp_tool_name 配對，這與工具決定事件中由主機定義的例外相同，需要 Claude Code v2.1.214 或更新版本。參數依工具而異：
  • 對於 Bash 工具：包含 bash_command、full_command、timeout、description 與 dangerouslyDisableSandbox，以及當 git commit 命令成功時的 git_commit_id 與 git_branch。當提交是工作階段工作目錄的 HEAD 時，git_commit_id 為完整的提交 SHA，否則為 git 的縮寫 SHA。git_branch 為提交所在的分支，在 detached HEAD 上會被省略
  • 對於桌面應用程式的工作區 Bash 工具（其 tool_name 也回報為 Bash）：僅包含 bash_command、full_command 與 timeout
  • 對於 MCP 工具：包含 mcp_server_name、mcp_tool_name
  • 對於 Skill 工具：包含 skill_name
  • 對於 Agent 工具或舊版 Task 工具：包含 subagent_type
• tool_input（當 OTEL_LOG_TOOL_DETAILS=1 時）：JSON 序列化後的工具引數。超過 512 個字元的個別值會被截斷，且完整 payload 的上限約為 4 K 個字元。適用於所有工具，包括 MCP 工具。

API 請求事件

針對每個傳送給 Claude 的 API 請求記錄。

事件名稱：claude_code.api_request

屬性：

• 所有標準屬性
• event.name："api_request"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• model：使用的模型（例如 "claude-sonnet-5"）
• cost_usd：預估成本（USD）
• cost_usd_micros：以百萬分之一美元為單位的預估成本，以整數發出
• duration_ms：請求持續時間（毫秒）
• input_tokens：輸入 token 數量，不包括從提示詞快取讀取或寫入的 token
• output_tokens：輸出 token 數量
• cache_read_tokens：從快取讀取的 token 數量
• cache_creation_tokens：用於建立快取的 token 數量
• request_id：API 請求 ID，例如 "req_011..."，說明請參閱事件關聯屬性。
• client_request_id：用戶端產生的 UUID，作為 x-client-request-id 請求標頭傳送；其出現時機請參閱事件關聯屬性表格。需要 Claude Code v2.1.214 或更新版本
• speed："fast" 或 "normal"，表示快速模式是否啟用
• query_source：發出請求的子系統，例如 "repl_main_thread"、"compact" 或 subagent 名稱
• effort：套用於請求的 effort 等級："low"、"medium"、"high"、"xhigh" 或 "max"。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱成本計數器。

API 錯誤事件

當傳送給 Claude 的 API 請求失敗時記錄。

事件名稱：claude_code.api_error

屬性：

• 所有標準屬性
• event.name："api_error"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• model：使用的模型（例如 "claude-sonnet-5"）
• error：錯誤訊息
• status_code：以數字表示的 HTTP 狀態碼。對於非 HTTP 錯誤（例如連線失敗）不存在。
• duration_ms：請求持續時間（毫秒）
• attempt：已進行的嘗試次數，包括初始請求。偵測重試耗盡說明計數何時會重新開始
• request_id：API 請求 ID，例如 "req_011..."，說明請參閱事件關聯屬性。
• client_request_id：用戶端產生的 UUID，作為 x-client-request-id 請求標頭傳送。即使逾時或連線錯誤等失敗從未產生伺服器 request_id，此值仍然可用；其出現時機請參閱事件關聯屬性表格。需要 Claude Code v2.1.214 或更新版本
• speed："fast" 或 "normal"，表示快速模式是否啟用
• query_source：發出請求的子系統，例如 "repl_main_thread"、"compact" 或 subagent 名稱
• effort：套用於請求的 effort 等級。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱成本計數器。

API 拒絕事件

當 API 請求傳回 stop_reason: "refusal" 時記錄。拒絕會出現在成功的回應串流中，而非以 HTTP 錯誤的形式出現，因此 api_error 事件不會因拒絕而觸發。此事件可讓您追蹤拒絕頻率，並依與 api_request 及 api_error 相同的屬性將拒絕分組。

事件名稱：claude_code.api_refusal

屬性：

• 所有標準屬性
• event.name："api_refusal"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• model：請求中的模型識別碼
• request_id：API 請求 ID，例如 "req_011..."，說明請參閱事件關聯屬性。
• query_source：發出請求的子系統，例如 "repl_main_thread"、"compact" 或 subagent 名稱。定義請參閱 api_request。
• speed：當快速模式啟用時為 "fast"，否則為 "normal"
• attempt：重試嘗試的編號。第一次嘗試為 1。
• effort：套用於請求的 effort 等級。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。
• server_fallback_hop：當 API 的伺服器端模型備援已在不同的模型上重試此拒絕，因此使用者並未看到此特定拒絕時為 true。當請求以拒絕結束時為 false。當備援模型也拒絕時，單一回合可能會同時發出一個 true 的跳轉事件以及之後一個 false 的最終事件。
• has_category：當 API 回應帶有值為 "cyber"、"bio"、"frontier_llm" 或 "reasoning_extraction" 的 stop_details.category 時為 true。當回應未帶有類別或帶有該集合以外的值時為 false。當 server_fallback_hop 為 true 時不存在，因為跳轉區塊不帶有 stop_details。
• has_explanation：當 API 回應帶有 stop_details.explanation 時為 true，否則為 false。當 server_fallback_hop 為 true 時不存在。
• category：API 回應中的 stop_details.category 值。為 "cyber"、"bio"、"frontier_llm" 或 "reasoning_extraction" 之一。僅在設定了 OTEL_LOG_TOOL_DETAILS=1 且 has_category 為 true 時存在。
• agent.name、skill.name、plugin.name、marketplace.name、mcp_server.name、mcp_tool.name：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱成本計數器。

API 請求主體事件

當設定了 OTEL_LOG_RAW_API_BODIES 時，針對每次 API 請求嘗試記錄。每次嘗試發出一個事件，因此以調整後參數進行的重試各自會產生自己的事件。

事件名稱：claude_code.api_request_body

屬性：

• 所有標準屬性
• event.name："api_request_body"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• body：JSON 序列化後的 Messages API 請求參數，例如系統提示詞、訊息與工具，在內容上限（預設 60 KB）處截斷。先前助理回合中的延伸思考內容會被遮蔽。僅在內嵌模式（OTEL_LOG_RAW_API_BODIES=1）下發出。
• body_ref：指向包含未截斷主體之 <dir>/<uuid>.request.json 檔案的絕對路徑。僅在檔案模式（OTEL_LOG_RAW_API_BODIES=file:<dir>）下發出。
• body_length：未截斷的主體長度。當 OTEL_LOG_RAW_API_BODIES=file:<dir> 時為 UTF-8 位元組，當 =1 時為 UTF-16 程式碼單元
• body_truncated：發生內嵌截斷時為 "true"。在檔案模式下以及未發生截斷時不存在。
• model：請求參數中的模型識別碼
• query_source：發出請求的子系統（例如 "compact"）
• request_body_id：識別此嘗試之請求主體的 UUID。成功之嘗試的 api_response_body 事件帶有相同的值，因此您可以將回應與產生它的確切請求配對。需要 Claude Code v2.1.274 或更新版本

API 回應主體事件

當設定了 OTEL_LOG_RAW_API_BODIES 時，針對每個成功的 API 回應記錄。

在檔案模式（OTEL_LOG_RAW_API_BODIES=file:<dir>）下，Claude Code 也會針對每個成功的回應，將一行 JSON 附加到 <dir>/index.jsonl，其欄位為 timestamp、session_id、query_source、model、request_id、message_id、message_uuid、request_file 與 response_file。讀取此檔案即可找出特定逐字稿訊息背後的請求與回應檔案，而無需查詢您的遙測後端。索引檔案需要 Claude Code v2.1.274 或更新版本。

事件名稱：claude_code.api_response_body

屬性：

• 所有標準屬性
• event.name："api_response_body"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• body：JSON 序列化後的 Messages API 回應，包括 id、內容區塊、使用量與停止原因，在內容上限（預設 60 KB）處截斷。延伸思考內容會被遮蔽。僅在內嵌模式（OTEL_LOG_RAW_API_BODIES=1）下發出。
• body_ref：指向包含未截斷主體之 <dir>/<request_id>.response.json 檔案的絕對路徑。僅在檔案模式（OTEL_LOG_RAW_API_BODIES=file:<dir>）下發出。
• body_length：未截斷的主體長度。當 OTEL_LOG_RAW_API_BODIES=file:<dir> 時為 UTF-8 位元組，當 =1 時為 UTF-16 程式碼單元
• body_truncated：發生內嵌截斷時為 "true"。在檔案模式下以及未發生截斷時不存在。
• model：模型識別碼
• query_source：發出請求的子系統
• request_id：API 請求 ID，例如 "req_011..."，說明請參閱事件關聯屬性。
• request_body_id：此回應所回覆之 api_request_body 事件的 request_body_id。需要 Claude Code v2.1.274 或更新版本
• message.id：API 指派給回應的訊息 ID，即回應主體的 id 欄位。需要 Claude Code v2.1.274 或更新版本
• message.uuid：回應之最後一筆逐字稿項目的 UUID。與 request_body_id 搭配，可將逐字稿訊息連結到其背後的請求與回應主體。需要 Claude Code v2.1.274 或更新版本

工具決定事件

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

事件名稱：claude_code.tool_decision

屬性：

• 所有標準屬性
• event.name："tool_decision"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• tool_name：工具名稱（例如 "Read"、"Edit"、"Write"、"NotebookEdit"）
• tool_use_id：此次工具呼叫的唯一識別碼。與傳遞給 hook 的 tool_use_id 相符，可讓 OTel 事件與 hook 擷取的資料相互關聯。
• decision："accept" 或 "reject"
• tool_source：一律存在。工具的來源，為 CLI 定義之值的封閉集合。需要 Claude Code v2.1.214 或更新版本
  • "builtin"：CLI 本身的工具
  • "mcp"：一般 MCP 伺服器
  • "sdk_host_builtin_mcp"：內建於 Claude Desktop 本身的處理程序內伺服器，位於 Claude Desktop 擁有的工作階段中。當 Claude Desktop 從其自身的進入點 claude-desktop、claude-desktop-3p 或 local-agent 之一啟動工作階段，且該工作階段不是巢狀子工作階段時，Claude Desktop 即擁有該工作階段；巢狀工作階段（包括 Claude Code 本身產生的工作階段）會將這些伺服器回報為 "mcp"
• source：決定的來源：
  • "config"：未經提示而自動決定，依據為專案設定、使用者個人設定中的允許或拒絕規則、企業受管政策、--allowedTools 或 --disallowedTools 旗標、作用中的權限模式、同一互動式 CLI 工作階段中先前提示所給予的工作階段範圍授權，或因為該工具本身即為安全。此事件不會指出是哪一個來源相符。當權限提示請求本身失敗時，Claude Code 也會回報 "config"，例如 Agent SDK 的 canUseTool 回呼或 --permission-prompt-tool 工具傳回無效結果時，或在請求等待期間輸入串流關閉時。在 v2.1.216 之前，Claude Code 會將這些失敗回報為 "user_reject"。
  • "hook"：PreToolUse 或 PermissionRequest hook 傳回了此決定。
  • "user_permanent"：當使用者在權限提示中選擇「Yes, and don't ask again for ...」時發出，這會將允許規則儲存到其個人設定中。在互動式 CLI 中，僅針對該選擇本身發出；之後符合已儲存規則的呼叫會改為發出 "config"。在 Agent SDK 或非互動式 -p 工作階段中，初始選擇與之後的規則比對都會發出 "user_permanent"。視為接受。
  • "user_temporary"：當使用者在權限提示中選擇「Yes」進行一次性核准，或在檔案編輯或讀取提示中選擇授予工作階段剩餘時間存取權的選項時發出。在互動式 CLI 中，僅針對該選擇本身發出；之後因該工作階段範圍授權而允許的呼叫會改為發出 "config"。在 Agent SDK 或非互動式 -p 工作階段中，該選擇與之後的比對都會發出 "user_temporary"。視為接受。
  • "user_abort"：當使用者未回答即關閉權限提示時發出。在 Agent SDK 與非互動式 -p 工作階段中，這包括在 canUseTool 或 --permission-prompt-tool 權限請求等待期間中斷回合；在 v2.1.216 之前，Claude Code 會將該中斷回報為 "user_reject"。視為拒絕。
  • "user_reject"：當使用者在提示時選擇「No」時發出。在互動式 CLI 中，僅針對該選擇本身發出；符合使用者個人設定中拒絕規則的呼叫會改為發出 "config"。在 Agent SDK 或非互動式 -p 工作階段中，符合個人設定中拒絕規則的呼叫會發出 "user_reject"。視為拒絕。
• tool_parameters（當 OTEL_LOG_TOOL_DETAILS=1 時）：包含工具特定參數的 JSON 字串。格式與工具結果事件相同，但不含執行後的欄位，例如 git_commit_id。若權限決定透過 updatedInput 改寫了工具輸入，已接受呼叫的值可能與 tool_result 不同。當 decision 為 "reject" 時，可使用此屬性查看哪個命令遭到拒絕。
  • 對於 "sdk_host_builtin_mcp" 工具：即使 OTEL_LOG_TOOL_DETAILS 關閉，也會包含 mcp_server_name 與 mcp_tool_name，因為這些名稱是由主機應用程式定義的；若沒有它們，在預設串流上將無法歸屬對這些內建伺服器之一的遭拒呼叫。對於使用者設定的 MCP 伺服器，事件的 tool_name 一律為字面值 "mcp_tool"，而伺服器與工具名稱僅在旗標開啟時出現在 tool_parameters 中；引數內容在任何情況下都需要該旗標。需要 Claude Code v2.1.214 或更新版本
  • 對於 Bash 工具：包含 bash_command、full_command、timeout、description、dangerouslyDisableSandbox。桌面應用程式的工作區 bash 工具也會將 tool_name 回報為 Bash，但僅包含 bash_command、full_command 與 timeout
  • 對於 MCP 工具：包含 mcp_server_name、mcp_tool_name
  • 對於 Skill 工具：包含 skill_name
  • 對於 Agent 工具或舊版 Task 工具：包含 subagent_type

權限模式變更事件

在權限模式變更時記錄，例如透過 Shift+Tab 循環切換、退出 plan mode，或自動模式閘門檢查。

事件名稱：claude_code.permission_mode_changed

屬性：

• 所有標準屬性
• event.name："permission_mode_changed"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• from_mode：先前的權限模式，例如 "default"、"plan"、"acceptEdits"、"auto" 或 "bypassPermissions"
• to_mode：新的權限模式
• trigger：造成變更的原因。為 "shift_tab"、"exit_plan_mode"、"auto_gate_denied" 或 "auto_opt_in" 之一。當轉換源自 SDK 或 bridge 時不存在

身分驗證事件

在 /login 或 /logout 完成時記錄。

事件名稱：claude_code.auth

屬性：

• 所有標準屬性
• event.name："auth"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• action："login" 或 "logout"
• success："true" 或 "false"
• auth_method：身分驗證方式，例如 "oauth"
• error_category：動作失敗時的錯誤種類分類。永遠不會包含原始錯誤訊息
• status_code：當動作因 HTTP 錯誤而失敗時，以字串表示的 HTTP 狀態碼

MCP 伺服器連線事件

在 MCP 伺服器連線、中斷連線或連線失敗時記錄。

事件名稱：claude_code.mcp_server_connection

屬性：

• 所有標準屬性
• event.name："mcp_server_connection"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• status："connected"、"failed" 或 "disconnected"
• transport_type：伺服器傳輸方式，例如 "stdio"、"sse" 或 "http"
• server_scope：伺服器設定所在的範圍，例如 "user"、"project" 或 "local"
• duration_ms：連線嘗試的持續時間（毫秒）
• error_code：連線失敗時的錯誤代碼
• is_plugin：當伺服器由外掛提供時為 true，否則為 false
• plugin_id_hash（當 is_plugin 為 true 時）：外掛名稱與市集的穩定雜湊值，可在不暴露名稱的情況下依外掛將事件分組。Claude Code 的計算方式如外掛載入事件中所述
• plugin.name（當 is_plugin 為 true 時）：提供該伺服器之外掛的名稱。對於第三方外掛，除非設定了 OTEL_LOG_TOOL_DETAILS=1，否則此值為字面字串 "third-party"；這可預設防止第三方外掛名稱出現在日誌中。來自 Anthropic 官方來源的外掛一律以名稱識別。plugin_id_hash 與 plugin.name 屬性會流向您自己的監控後端，不會傳送給 Anthropic
• server_name（當 OTEL_LOG_TOOL_DETAILS=1 時）：設定的伺服器名稱
• error（當 OTEL_LOG_TOOL_DETAILS=1 時）：連線失敗時的完整錯誤訊息

內部錯誤事件

當 Claude Code 捕捉到非預期的內部錯誤時記錄。僅記錄錯誤類別名稱與 errno 風格的代碼。永遠不會包含錯誤訊息與堆疊追蹤。在搭配 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 執行時，或設定了 DISABLE_ERROR_REPORTING 時，不會發出此事件。

事件名稱：claude_code.internal_error

屬性：

• 所有標準屬性
• event.name："internal_error"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• error_name：錯誤類別名稱，例如 "TypeError" 或 "SyntaxError"
• error_code：錯誤上存在時的 Node.js errno 代碼，例如 "ENOENT"

外掛安裝事件

在外掛完成安裝時記錄，涵蓋 claude plugin install CLI 命令與互動式 /plugin UI。

事件名稱：claude_code.plugin_installed

屬性：

• 所有標準屬性
• event.name："plugin_installed"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• marketplace.is_official：若市集為 Anthropic 官方市集則為 "true"，否則為 "false"
• install.trigger："cli" 或 "ui"
• plugin.name：已安裝外掛的名稱。對於第三方市集，僅在 OTEL_LOG_TOOL_DETAILS=1 時包含
• plugin.version：市集項目中宣告的外掛版本。對於第三方市集，僅在 OTEL_LOG_TOOL_DETAILS=1 時包含
• marketplace.name：外掛的安裝來源市集。對於第三方市集，僅在 OTEL_LOG_TOOL_DETAILS=1 時包含

外掛載入事件

在工作階段開始時，針對每個已啟用的外掛記錄一次。可使用此事件盤點整個裝置群中作用中的外掛，作為記錄安裝動作本身之 plugin_installed 的補充。

事件名稱：claude_code.plugin_loaded

屬性：

• 所有標準屬性
• event.name："plugin_loaded"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• plugin.name：外掛名稱。對於官方市集與內建套件以外的外掛，除非設定了 OTEL_LOG_TOOL_DETAILS=1，否則此值為 "third-party"
• marketplace.name：外掛的安裝來源市集（已知時）。在與 plugin.name 相同的條件下遮蔽為 "third-party"
• plugin.version：外掛資訊清單中的版本。僅在名稱未遮蔽且資訊清單宣告了版本時包含
• plugin.scope：外掛的來源類別："official"、"community"、"org"、"user-local" 或 "default-bundle"
• enabled_via：外掛被啟用的方式："default-enable"、"org-policy"、"admin-install"、"seed-mount" 或 "user-install"。"admin-install" 值表示該外掛在 Organization settings > Plugins & skills 中被設定為您組織的必要或自動安裝外掛。在 v2.1.246 之前，Claude Code 會將這些外掛回報為 "user-install" 或 "seed-mount"
• plugin_id_hash：外掛名稱與市集的確定性雜湊值，僅傳送給您設定的匯出器。可讓您在不記錄名稱的情況下，計算整個裝置群中載入的不同第三方外掛數量。對於從 claude.ai 同步的外掛，Claude Code 會以 claude.ai 為該外掛回報的市集名稱（否則為 synced）與外掛名稱一起計算雜湊。在 v2.1.246 之前，Claude Code 未在雜湊中使用 claude.ai 回報的市集名稱
• has_hooks：外掛是否提供 hook
• has_mcp：外掛是否提供 MCP 伺服器
• host_owned_mcp：當 SDK 主機管理此外掛的 MCP 連線，且 Claude Code 略過讀取外掛的 MCP 伺服器設定時為 true，否則為 false
• skill_path_count：外掛宣告的 skill 目錄數量
• command_path_count：外掛宣告的命令目錄數量
• agent_path_count：外掛宣告的 agent 目錄數量
• safe_mode：當工作階段以 --safe-mode 啟動時為 "true"，否則為 "false"。在安全模式下，此事件僅回報已設定的清單；外掛的命令、skill、hook 與 MCP 伺服器不會載入。需要 Claude Code v2.1.169 或更新版本

Skill 啟用事件

在 skill 被呼叫時記錄，無論是 Claude 透過 Skill 工具呼叫，或是您以 / 命令執行。

事件名稱：claude_code.skill_activated

屬性：

• 所有標準屬性
• event.name："skill_activated"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• skill.name：skill 的名稱。對於使用者定義與第三方外掛的 skill，除非設定了 OTEL_LOG_TOOL_DETAILS=1，否則此值為預留值 "custom_skill"
• invocation_trigger：skill 的觸發方式（"user-slash"、"claude-proactive" 或 "nested-skill"）
• skill.source：skill 的載入來源（例如 "bundled"、"userSettings"、"projectSettings"、"plugin"）
• skill.kind：當 skill 為工作流程 skill 時為 "workflow"。否則不存在
• plugin.name（當 OTEL_LOG_TOOL_DETAILS=1 或外掛來自官方市集時）：當 skill 由外掛提供時，為其所屬外掛的名稱
• marketplace.name（當 OTEL_LOG_TOOL_DETAILS=1 或外掛來自官方市集時）：當 skill 由外掛提供時，為所屬外掛的安裝來源市集

@ 提及事件

當 Claude Code 解析提示詞中的 @ 提及時記錄。並非每個提及都會發出事件：提早結束的路徑（例如權限拒絕、檔案過大、PDF 參考附件與目錄列出失敗）會直接返回而不記錄。

每次 Claude Code 讀取提示詞時，最多會記錄 100 個 mention_type 為 "agent" 的事件，以及 100 個為 "mcp_resource" 的事件。超過任一上限的提及仍會被解析，但不會發出事件。

事件名稱：claude_code.at_mention

屬性：

• 所有標準屬性
• event.name："at_mention"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• mention_type：提及的類型（"file"、"directory"、"agent"、"mcp_resource"、"peer"）。"peer" 值表示您提及了您的其他 Claude Code 工作階段之一。需要 Claude Code v2.1.232 或更新版本
• success：提及是否成功解析（"true" 或 "false"）

API 重試用盡事件

當 API 請求在多次嘗試後失敗時記錄一次。與最終的 api_error 事件一同發出。

事件名稱：claude_code.api_retries_exhausted

屬性：

• 所有標準屬性
• event.name："api_retries_exhausted"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• model：使用的模型
• error：最終錯誤訊息
• status_code：以數字表示的 HTTP 狀態碼。對於非 HTTP 錯誤不存在。
• total_attempts：嘗試的總次數
• total_retry_duration_ms：所有嘗試的總實際經過時間
• speed："fast" 或 "normal"

Hook 註冊事件

在工作階段開始時，針對每個已設定的 hook 記錄一次。可使用此事件盤點整個裝置群中作用中的 hook，作為每次執行之 hook_execution_start 與 hook_execution_complete 事件的補充。

事件名稱：claude_code.hook_registered

屬性：

• 所有標準屬性
• event.name："hook_registered"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• hook_event：hook 事件類型，例如 "PreToolUse" 或 "PostToolUse"
• hook_type：hook 實作類型："command"、"prompt"、"mcp_tool"、"http" 或 "agent"
• hook_source：hook 的定義位置："userSettings"、"projectSettings"、"localSettings"、"flagSettings"、"policySettings" 或 "pluginHook"
• safe_mode：當工作階段以 --safe-mode 啟動時為 "true"，否則為 "false"。需要 Claude Code v2.1.169 或更新版本
• hook_matcher（當 OTEL_LOG_TOOL_DETAILS=1 時）：hook 設定中的 matcher 字串（有設定時）
• plugin.name（當 hook_source 為 "pluginHook" 時）：提供該 hook 之外掛的名稱。對於官方市集與內建套件以外的外掛，除非設定了 OTEL_LOG_TOOL_DETAILS=1，否則此值為 "third-party"
• plugin_id_hash（當 hook_source 為 "pluginHook" 時）：外掛名稱與市集的確定性雜湊值，僅傳送給您設定的匯出器。可讓您在不記錄名稱的情況下計算提供 hook 的不同外掛數量。Claude Code 的計算方式如外掛載入事件中所述

Hook 執行開始事件

當一個或多個 hook 開始針對某個 hook 事件執行時記錄。

事件名稱：claude_code.hook_execution_start

屬性：

• 所有標準屬性
• event.name："hook_execution_start"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• hook_event：Hook 事件類型，例如 "PreToolUse" 或 "PostToolUse"
• hook_name：包含 matcher 的完整 hook 名稱，例如 "PreToolUse:Write"
• num_hooks：相符的 hook 命令數量
• managed_only：當僅允許受管政策 hook 時為 "true"
• hook_source："policySettings" 或 "merged"
• safe_mode：當工作階段以 --safe-mode 啟動時為 "true"，否則為 "false"。需要 Claude Code v2.1.169 或更新版本
• hook_definitions：JSON 序列化後的 hook 設定。僅在同時啟用詳細 beta 追蹤與 OTEL_LOG_TOOL_DETAILS=1 時包含

Hook 執行完成事件

當某個 hook 事件的所有 hook 都已完成時記錄。

事件名稱：claude_code.hook_execution_complete

屬性：

• 所有標準屬性
• event.name："hook_execution_complete"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• hook_event：Hook 事件類型
• hook_name：包含 matcher 的完整 hook 名稱
• num_hooks：相符的 hook 命令數量
• num_success：成功完成的數量
• num_blocking：傳回阻擋決定的數量
• num_non_blocking_error：失敗但未阻擋的數量
• num_cancelled：完成前被取消的數量
• total_duration_ms：所有相符 hook 的實際經過時間
• stdout_chars：成功之相符 hook 的 stdout 總字元數。需要 Claude Code v2.1.280 或更新版本
• additional_context_chars：相符 hook 傳回之 additionalContext 的總字元數。需要 Claude Code v2.1.280 或更新版本
• system_message_chars：相符 hook 傳回之 systemMessage 的總字元數。需要 Claude Code v2.1.280 或更新版本
• initial_user_message_chars：相符 hook 傳回之 initialUserMessage 的總字元數。需要 Claude Code v2.1.280 或更新版本
• num_outputs_persisted：超過 10,000 字元上限而由 Claude Code 儲存至檔案的 hook 輸出數量。需要 Claude Code v2.1.280 或更新版本
• managed_only：當僅允許受管政策 hook 時為 "true"
• hook_source："policySettings" 或 "merged"
• safe_mode：當工作階段以 --safe-mode 啟動時為 "true"，否則為 "false"。需要 Claude Code v2.1.169 或更新版本
• hook_definitions：JSON 序列化後的 hook 設定。僅在同時啟用詳細 beta 追蹤與 OTEL_LOG_TOOL_DETAILS=1 時包含

Hook 外掛指標事件

當官方市集外掛的 hook 發出每次呼叫的指標時記錄。只有從 Anthropic 官方市集安裝的外掛才能發出這些指標。第三方市集外掛與使用者設定的 hook 不會發出此事件。可使用此事件從您自己的可觀測性堆疊監控外掛行為，例如發現率、成本與持續時間。

事件名稱：claude_code.hook_plugin_metrics

屬性：

• 所有標準屬性
• event.name："hook_plugin_metrics"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• plugin_id：<name>@<marketplace> 形式的外掛識別碼
• hook_event：發出指標的 hook 事件類型
• 最多 20 個外掛發出的指標鍵。名稱需符合 ^[a-z][a-z0-9_]{0,39}$。值為布林值或數字。

壓縮事件

在對話壓縮完成時記錄。

事件名稱：claude_code.compaction

屬性：

• 所有標準屬性
• event.name："compaction"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請參閱事件關聯屬性
• trigger："auto" 或 "manual"
• success："true" 或 "false"
• duration_ms：壓縮持續時間
• pre_tokens：壓縮前的約略 token 數量
• post_tokens：壓縮後的約略 token 數量
• error：壓縮失敗時的錯誤訊息
• precompute_reuse：僅在 trigger 為 "manual" 時設定。自動壓縮可在上下文視窗填滿前於背景準備摘要，此屬性記錄 /compact 是否重複使用了該預先準備的摘要。"hit" 表示已重複使用；"miss_custom_instructions"、"miss_hook" 與 "miss_not_ready" 則說明改為重新計算摘要的原因

Subagent 完成事件

在 subagent 完成並將結果傳回啟動它的對話時記錄。可用於依 subagent 類型彙總工具使用情況與執行時間；若要彙總 token 或成本，請使用以 query_source "subagent" 篩選的 token 計數器與成本計數器，因為此事件的 total_tokens 僅涵蓋最後一個請求。"subagent" 類別也會計入來自以 agent 為基礎之 hook 的請求，而這些 hook 不會發出 subagent 事件。

事件名稱：claude_code.subagent_completed

屬性：

• 所有標準屬性
• event.name："subagent_completed"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請見事件關聯屬性
• agent_type：subagent 類型。內建 agent 名稱及來自官方市集外掛的 agent 會原樣顯示；除非設定了 OTEL_LOG_TOOL_DETAILS=1，否則其他 agent 名稱會以 "custom" 取代
• agent.source：agent 定義的來源：built-in、plugin，或定義自訂 agent 的設定來源，例如 userSettings 或 projectSettings
• is_built_in：subagent 是否為內建 agent 類型
• is_async：subagent 是否在背景執行
• total_tokens：subagent 最後一個 API 請求的 token 用量：該請求的輸入、快取建立、快取讀取與輸出 token，大致等於 subagent 完成時的上下文大小。並非整個執行過程的總和
• total_tool_uses：subagent 在整個執行過程中進行的工具呼叫次數
• duration_ms：執行時間（毫秒）
• model：subagent 被解析為使用的模型
• final_model：產生 subagent 最終回應的模型；在執行中途切換（例如備援）之後，此值會與 model 不同。需要 Claude Code v2.1.212 或更新版本
• model_swapped：是否有多個模型處理過 subagent 的請求。需要 Claude Code v2.1.212 或更新版本
• plugin_id_hash、plugin.name：由外掛提供的 agent 才會出現。官方市集外掛名稱會原樣顯示；除非設定了 OTEL_LOG_TOOL_DETAILS=1，否則其他外掛名稱會以 "third-party" 取代

意見調查事件

在顯示或回答工作階段品質調查時記錄。關於調查收集的內容及如何控制，請參閱工作階段品質調查。

事件名稱：claude_code.feedback_survey

屬性：

• 所有標準屬性
• event.name："feedback_survey"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請見事件關聯屬性
• event_type：調查生命週期事件，例如 "appeared"、"responded" 或 "transcript_prompt_appeared"
• appearance_id：用於連結同一調查實例所發出之事件的唯一 ID
• survey_type：產生此事件的調查。"session" 為「How is Claude doing?」評分提示
• response：使用者在 responded 事件中的選擇
• enabled_via_override：設定了 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL 時為 true。以 Boolean 而非字串發出。出現在 session 調查事件上。可依此屬性篩選，以確認覆寫已套用至整個裝置群

保留清理事件

保留清理作業每執行一次記錄一次，此作業會刪除早於 cleanupPeriodDays 設定的工作階段逐字稿及其他應用程式資料。Claude Code 在每個工作階段中最多於背景執行一次清理作業，即使某次執行未刪除任何內容也會發出此事件。若 Claude Code 在過去 24 小時內已於同一台電腦上的任何工作階段執行過清理作業，則會將此工作階段的清理作業延後至少 10 分鐘，因此較早結束的工作階段不會發出任何內容。使用 --bare 執行 claude -p 時，Claude Code 不會執行清理作業，也不會發出任何內容。

如同本頁上的所有 OTel 事件，此事件只會傳送至您設定的遙測後端。需要 Claude Code v2.1.227 或更新版本。

當 Claude Code 無法安全地判斷保留期間時，會暫停清理作業，並發出 result 設為 "skipped" 且帶有 skip_reason 的事件。當受管設定設定了 cleanupPeriodDays 時，受管的值會固定保留期間，即使較低優先順序範圍中的設定檔損毀或無效，清理作業仍會執行。當 managed-settings.json 本身無法讀取時，除非受管層級從其他來源（例如伺服器受管設定或位於損毀檔案旁的 managed-settings.d/ 附加檔案）提供 cleanupPeriodDays，否則 Claude Code 仍會暫停清理作業。刪除計數器屬性只有在 result 為 "complete" 時才會出現。

事件名稱：claude_code.retention_sweep

屬性：

• 所有標準屬性
• event.name："retention_sweep"
• event.timestamp：ISO 8601 時間戳記
• event.sequence：用於排序事件的每程序計數器，說明請見事件關聯屬性
• result：清理作業已執行時為 "complete"，Claude Code 暫停時為 "skipped"
• period_days：合併設定中的 cleanupPeriodDays 值（以天為單位），若沒有任何來源設定則為 30。在略過的事件中，此值為清理作業原本會使用的值，根據 Claude Code 能夠讀取的設定來源計算而得
• used_default：沒有任何可讀取的設定來源設定 cleanupPeriodDays 時為 "true"，否則為 "false"。在完成的事件中，"true" 表示套用了 30 天的預設值
• skip_reason：Claude Code 暫停清理作業的原因。僅在 result 為 "skipped" 時出現：
  • "user_source_disabled"：使用者設定被排除，例如透過 --setting-sources 旗標或 SDK 的 settingSources 選項，且沒有任何已啟用的來源提供 cleanupPeriodDays
  • "settings_unknowable"：某個設定檔無法讀取或剖析，因此 cleanupPeriodDays 或 desktopSessionCleanupPeriodDays 可能被設為 Claude Code 看不到的值
  • "settings_invalid_key_set"：設定有驗證錯誤，且明確設定了 cleanupPeriodDays 或 desktopSessionCleanupPeriodDays，因此改用預設值可能會違反該設定而刪除或保留檔案
• transcripts_deleted：清理作業刪除的工作階段逐字稿（即頂層的 ~/.claude/projects/*/*.jsonl 檔案）數量
• transcripts_exempted_desktop：已超過保留期間、但清理作業依 Claude Desktop 與 Cowork 規則保留的逐字稿數量。這些不計入 files_past_cutoff。需要 Claude Code v2.1.248 或更新版本
• session_files_deleted：工作階段檔案清理作業刪除的 artifact 數量：逐字稿加上每個工作階段的附屬檔案，例如 sidecar、錄製內容與工具結果
• artifacts_deleted：清理作業在其涵蓋的資料目錄中刪除的項目總數，包括工作階段檔案。部分清理作業會將整個移除的目錄樹計為一個項目，且少數清理流程不會計入此計數器，因此請將此值視為下限，而非精確的檔案數量
• files_retained_fresh：已檢查但因仍在保留期間內而保留的檔案。只有逐檔案的清理作業會計入這些檔案，因此此值為下限；非零值為正常的穩定狀態
• files_past_cutoff：早於保留期間但清理作業未能刪除的檔案，例如因權限錯誤或檔案被開啟佔用。此計數也包含清理作業在 skills/synced/ 或 plugins/synced/ 下找到的每個過時資料夾，無論是否將該資料夾移至垃圾桶。除了這些資料夾之外，大於零的值表示有檔案超過了所設定的保留期間；零並不能證明沒有檔案超過，因為移除整個目錄失敗時會改計入 error_count
• error_count：清理作業在列出或刪除檔案時遇到的錯誤數量

受管設定解析事件

隨工作階段所解析的受管設定一併記錄：於工作階段開始時記錄一次，在工作階段期間受管設定或政策輔助程式的狀態變更時再次記錄，以及當 Claude Code 因 error.type 屬性所列的原因之一而拒絕啟動或結束工作階段時記錄。 可使用此事件找出在非預期受管來源上執行的電腦、政策輔助程式失敗的電腦，以及電腦拒絕啟動的原因。 需要 Claude Code v2.1.274 或更新版本。

根據預設，此事件會包含受管來源與政策輔助程式的狀態，但不包含設定本身。若要加入經過遮蔽的 managed_settings.settings 屬性與 managed_settings.resolved_sha256 摘要，請設定 OTEL_LOG_MANAGED_SETTINGS=1：

• 在受管設定、使用者設定或 --settings 的 env 區塊中設定，或在啟動 Claude Code 的環境中設定。在專案或本機設定中設定此值不會啟用它，因為複製的儲存庫可以寫入這些設定。
• 伺服器受管設定可以設定此值而不顯示安全性核准對話方塊，因為此變數只會將您組織自己經過遮蔽的政策加入您組織已經會收到的事件中。

在您尚未信任的資料夾中的互動式工作階段，Claude Code 不會匯出拒絕事件。

事件名稱：claude_code.managed_settings_resolved

屬性：

• 所有標準屬性

• event.name："managed_settings_resolved"

• event.timestamp：ISO 8601 時間戳記

• event.sequence：用於排序事件的每程序計數器，說明請見事件關聯屬性

• managed_settings.trigger：工作階段開始事件為 "startup"，在工作階段後續受管設定或政策輔助程式狀態變更時為 "change"，受管設定政策停止工作階段時為 "refused"。只有當某個屬性與上次傳送的事件不同時，Claude Code 才會傳送 change 事件；即使 OTEL_LOG_MANAGED_SETTINGS 未開啟，設定值的變更也會計入

• error.type：Claude Code 停止工作階段的原因。僅出現在 refused 事件上：

  • "helper_failed"：政策輔助程式執行失敗
  • "policy_invalid"：受管設定包含會阻止 Claude Code 啟動的錯誤，或某個管理來源因讀取被拒以外的原因而載入失敗，導致 Claude Code 無法檢查組織登入或提供者強制規定
  • "provider_not_allowed"：工作階段會使用受管 allowedProviders 清單不允許的 API 提供者，或將某個提供者的流量傳送至不允許的主機。需要 Claude Code v2.1.285 或更新版本
  • "consent_rejected"：使用者拒絕了伺服器受管設定的安全性核准對話方塊
  • "force_refresh_failed"：forceRemoteSettingsRefresh 所要求的設定擷取失敗
  • "gateway_rejected"：Claude apps 閘道以 HTTP 403 回應受管設定載入
  • "version_below_minimum"：此版本的 Claude Code 低於 requiredMinimumVersion 或高於 requiredMaximumVersion
  • "_OTHER"：Claude apps 閘道的受管設定載入因其他原因失敗

• managed_settings.sources：所有提供至少一個政策鍵的受管來源，依優先順序由高至低排列，包括在 first-wins 下其鍵未生效的來源。值包括：MDM 或作業系統層級政策的 "remote"、"plist" 或 "hklm"，受管設定檔與附加檔案的 "file"，嵌入主機提供設定時的 "parent"，以及 Claude Code 讀取Windows HKCU 登錄值時的 "hkcu"。僅包含控制鍵的來源，或 Claude Code 無法讀取的來源，不會列出。以字串陣列發出，若沒有任何受管來源提供政策鍵則為空陣列

• managed_settings.source_behavior：Claude Code 讀取到的 managedSourcesBehavior 值，為 "first-wins" 或 "merge"。沒有任何來源設定此鍵時為 "first-wins"

• managed_settings.helper.state：所選 MDM 或檔案來源所設定之政策輔助程式的狀態：

  • "ok"：輔助程式的輸出作為受管設定使用
  • "bad_path"、"not_a_file"、"exit_nonzero"、"timed_out"、"oversize"、"parse_failed"、"envelope_invalid" 或 "schema_rejected"：輔助程式最近一次執行失敗。輔助程式失敗說明了各種情況
  • "none"：未設定輔助程式，或設定它的來源不是 MDM 政策或受管設定檔

• managed_settings.helper.applied：當輔助程式本身的輸出作為受管設定使用時為 "output"，否則為 "none"

• managed_settings.helper.entry：Claude Code 選取了 policyHelper 時為 "policyHelper"。未選取任何輔助程式時不會出現

• managed_settings.helper.path：輔助程式所設定的 path。只要 Claude Code 選取了輔助程式就會出現，無論是否設定 OTEL_LOG_MANAGED_SETTINGS

• managed_settings.resolved_sha256（當 OTEL_LOG_MANAGED_SETTINGS=1 時）：遮蔽前已解析受管設定的 SHA-256，以遞迴排序鍵且不含空白的 JSON 序列化後計算。摘要相同的電腦執行相同的政策。Claude Code 僅在選擇啟用時才傳送摘要，因為較短的政策可以透過雜湊猜測值而被還原。沒有解析任何受管設定時不會出現，在 refused 事件上也不會出現

• managed_settings.settings（當 OTEL_LOG_MANAGED_SETTINGS=1 時）：已解析受管設定的名稱與結構，以 JSON 字串表示，值經過遮蔽。在 refused 事件上不會出現。Claude Code 依據其設定 schema 建置此值：

  • schema 宣告的設定名稱會被匯出，schema 未宣告的鍵則會被省略
  • Boolean、數字，以及 schema 限制為固定選項集合的字串值（例如 permissions.defaultMode）會原樣匯出。sandbox.network.httpProxyPort 與 sandbox.network.socksProxyPort 會匯出為 "[REDACTED]"
  • 其他所有字串，例如 model、apiKeyHelper、每個 env 值、每個 URL 與每個命令，都會匯出為 "[REDACTED]"
  • 對應表的項目名稱，例如 env 變數名稱與外掛 ID，會原樣匯出。schema 未定義其項目類型的設定（例如 vimInsertModeRemaps）會匯出為單一的 "[REDACTED]"，而 sandbox.ignoreViolations 會匯出為其路徑清單的清單，不含命令模式
  • 清單會保留其長度，每個項目依相同規則遮蔽
  • 當工具內建於此版本的 Claude Code，或為 mcp__ 參照（例如 mcp__jira__create_issue）時，permissions.allow、permissions.deny 或 permissions.ask 規則會匯出為其工具名稱並遮蔽內容，例如 Read([REDACTED])。其他任何規則都會匯出為 "[REDACTED]"
  • hook 遵循相同規則，因此固定選項與數值欄位（例如 type 與 timeout）會顯示，而每個命令、URL、matcher 與 if 條件都會匯出為 "[REDACTED]"

  例如，包含 apiKeyHelper、兩個 env 變數與一條拒絕規則的受管設定會匯出為 {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}。

  Claude Code 會在 UTF-8 編碼 8 KB 處截斷此值，截斷後的值不是有效的 JSON

• managed_settings.settings_truncated（當 managed_settings.settings 存在時）：Claude Code 在 8 KB 處截斷 managed_settings.settings 時為 true，否則為 false。以 Boolean 而非字串發出

解釋指標和事件資料

匯出的指標和事件支援一系列分析：

使用情況監控

成本監控

claude_code.cost.usage 指標有助於：

• 追蹤跨團隊或個人的使用趨勢
• 識別高使用量工作階段以進行最佳化
• 透過 skill.name、plugin.name 和 agent.name 屬性將支出歸因於特定技能、外掛程式或子代理類型

Claude Code 將每個串流回應計入成本和權杖指標中恰好一次，包括當閘道或代理在 ANTHROPIC_BASE_URL 後面跨多個框架逐步串流使用情況時。在 v2.1.214 之前，在多個框架中攜帶使用情況的串流會使 claude_code.cost.usage 和 claude_code.token.usage 膨脹，大約每個額外框架增加一個完整請求。

警報和分段

要考慮的常見警報：

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

所有指標都可以按標準屬性進行分段。model 屬性可在 claude_code.token.usage、claude_code.cost.usage 和 claude_code.lines_of_code.count 上使用。

提交的按模型細分只能透過在 session.id 上與權杖或成本指標進行聯接來近似，因為一個工作階段可以跨越多個模型。篩選權杖或成本端的列，使 query_source 為 "main"，以便輔助和子代理請求不會將工作階段的提交歸因於未進行提交的模型。

偵測重試耗盡

Claude Code 在內部重試失敗的 API 請求，並僅在放棄後才發出單個 claude_code.api_error 事件，因此事件本身是該請求的終端訊號。中間重試嘗試不會作為單獨的事件記錄。

事件上的 attempt 屬性記錄嘗試次數。CLAUDE_CODE_MAX_RETRIES 預設為 10，上限為 15。在 v2.1.199 或更新版本上，您可以設定 CLAUDE_CODE_RETRY_WATCHDOG 以提高預設值並移除上限。

當請求在暫時性錯誤上耗盡所有重試時，attempt 最多為該有效限制加一：預設為 11。

較低的值仍可能表示重試已用盡：每次 Claude Code 在串流失敗後重新發出請求時，attempt 都會從 1 重新開始計算。

若要區分從一個恢復的工作階段與停滯的工作階段，請按 session.id 分組事件，並檢查錯誤後是否存在更晚的 api_request 事件。

事件分析

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

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

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

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

將輸入 token 對應至 OpenTelemetry GenAI 語意慣例

Claude Code 依照 API 回應的 usage 區塊中所呈現的方式匯出輸入 token 計數，因此這些值不包含從提示快取讀取或寫入的 token：

• claude_code.llm_request span 和 api_request 事件上的 input_tokens
• claude_code.token.usage 指標的 "input" 類型

Claude Code 不會設定 gen_ai.usage.* 屬性。OpenTelemetry GenAI 語意慣例規定 gen_ai.usage.input_tokens 應包含從快取讀取和寫入快取的 token。若要計算該總數：

• 從 span 或事件：將 input_tokens、cache_read_tokens 和 cache_creation_tokens 相加
• 從 claude_code.token.usage 指標：將其 "input"、"cacheRead" 和 "cacheCreation" 類型相加

這些慣例也為快取讀取和快取寫入定義了個別的屬性：

• cache_read_tokens 對應至 gen_ai.usage.cache_read.input_tokens
• cache_creation_tokens 對應至 gen_ai.usage.cache_write.input_tokens。較舊版本的慣例將快取寫入屬性命名為 gen_ai.usage.cache_creation.input_tokens，因此請使用您的後端所預期的名稱。

稽核安全事件

OpenTelemetry 事件是 Claude Code 活動的稽核資料來源。每個事件都帶有身份屬性，將工具呼叫、MCP 活動和權限決定與觸發它們的使用者相關聯。OTLP 日誌匯出器可以將這些事件傳遞到任何具有 OTLP 接收器的安全資訊和事件管理 (SIEM) 平台，或轉發到您的 SIEM 的 OpenTelemetry Collector。

將屬性操作歸因於使用者

每個事件上的標準屬性包括已驗證使用者的身份：使用 Claude 帳戶登入時的 user.email、user.account_uuid、user.account_id 和 organization.id，或在雲端工作階段中，當工作階段自身的認證攜帶它們時，加上 user.id 和每個工作階段的 session.id。user.id 是安裝範圍的識別碼，除了在 Claude apps gateway 工作階段上透過 /login 登入時，其中它是來自閘道簽發令牌的 IdP 主體。

在一個開發人員啟動的工作階段中，MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於該開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶，或開發人員在 Claude apps gateway 工作階段上的 IdP 身份。在 Claude Tag 頻道工作階段中，Claude 改為以您組織的共用身份運作。

當 Claude Code 使用直接 API 金鑰進行身份驗證，或針對 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 進行身份驗證時，工作階段中沒有 Claude 帳戶，僅填充 user.id 和 session.id。在這些部署中，使用 OTEL_RESOURCE_ATTRIBUTES 自行附加使用者身份，透過受管設定檔案或啟動包裝器按使用者設定。Claude apps gateway 工作階段不需要任何這些：請參閱標準屬性以了解其匯出所攜帶的身份。

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

稽核 MCP 活動

若要使用完整呼叫詳情捕捉 MCP 伺服器活動，請啟用日誌匯出器並設定 OTEL_LOG_TOOL_DETAILS=1。每個 MCP 操作然後產生結構化事件，其中包含伺服器名稱、工具名稱和呼叫引數以及標準身份屬性：

沒有 OTEL_LOG_TOOL_DETAILS，這些事件會捨棄識別詳情：

• tool_result：保留 mcp_server_scope 和 tool_name 對使用者設定的伺服器編輯為字面上的 "mcp_tool"，省略引數內容。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，它也保留 tool_parameters 內的 mcp_server_name/mcp_tool_name 配對，與 tool_decision 相同的主機編寫例外，需要 Claude Code v2.1.214 或更新版本
• tool_decision：保留 tool_source 和 tool_name 對使用者設定的伺服器編輯為字面上的 "mcp_tool"，省略引數內容。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，它也保留 tool_parameters 內的 mcp_server_name/mcp_tool_name 配對；tool_source 和名稱配對都需要 Claude Code v2.1.214 或更新版本
• mcp_server_connection：省略 server_name 和錯誤訊息，但保留 is_plugin、plugin_id_hash 和 plugin.name，非 Anthropic plugin 名稱被編輯為字面上的 "third-party"，因此 plugin 提供的伺服器在沒有詳細日誌的情況下仍然可以區分

將安全問題對應到事件

建立偵測規則時，查詢您想要監控的訊號並查詢您的後端以取得相應的事件和屬性：

Claude Code 僅發出原始事件流。異常偵測、基線設定、跨工作階段關聯和警報是您的 SIEM 或可觀測性後端的責任。

將外送路徑對應到受管控制項和事件

下表將可能把工作階段內容帶離機器的路徑（以及本機保留）與限制它們的受管設定鍵和記錄它們的事件配對。關於 Claude Code 本身傳送給 Anthropic 的內容（例如 /feedback 報告），請參閱資料使用。各名稱連結至其參考項目，其中提供值和預設值。

allowedHttpHookUrls、managed-mcp.json 和 hook 事件項目需要表格所示以外的說明：

• allowedHttpHookUrls：項目會跨設定檔合併，因此開發人員可以在空白的受管清單中新增項目。allowManagedHooksOnly 決定哪些 hook 會執行
• managed-mcp.json：若要關閉 MCP，請參閱完全停用 MCP。若要確認 Claude Code 會讀取該檔案，請參閱驗證設定
• Hook 事件：Claude Code 會針對每個 hook 事件記錄一次 hook_execution_start 和 hook_execution_complete，涵蓋所有相符的 hook。單獨使用 OTEL_LOG_TOOL_DETAILS=1 不會記錄 HTTP hook 的 URL。hook 設定僅出現在 hook_definitions 中，這還需要詳細的 beta 追蹤

OTEL_LOG_TOOL_DETAILS=1 會將命令字串、伺服器和工具名稱以及工具輸入加入這些事件中。這些詳情可能包含與工作階段本身相同的敏感內容，因此請僅在您的收集器獲准保存該內容時才啟用它。

檢查保留清理

若要讓每台機器使用相同的保留期間，請在受管設定中設定 cleanupPeriodDays。若要檢查機器是否以該值執行清理，請收集 retention_sweep 事件。period_days 和各計數器是字串，因此請在比較之前將它們轉換為數字。

正常運作的機器可能因以下原因而沒有事件：

• 沒有人啟動 Claude Code：不會執行清理，機器會保留其資料直到下次啟動
• 工作階段持續開啟：Claude Code 每個工作階段最多執行一次清理
• 工作階段提早結束：工作階段結束時尚未完成的清理不會發出任何內容，因意外錯誤而停止的清理也不會

清理並未涵蓋所有路徑。保留直到您刪除列出了會保留的內容，清除本機資料則說明如何移除它們。

將事件傳送到 SIEM

將 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 指向您的 SIEM 的 OTLP 接收器，或指向轉發到您的 SIEM 的原生擷取 API 的 OpenTelemetry Collector。以下受管設定範例僅匯出事件，並啟用完整工具詳情以進行 MCP 和 Bash 稽核：

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

若要確認事件已到達，請在執行此設定的工作階段中提交提示，並檢查您的 SIEM 是否有 claude_code.user_prompt 事件。如果沒有任何內容到達，請執行 claude --debug-file <path> 並檢查該日誌中的 [3P telemetry] 匯出錯誤。

後端考量

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

對於指標

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

對於事件/日誌

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

對於追蹤

選擇支援分散式追蹤儲存和跨度關聯的後端：

• 分散式追蹤系統：跨度視覺化、請求瀑布圖、延遲分析
• 功能完整的可觀測性平台：追蹤搜尋和與指標和日誌的關聯

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

服務資訊

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

• service.name：終端機工作階段為 claude-code，從 Claude Desktop 應用程式中的 Code 標籤啟動的工作階段為 claude-code-desktop
• service.version：目前的 Claude Code 版本，或 Code 標籤工作階段的 Desktop 應用程式版本
• os.type：作業系統類型（例如，linux、darwin、windows）
• os.version：作業系統版本字串
• host.arch：主機架構（例如，amd64、arm64）
• wsl.version：WSL 版本號（僅在 Windows Subsystem for Linux 上執行時出現）
• 計量器名稱：com.anthropic.claude_code

如果您的收集器管道或儀表板在 service.name = claude-code 上進行篩選，請將 claude-code-desktop 新增至篩選條件，以同時擷取來自 Code 標籤工作階段的遙測資料。

ROI 測量資源

如需有關測量 Claude Code 投資回報率的綜合指南，包括遙測設定、成本分析、生產力指標和自動化報告，請參閱 Claude Code ROI 測量指南。此儲存庫提供現成可用的 Docker Compose 配置、Prometheus 和 OpenTelemetry 設定，以及用於產生與 Linear 等工具整合的生產力報告的範本。

安全性和隱私

• OpenTelemetry 匯出到您的後端是選擇加入的，需要明確配置。如需了解 Anthropic 的獨立營運遙測以及如何停用它，請參閱資料使用
• 原始檔案內容和程式碼片段不包含在指標或事件中。追蹤跨度是單獨的資料路徑：請參閱下面的 OTEL_LOG_TOOL_CONTENT 項目
• 透過 OAuth 驗證時，user.email 包含在遙測屬性中，僅傳送到您配置的 OTel 端點，絕不會傳送到 Anthropic。如果這對您的組織是個問題，請與您的遙測後端合作以篩選或編輯此欄位
• 預設不收集使用者提示詞內容。僅記錄提示詞長度。若要包含提示詞內容，請設定 OTEL_LOG_USER_PROMPTS=1。啟用時：

  • user_prompt 事件在兩個屬性中帶有提示詞文字：prompt 和 prompt_text。如果您在收集器中依屬性名稱捨棄或遮蔽事件的提示詞文字，請在規則中列出這兩個屬性

    此 OpenTelemetry Collector attributes 處理器會在列出它的管線中刪除這兩個屬性：

    processors:
      attributes/drop-prompt-text:
        actions:
          - key: prompt
            action: delete
          - key: prompt_text
            action: delete
    

  • 開啟追蹤時，claude_code.interaction 跨度會在其 user_prompt 屬性中帶有提示詞文字

  • 在詳細的測試版追蹤下，跨度也會帶有每個請求所傳送的新使用者訊息、工具結果和系統提醒、系統提示詞文字，以及模型輸出。詳細測試版追蹤下的內容屬性列出了每個屬性。claude_code.system_prompt 事件帶有完整的系統提示詞

• 助理回應文字預設不收集。僅記錄回應長度。若要包含回應文字，請設定 OTEL_LOG_ASSISTANT_RESPONSES=1。如同 Claude Code 的所有 OpenTelemetry 資料，回應文字僅傳送到您設定的 OTel 端點，絕不會傳送到 Anthropic。當此變數未設定時，OTEL_LOG_USER_PROMPTS 會用作備援，因此如果您想要事件中有提示詞內容而不要回應內容，請設定 OTEL_LOG_ASSISTANT_RESPONSES=0。在詳細的測試版追蹤下，claude_code.llm_request 跨度仍會在 response.model_output 中帶有模型輸出，該屬性遵循 OTEL_LOG_USER_PROMPTS 而非此變數
• 工具輸入引數和參數預設不記錄。若要包含它們，請設定 OTEL_LOG_TOOL_DETAILS=1。針對 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，tool_decision 和 tool_result 帶有 mcp_server_name/mcp_tool_name 配對，即主機撰寫的名稱而非引數內容，即使旗標關閉也是如此。此例外需要 Claude Code v2.1.214 或更新版本。此資料僅傳送到您設定的 OTEL 端點，絕不會傳送到 Anthropic。引數仍可能包含敏感值，因此請根據需要設定您的遙測後端以篩選或編輯這些屬性。啟用時：
  • tool_result 和 tool_decision 事件包含 tool_parameters 屬性，其中包含 Bash 命令、MCP 伺服器和工具名稱以及 skill 名稱。full_command 等欄位未截斷地發出
  • tool_result 事件另外包含 tool_input 屬性，其中包含檔案路徑、URL、搜尋模式和其他引數。超過 512 個字元的個別值會被截斷，總計上限約為 4 K 字元
  • user_prompt 事件包含自訂、外掛和 MCP 命令的逐字 command_name
  • 成本和 token 計數器以及 api_request、api_error 和 api_refusal 事件在其歸因屬性中帶有真實的 agent、skill、外掛和 MCP 伺服器和工具名稱
  • claude_code.tool 跨度帶有輸入衍生屬性，例如 file_path。在詳細的測試版追蹤下，它還會帶有 tool_input 屬性
• 工具內容預設不在追蹤跨度中記錄。若要包含它，請設定 OTEL_LOG_TOOL_CONTENT=1。claude_code.tool 跨度隨後帶有 tool.output 跨度事件，其中包含原始檔案內容、Bash 命令輸出，以及 MCP 工具、WebFetch 和 WebSearch 傳回的內容，在內容限制（預設 60 KB）處按屬性截斷。來自 MCP 工具、WebFetch 和 WebSearch 的結果需要 Claude Code v2.1.283 或更新版本。工具內容也透過 new_context 到達跨度，其控制因跨度而異。根據需要配置您的遙測後端以篩選或編輯這些屬性
• 原始 Anthropic Messages API 請求和回應主體預設不記錄。若要包含它們，請在您的 shell、使用者設定或受管設定中設定 OTEL_LOG_RAW_API_BODIES。在專案和本機設定中會被忽略。主體包含完整的對話歷史記錄，包括系統提示、每個先前的使用者和助手輪次以及工具結果，因此啟用此選項意味著同意其他 OTEL_LOG_* 內容旗標會揭露的所有內容。Claude Code 始終從這些主體中編輯 Claude 的擴展思考內容，無論其他設定如何。您設定的值決定了 Claude Code 如何傳遞主體：

  • 使用 =1 時，Claude Code 為每個 API 呼叫發出 api_request_body 和 api_response_body 日誌事件。事件的 body 屬性帶有 JSON 序列化的承載，在內容限制（預設 60 KB）處截斷

  • 使用 =file:<dir> 時，Claude Code 將未截斷的主體寫入該目錄下的 .request.json 和 .response.json 檔案，事件帶有 body_ref 路徑而不是內聯主體。使用日誌收集器或邊車傳送目錄，而不是透過遙測流

    對於每個成功的回應，Claude Code 也會在該目錄中的 index.jsonl 附加一行，將回應檔案連結到產生它的請求檔案以及它成為的文字記錄訊息。每一行不包含任何訊息內容，API 回應主體事件部分列出其欄位。索引檔案需要 Claude Code v2.1.274 或更新版本

在 Amazon Bedrock 上監控 Claude Code

如需 Amazon Bedrock 上 Claude Code 使用情況監控的詳細指南，請參閱 Claude Code 監控實作 (Amazon Bedrock)。