OpenTelemetryでClaude Codeの圧縮とhookを見る：compaction、hook_execution_complete、precompute_reuseの読み方

Claude Codeは自身の振る舞いをOpenTelemetryイベントとして出力できる。多くの紹介は「トークンとコストが見える」で止まるが、公式のMonitoringドキュメントには、圧縮、hook、ツール判定のイベントも載っており、セッションがなぜ遅い・高い・止められたのかを調べるのに役立つ。本稿は3グループのイベントのフィールドを整理する。フィールド名と説明は公式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

ドキュメントによれば、ログだけの構成ではプロンプトを1つ送るとclaude_code.user_promptイベントが見え、それで疎通が確認できる。ツールの引数などの詳細は既定では記録されず、必要ならOTEL_LOG_TOOL_DETAILS=1を設定する。

イベント1：claude_code.compaction

圧縮が完了するたびに1件記録され、フィールドはtrigger（autoまたはmanual）、success、duration_ms、pre_tokensとpost_tokens（どちらも概算）、失敗時のerror、そしてprecompute_reuseだ。最後のものは注目に値する。ドキュメントによれば、自動圧縮はコンテキストウィンドウが満杯になる前にバックグラウンドで要約を準備でき、precompute_reuseはその圧縮が準備済みの要約を再利用したかを記録する。"hit"は再利用、"miss_custom_instructions"、"miss_hook"、"miss_not_ready"は新しく要約を作った理由を示す。この属性はtriggerがmanualのとき、またはtriggerをautoと報告するアイドル圧縮のときだけ設定される。

イベント2：hookの3つのイベント

• claude_code.hook_registered：セッション開始時に設定済みのhookごとに1件。ドキュメントは、組織全体で有効な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実行開始。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も加わる。

イベント3：ツール判定とその他

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が欠けていた問題を修正し、権限ルール、auto mode、安全チェック、hook、サンドボックスが止めた・確認した・差し戻したツール呼び出しごとに発行されるclaude_code.safety_eventを追加したとある。safety_eventのフィールド一覧は見つけられなかったので載せない。ドキュメントにはat_mention、api_retries_exhausted、サブエージェント完了、スキル有効化のイベントも載っている。

私の推論：これらのフィールドで何がわかるか

以下はフィールドの意味からの推論で、検証していない：

• 「圧縮が多すぎないか」：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が動作を止めずに失敗している。これは先に書いたhookの既定のfail-openと呼応する。
• 「チームで誰がどのhookを読み込んでいるか」：hook_registeredのhook_sourceとPlugin.nameで、プロジェクト、ユーザー、プラグインが何を提供しているかを見る。

2点の注意。これらのイベントはセッション単位の振る舞い記録であり、完全な監査証拠ではない。また、ドキュメントはすべてのフィールドがあらゆる環境で存在するとは約束しておらず、例えばhook_definitionsは詳細ベータトレースとOTEL_LOG_TOOL_DETAILS=1の両方が有効なときだけ含まれる。