結論：文字数・file保存数・結果を同時に見る
監視対象はstdout_chars、additional_context_chars、system_message_chars、initial_user_message_chars、num_outputs_persistedです。値の大きさだけでは異常と断定せず、hook_name、hook_event、成功数、blocking数、非blocking error数、cancel数、所要時間と組み合わせます。これらのsize属性はClaude Code 2.1.280以降が条件です。
更新根拠はClaude Code changelog 2.1.280、正式なevent名と属性はClaude Code公式Monitoring文書です。hook出力の10,000-character cap、file保存、最大2,000文字previewはClaude Code公式Hooks文書を確認します。
既存のHTTP hook許可先は外部送信境界、managed settingsのOTel監査は設定解決、Apps GatewayのOTLP転送はcollector経路が中心です。本稿はhook出力が大きくなった時の検知と原因確認に限定します。
新しい属性と意味を比較する
| 属性 | 数えるもの | 確認したい問題 |
|---|---|---|
| stdout_chars | 成功したhookのstdout合計 | plain outputの肥大化 |
| additional_context_chars | additionalContext合計 | model contextへの過剰注入 |
| system_message_chars | systemMessage合計 | 利用者向けmessageの長文化 |
| initial_user_message_chars | initialUserMessage合計 | 初回turnの意図しない肥大化 |
| num_outputs_persisted | cap超過でfile保存された件数 | 全文が直接渡らない状態 |
Hooks文書では、plain stdout、additionalContext、systemMessage、initialUserMessageの各文字列を個別に10,000文字で測ります。超過時はsession directoryのfileへ保存し、Claudeへはpathと先頭最大2,000文字のpreviewを渡します。fileがあるからClaudeが自動で全文を読むとは限りません。重要な判断条件が末尾だけにあるhookは、成功扱いでも期待した動作にならない可能性があります。
num_outputs_persistedは失敗数ではありません。大きい出力がfileへ退避された数です。num_successが多くてもpersistedが急増したなら説明の肥大化、生成物の誤出力、debug情報の混入を調べます。num_non_blocking_errorやnum_cancelledが増えた場合は、出力量とは別にschema、timeout、通信を切り分けます。
監視を組み込む8手順
- versionをそろえる。terminal、IDE、runnerでClaude Code 2.1.280以降を確認し、古いclientのeventに新属性がないことを正常として扱います。
- 対象hookを台帳化する。
hook_registeredと設定を使い、hook名、event、owner、目的、blocking可否を整理します。 - OTelの送信先を固定する。
CLAUDE_CODE_ENABLE_TELEMETRY=1とlogs exporter、protocol、endpointをmanaged settingsなど承認済み経路で設定します。 - baselineを取る。通常業務で各size属性、persisted数、duration、成功・errorの分布を数日分測り、いきなり一律閾値を置きません。
- alert条件を決める。persistedが発生、文字数がbaselineから急増、durationとerrorも増加、といった複合条件にします。
- 対象hookだけを再現する。秘密を除いた同じ入力で実行し、stdoutとJSON fieldのどれが増えたかを確認します。
- 出力を短くする。modelが判断に使う結論を前半へ置き、debug log、重複説明、巨大なfile本文はpathや要約へ分離します。
- rollbackを確認する。hook変更を戻し、新sessionでsize、persisted、判断結果がbaselineへ戻ることをreadbackします。
OTelはmetricsをtime series、eventsをlogs/events protocol、任意のtraceをtraces protocolで送ります。hook_execution_completeはeventなので、metrics exporterだけでなくlogs exporterの経路を確認します。送信確認ではsession開始のmetricだけで済ませず、実際にhookを1回動かしてcollectorにeventと新属性が届くかを読みます。
collector・秘密・保存期間を先に決める
size属性自体は文字数と件数ですが、標準属性にはsessionや組織の識別情報が含まれ得ます。さらに詳細beta tracingとOTEL_LOG_TOOL_DETAILS=1を併用するとhook_definitionsが含まれる条件があります。監視開始前に送信項目、collector、閲覧者、保存期間、削除方法を審査し、hook commandや設定にcredentialを埋め込まないでください。
Claude Codeは自身に設定したOTEL_*を、Bash、hooks、MCP server、language serverなどのsubprocessへそのまま渡しません。hook自身もOTel送信したい場合は、そのprocess用の設定を別に管理します。Claude Codeのeventが届くことと、hook application独自のtraceが届くことを同じ疎通確認にしないことが重要です。
managed settingsでOTLP endpointやcredentialを固定すると、developer側の競合する変数が除外される仕様があります。利用者のshellだけを直しても送信先が変わらない場合は、debug logとmanaged設定の優先順位を確認します。勝手な一時collectorへ切り替えず、既存の監視経路で検証してください。
大きすぎる出力を直す判断基準
最初に、出力がmodelの次の判断に必要か、利用者に見せるmessageか、監査logかを分けます。modelへ渡す必要がある結論は短いadditionalContext、利用者への説明は適切なsystemMessage、詳細な診断は保護されたlogやfileへ分離します。同じ全文を複数fieldへ複製すると、それぞれが10,000文字の判定対象になり、contextと保存fileの両方を増やします。
file保存が発生した時は、内容が消えたと決めつけず、session directoryのpath、preview、ClaudeがReadしたか、最終判断へ反映されたかを確認します。重要条件をfile末尾へ置く設計は避け、previewだけでも「何のfileか」「読む必要があるか」「失敗時に止めるか」が分かる先頭構造にします。
alertは固定文字数だけでなく変化率と業務影響で決めます。例えば、通常500文字のpolicy hookが9,000文字へ増えた状態はcap未満でも要調査です。一方、承認済みのinventory hookが一定量を返す場合は、persisted件数が0で判断結果が安定していれば即障害とは限りません。ownerが例外理由と期限を記録します。
チェックリスト
- Claude Code 2.1.280以降を確認した
- logs exporterからhook eventが届くことを確認した
- 五つのsize・persisted属性を保存した
- 成功・blocking・error・cancel・durationも同時に見ている
- 10,000文字超過時のfile保存と2,000文字previewを理解した
- collector、閲覧者、保存期間を承認済みにした
- 詳細tracingへhook定義を送る条件を審査した
- 修正後に新sessionでbaselineへ戻ることを確認した
よくある質問
num_outputs_persistedが1ならhookは失敗ですか？
いいえ。10,000文字を超えた出力がfile保存へ切り替わった件数です。成功・blocking・errorの属性と、Claudeが必要な全文を読んだかを合わせて判断します。
OTelを有効にすればhook本文もすべて送信されますか？
通常のsize属性は文字数と件数です。hook_definitionsなど詳細情報には別の詳細tracing設定が必要で、送信内容と保存先を事前審査します。本文の無制限収集を目的にしません。
10,000文字を超えるhook出力は消えますか？
Claude Codeはsession directoryへ保存し、pathと先頭最大2,000文字のpreviewをClaudeへ渡します。ただし自動で全文を読むとは限らないため、重要条件を先頭へ置き、実際の判断をreadbackします。
公式情報
次の一歩
hookが増え、何がClaudeへ渡り、何がfileやcollectorへ残るか説明できない場合は、Miraigentの無料診断で、hook、出力、監視、保持、停止条件を60秒から整理できます。