OpenTelemetry 是什麼,Claude Code 怎麼用它?
OpenTelemetry(OTel)是可觀測性的開放標準,定義了指標、事件(日誌)與追蹤怎麼輸出。官方監控文件說,Claude Code 在 CLAUDE_CODE_ENABLE_TELEMETRY=1 之後,可以輸出 claude_code.* 事件,例如 user_prompt、tool_decision、compaction、hook_registered、hook_execution_complete、at_mention、api_retries_exhausted。
為什麼存在?
個人用 Claude Code 看畫面就知道發生什麼,但團隊或 CI 要回答「誰載入了哪些 hook」「壓縮是不是失敗」「哪些工具被拒絕」就需要結構化紀錄。OTel 讓這些資料能進你已有的觀測平台,而不是各家自訂格式。
怎麼開啟?
文件的最小設定:CLAUDE_CODE_ENABLE_TELEMETRY=1(必要)、OTEL_LOGS_EXPORTER 選 otlp、console 或 none;送到收集器時再設 OTEL_EXPORTER_OTLP_PROTOCOL(無預設值,需自己設)與 OTEL_EXPORTER_OTLP_ENDPOINT,匯出間隔 OTEL_LOGS_EXPORT_INTERVAL 預設 5000 毫秒。送出一個 prompt 後看到 claude_code.user_prompt 就代表通了。工具參數等細節預設不記,要設 OTEL_LOG_TOOL_DETAILS=1。
對我有什麼影響?
如果你負責一個團隊的 Claude Code 使用,先開 console 輸出看一次事件長什麼樣,再決定接哪個後端。要注意事件不是完整稽核證據,部分欄位要額外開關才有;我沒有架過收集器實測。
公開文件可查的例子:claude_code.compaction 事件有 trigger、pre_tokens、post_tokens 與 precompute_reuse(hit 或 miss_*),可以用來統計壓縮是否頻繁、有沒有重用背景預備的摘要。
優點是標準格式、可進既有觀測平台、事件粒度細;缺點是要自己架收集器與儀表板,且事件是 session 層級紀錄,不等於完整稽核。