用 OpenTelemetry 看 Claude Code 的壓縮與 hook：compaction、hook_execution_complete 與 precompute_reuse 欄位怎麼讀

Claude Code 可以把自己的行為輸出成 OpenTelemetry 事件。多數介紹都停在「可以看 token 與成本」，但官方監控文件還列了壓縮、hook、工具決定等事件，對「為什麼這個 session 變慢／變貴／被擋」很有用。本文整理其中三組事件的欄位與用法。欄位名稱與說明來自官方 Monitoring 文件；我沒有架過收集器實測，所以「怎麼用」一節是我的推論，會標明。

先把事件開起來

文件的最小設定：CLAUDE_CODE_ENABLE_TELEMETRY=1 是必要的，再用 OTEL_LOGS_EXPORTER 選 otlp、console 或 none。先用 console 看看輸出最省事：

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=console   # options: otlp, console, none
claude

要送進收集器就改成 OTLP：

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
export OTEL_LOGS_EXPORT_INTERVAL=5000   # default 5000 ms

文件說只開事件（logs）時，送出一個 prompt 後應該看到 claude_code.user_prompt 事件，就代表通了。工具參數等細節預設不記，需要設 OTEL_LOG_TOOL_DETAILS=1。

事件一：claude_code.compaction

每次壓縮完成時記錄一筆，欄位包括 trigger（auto 或 manual）、success、duration_ms、pre_tokens、post_tokens（都是近似值）、失敗時的 error，以及 precompute_reuse。最後這個值得細看：文件說自動壓縮可以在 context window 填滿之前，先在背景準備好摘要，precompute_reuse 記錄這次壓縮有沒有重用那份預先準備的摘要。"hit" 表示重用；"miss_custom_instructions"、"miss_hook"、"miss_not_ready" 說明為什麼改成現算一份。這個欄位只在 trigger 是 manual，或是閒置壓縮（idle compaction，會把 trigger 報成 auto）時才有。

事件二：hook 的三個事件

• claude_code.hook_registered：session 開始時，每個設定好的 hook 記一筆，文件說用來盤點整個團隊啟用了哪些 hook。欄位有 hook_event（如 PreToolUse）、hook_type（command、prompt、mcp_tool、http、agent）、hook_source（userSettings、projectSettings、localSettings、flagSettings、policySettings、pluginHook）與 safe_mode。
• claude_code.hook_execution_start：一個 hook 事件開始執行，帶 hook_name（含 matcher，如 PreToolUse:Write）與 num_hooks。
• claude_code.hook_execution_complete：該事件的所有 hook 結束時記一筆，有 num_success、num_blocking（回傳阻擋決定的數量）、num_non_blocking_error（失敗但沒有阻擋）、num_cancelled、total_duration_ms。v2.1.280 起另有 stdout_chars、additional_context_chars、system_message_chars 等字元數，以及超過 10,000 字元上限而被存成檔案的 num_outputs_persisted。

事件三：工具決定與其他

claude_code.tool_decision 記錄每次工具核准或拒絕：decision 是 accept 或 reject，source 是 config、hook、user_permanent、user_temporary、user_abort 或 user_reject，tool_source 是 builtin、mcp 或 sdk_host_builtin_mcp。v2.1.307 的更新說明另寫：修正了多數 auto mode 分類器阻擋的事件缺少 classifier_category，並新增 claude_code.safety_event，對每個被權限規則、auto mode、安全檢查、hook 或沙盒擋下、詢問或退回的工具呼叫發出。我沒有查到 safety_event 的欄位清單，所以不在此列。文件還列了 at_mention、api_retries_exhausted、子代理完成與 Skill 啟用等事件。

我的推論：這些欄位可以回答什麼問題

以下是我依欄位意義做的推論，沒有實測：

• 「壓縮是不是太頻繁？」看 compaction 事件的次數，與 pre_tokens／post_tokens 的比例；success=false 搭配 error 是需要處理的。
• 「預先準備的摘要有幫上忙嗎？」看 precompute_reuse 的 hit 與各種 miss 的比例；大量 miss_hook 暗示壓縮相關的 hook 讓預備摘要作廢（這是我對欄位名稱的解讀）。
• 「我的 hook 有沒有在默默失敗？」hook_execution_complete 的 num_non_blocking_error 大於 0，表示有 hook 失敗但沒擋住動作；這和之前 hooks 預設 fail-open 的行為相呼應。
• 「團隊裡誰載入了哪些 hook？」用 hook_registered 的 hook_source 與 Plugin.name 看專案、使用者與外掛各貢獻了什麼。

注意兩件事：這些事件是 session 層級的行為紀錄，不是稽核的完整證據；官方文件也沒有保證每個欄位在所有環境都存在，像 hook_definitions 就要同時開啟詳細追蹤與 OTEL_LOG_TOOL_DETAILS=1 才有。