Watching Claude Code Compaction and Hooks Through OpenTelemetry: Reading the compaction, hook_execution_complete and precompute_reuse Fields

Claude Code can export its own behavior as OpenTelemetry events. Most introductions stop at "you can see tokens and cost", but the official monitoring docs also list Compaction, hook and tool-decision events that help answer why a session got slow, expensive or blocked. This article covers the fields of three groups of events. Field names and descriptions come from the official Monitoring page; I did not stand up a collector to test, so the "how to use it" section is my inference and says so.

Turn the events on first

The docs' minimal setup: CLAUDE_CODE_ENABLE_TELEMETRY=1 is required, then pick otlp, console or none with OTEL_LOGS_EXPORTER. Console is the easiest way to look first:

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

To send to a collector, switch to 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

The docs say that for a logs-only setup, submitting a prompt should produce a claude_code.user_prompt event, which confirms it works. Tool parameters and similar detail are not recorded by default; set OTEL_LOG_TOOL_DETAILS=1 for them.

Event one: claude_code.compaction

One record per completed compaction, with trigger (auto or manual), success, duration_ms, pre_tokens and post_tokens (both approximate), error on failure, and precompute_reuse. The last one deserves a close look: the docs say auto-compaction can prepare a summary in the background before the Context Window fills, and precompute_reuse records whether this compaction reused that prepared summary. "hit" means it was reused; "miss_custom_instructions", "miss_hook" and "miss_not_ready" give the reason a fresh summary was computed instead. The attribute is set only when trigger is manual or for an idle compaction, which reports trigger as auto.

Event two: three hook events

• claude_code.hook_registered: one record per configured hook at session start, which the docs say is for inventorying active hooks across a fleet. Fields include hook_event (such as PreToolUse), hook_type (command, prompt, mcp_tool, http, agent), hook_source (userSettings, projectSettings, localSettings, flagSettings, policySettings, pluginHook) and safe_mode.
• claude_code.hook_execution_start: hooks begin executing for a hook event, with hook_name (including the matcher, such as PreToolUse:Write) and num_hooks.
• claude_code.hook_execution_complete: all hooks for the event have finished, with num_success, num_blocking (returned a blocking decision), num_non_blocking_error (failed without blocking), num_cancelled and total_duration_ms. From v2.1.280 there are also character counts such as stdout_chars, additional_context_chars and system_message_chars, plus num_outputs_persisted for outputs over the 10,000-character cap that were saved to a file.

Event three: tool decisions and others

claude_code.tool_decision records each tool approval or rejection: decision is accept or reject, source is config, hook, user_permanent, user_temporary, user_abort or user_reject, and tool_source is builtin, mcp or sdk_host_builtin_mcp. The v2.1.307 release notes add that they fixed classifier_category missing from most Auto Mode classifier blocks and added claude_code.safety_event, emitted for each tool call that a permission rule, auto mode, a safety check, a hook or the Sandbox stopped, prompted or sent back. I could not find a field list for safety_event, so I do not list one. The docs also list at_mention, api_retries_exhausted, Subagent-completed and Skill-activated events.

My inference: what questions these fields can answer

The following is inference from what the fields mean; I have not tested it:

• "Is compaction too frequent?" Count compaction events and look at the pre_tokens to post_tokens ratio; success=false with an error needs attention.
• "Is the pre-prepared summary helping?" Compare precompute_reuse hits with the various misses; many miss_hook values suggest a compaction-related hook is invalidating the prepared summary (my reading of the field name).
• "Are my hooks failing silently?" A num_non_blocking_error above zero in hook_execution_complete means a hook failed without stopping the action, which echoes the earlier fail-open default for hooks.
• "Who loaded which hooks across the team?" Use hook_source and Plugin.name from hook_registered to see what project, user and plugins each contribute.

Two cautions: these events are a session-level behavior record, not complete audit evidence, and the docs do not promise every field exists everywhere; hook_definitions, for example, appears only when detailed beta tracing and OTEL_LOG_TOOL_DETAILS=1 are both on.