telemetry-inspect

telemetry-inspect

OrchestKit のテレメトリパイプラインを一度だけヘルスチェックします。ライターのアクティビティ、ファイルサイズ、スキーマロックの適用状況、孤立ファイル、増加に関する警告を報告します。パイプラインが正しく動作しているか確認するときや、ライターが見つからない問題をデバッグするときに使用します。

使用するタイミング

• リスクの高いフックのリファクタリングの前後に、テレメトリが想定どおり書き込まれることを確認するとき
• 長期間稼働しているプロジェクトの週次ヘルスチェック
• analytics の出力が不審なときに、まず基になるデータを調べるとき
• 新しいテレメトリファイルを追加し、認識されることを確認するとき
• スキーマロックの対象ファイルと、スキーマの逸脱に対して脆弱なファイルを監査するとき

チェック項目

1. ライターのアクティビティ — 登録済みの各テレメトリファイルについて、直近の書き込み回数（mtime スキャンによる）と最終書き込みからの経過時間
2. ファイルの状態 — サイズ（256 KB で警告、1 MB で重大）、行数、mtime
3. スキーマロックの状態 — lib/telemetry-schemas.ts にバリデーターがあるファイル
4. 孤立ファイルの検出 — .claude/{telemetry,logs,state,feedback}/ 配下のディスク上のファイルのうち、レジストリにないもの（古いライター、またはスキーマが必要な新規ファイルの可能性があります）。また、src/hooks/src/ に対応するライターフックが存在しなくなったインベントリ行も検出します（停止したライター → 孤立ファイル）。
5. 増加傾向 — セッション開始以降の 1 時間あたりのバイト数（100 KB/時を超えるとアラートを発報）
6. 調整レイヤー（M168） — sessions.db の現在の件数（実行中のセッション、保持中のロック、保留中の worktree リンク、スキルの呼び出し回数）と、coordination-metrics.jsonl による書き込みスループット
7. 実行時の発火状況調査 — run-hook.mjs が ~/.claude/analytics/hook-timing.jsonl に書き込む呼び出しごとの記録から、実際に発火したフックを確認します。チェック 1〜4 で分かるのは「ファイルに書き込みがあるか」です。ここでは、その上流にある「ライターがそもそも実行されているか」を確認します。フックが接続され到達可能であっても（静的にはクロージャゲートで確認できます）、一度も発火しないことがあります。#2886 では、テストが 12 件すべて成功していたにもかかわらず、まさにこの問題が発生しました。

使用方法

telemetry-inspect
telemetry-inspect --session sess-abc123
telemetry-inspect --json

デフォルトモードでは、ターミナルで見やすい ASCII レポートを出力します。--json を指定すると、別のツールにパイプで渡したり、アップロードしたりできる構造化データを出力します。

出力形式（ASCII モード）

Telemetry Health — 2026-07-09 11:50
────────────────────────────────────

Schema-locked files (7)
  .claude/telemetry/pre-compact-decisions.jsonl  ◆ 3 lines  1.1 KB  ✓ healthy
  .claude/telemetry/image-responses.jsonl        ◆ 0 lines  —       ✗ no writes
  .claude/logs/decisions.jsonl                   ◆ 0 lines  —       ✗ no writes
  .claude/logs/subagent-spawns.jsonl             ◆ 6 lines  3 KB    ✓ healthy
  .claude/state/edit-history.jsonl               ◆ 94 lines 412 KB  ⚠ rotate
  .claude/state/ork-metrics-*.json               ◆ (N/A)    2.1 KB  ✓ healthy
  .claude/logs/skill-channels.jsonl              ◆ 12 lines 4 KB    ✓ healthy

Unlocked telemetry files (14)
  .claude/feedback/changelog-decisions.json      ○ 4 KB    ✗ no schema
  .claude/feedback/learned-patterns.json         ○ 8 KB    ✗ no schema
  (...14 more...)

Orphan files (1)
  .claude/feedback/skill-usage.json  — delisted, writer unwired since #959

Runtime fired-census (7d window)
  ALIVE  59   IDLE 3   NEVER 83   UNOBSERVABLE 54
  tree 8.75.0 · installed 8.73.0/8.74.0  <-- SKEW: NEVER is not a verdict
  never-fired writers (the ones that matter here):
    posttool/dirty-file-tracker   [PostToolUse]   0 fires, ever

Summary
  Pipeline health:  GREEN  (21/21 expected writers active)
  Schema coverage:  7/21 (33%)
  Largest file:     edit-history.jsonl (412 KB)
  Hotspot:          edit-history.jsonl  +40 KB/hr

実装計画（このスキルを実行するエージェント／LLM向け）

1. 既知のファイルを一覧表示する — lib/telemetry-schemas.ts の SCHEMA_LOCKED インベントリから、ロックされた 7 つのパスを読み取ります。スキル内の references/telemetry-inventory.md に記載されたロックされていないパスを追加します。
2. インベントリ内の書き込み元をレジストリの閉包と照合する — インベントリを鵜呑みにしないでください。
   • OrchestKit リポジトリのルートで node src/hooks/scripts/validate-registry.mjs を実行し、成功することを確認します（OrchestKit リポジトリ内でない場合は、適切にスキップします）。
   • インベントリに記載されたすべての書き込み元（例：posttool/metrics-bridge）について、ソースファイルが存在することを確認します。test -f src/hooks/src/<writer>.ts
   • インベントリ内の書き込み元が src/hooks/src/ の有効なファイルでない場合は、孤立 — 🔴 として報告し、「想定内だが空」としてはいけません。ディスク上のファイルは鮮度にかかわらず孤立ファイルであり、インベントリの行は古くなっているため、削除対象として指摘します。
3. 各ファイルについて：
   • Glob を使って .claude/state/ork-metrics-*.json パターンを解決します。複数見つかる場合があります。
   • Read に limit: 10 を指定して形式を確認し、Bash wc -l で行数を取得します。
   • Bash stat で更新日時とサイズを確認します。
4. 健全性を分類する：
   • サイズが 1 MB 超 → 重大
   • サイズが 256 KB 超 → 警告
   • 更新日時が 7 日より前 → 「最近の書き込みなし」
   • 行数が 0 → 「書き込みなし」
5. 孤立ファイルをスキャンする — Bash find .claude/{telemetry,logs,state,feedback} -type f の結果を登録済みパスと照合します。ディスク上にあってインベントリにないファイルは孤立ファイルです。手順 2 の書き込み元が無効だった場合の孤立ファイルも統合します。
6. ランタイムの発火状況を集計する — 手順 1～5 では「ファイルに書き込まれているか」を確認します。ここでは、その上流にある「書き込み元のフック自体が実行されるか」を確認します。
   • node src/hooks/scripts/fired-census.mjs --json を実行します（OrchestKit リポジトリ内のみ。他では適切にスキップします。~/.claude/analytics/hook-timing.jsonl がまだ存在しない場合は、終了コード 0 で不在を知らせるメッセージを出力します）。
   • クラス別の件数（totals）を報告し、versions.skewed が true の場合は、その行をそのまま報告します。センサスはインストール済みプラグインによってすべてのプロジェクトを対象に記録されますが、閉包はこのツリーから得られるため、インストール済みビルドより新しいフックが NEVER になるのは想定内であり、指摘事項ではありません。
   • 相互参照：手順 2 のインベントリにある有効なファイルの書き込み元すべてについて、センサスの行を確認します。ALIVE なのにファイルの行数が 0 の書き込み元は、実際の不具合です（実行されているのに何も生成していません）。NEVER の書き込み元は #2886 のクラスに該当します。指摘はしますが、参考情報として扱います。
   • NEVER だけを根拠にフックを停止済みと判断してはいけません。UNOBSERVABLE の行（ディスパッチャーの子）は仕様上、ここには現れません。また、まれなイベント（WorktreeRemove、PreCompact）は、ここでは壊れたガードと同じように見えます。判断を下す前にガードを確認してください。
7. レポートを出力する — デフォルトでは ASCII テーブルを使い、--json 引数が渡された場合は JSON を使います。

中核となる処理は決定的で、読み取り専用です。テレメトリファイルには書き込まないでください。このスキルは監視専用です。

調整レイヤー（M168 #1915）

SQLite 調整レイヤーは .claude/ の外側の ~/.local/state/orchestkit/ にあります。

ソース	確認できる内容
sessions.db	実行中のセッション／ロック／ワークツリーの状態（SQLite）
events.jsonl	調整イベントストリーム（goal_converged、chain_stale、…）
coordination-metrics.jsonl	sessions.db の書き込みスループットカウンター（#1915）

現在の件数 — DB ファイルは標準的な SQLite データベースです。sqlite3 で読み取ります（読み取り専用の SELECT のみ）。

DB="$HOME/.local/state/orchestkit/sessions.db"
[ -f "$DB" ] || echo "coordination layer idle (no multi-session activity yet)"
sqlite3 "$DB" "SELECT COUNT(*) FROM sessions WHERE status='running'"                  # live sessions
sqlite3 "$DB" "SELECT COUNT(*) FROM skill_invocation"                                 # skill invocations

書き込みスループット — coordination-metrics.jsonl は追記専用の {ts, metric, count} 行からなり、sessions.db への書き込みのたびに lib/metrics-emitter.ts が非同期で出力します。イベントレートは、最近の sessions_db_write 行数で概算できます。

M="$HOME/.local/state/orchestkit/coordination-metrics.jsonl"
[ -f "$M" ] && tail -200 "$M" | grep -c '"sessions_db_write"'

適切に縮退処理してください。sqlite3 がない場合、または DB／メトリクスファイルが存在しない場合は、エラーにせず 「調整レイヤーはアイドル状態」 と報告します。このスキルのほかの処理と同様、これらは読み取り専用の観測です。

上流の OTel メトリクスに関する注意事項

Claude Code 自体の OTel メトリクス（このスキルの下流にある、コレクター内の claude_code.*）を調べる場合：

• CC 2.1.129+：claude_code.pull_request.count は、Bash ツール経由で実行されたシェルコマンドだけでなく、MCP ツール（例：GitHub MCP の create_pull_request）経由で作成された PR/MR もカウントするようになりました。2.1.129 より前に作成されたダッシュボードでは、切り替え時に段階的な増加が見られます。注釈を付け、アラートは設定しないでください。MCP 経由とシェル経由で作成された PR を区別する結合パターンについては、../monitoring-observability/references/metrics-collection.md を参照してください。
• CC 2.1.161+：OTEL_RESOURCE_ATTRIBUTES の値が、すべてのメトリクスのデータポイントにラベルとして付与されるようになり、ディメンションによるスライス（チーム、リポジトリ、環境）が可能になりました。既存のダッシュボードは引き続き動作します。新しいダッシュボードでは、ラベルセレクターを使用して使用状況をセグメント化してください。
• CC 2.1.145+：claude_code.tool の OTel スパンに agent_id と parent_agent_id が含まれるようになり、バックグラウンドのサブエージェントのスパンは、呼び出し元の Agent ツールのスパン内にネストされます。parent_agent_id でクエリしてトレースツリーを構築してください。これにより、複数エージェントを使用するスキル（brainstorm、explore、implement）のスキルごとのファンアウト時間とコストの割り当てが可能になります。スキーマの変更は不要です。
• CC 2.1.174+：/usage で、コンポーネントごとの CC ネイティブな割り当て（キャッシュミス、長いコンテキスト、サブエージェント、スキル／エージェント／プラグイン／MCP ごとのコスト内訳、期間は 24 時間／7 日間）が確認できるようになりました（最初に VSCode の「アカウントと使用状況」ダイアログに表示）。ヘルスレポートでは、これを照合用の情報源として扱ってください。ork のテレメトリではスキル／エージェントがアクティブなのに CC の割り当てでは使用量がゼロになっている場合（またはその逆の場合）は、どちらか一方だけを信頼せず、書き込み元の欠落または古いインストールの可能性がある不一致としてフラグを立ててください。
• CC 2.1.202+：ワークフローによって起動されたエージェント（/workflows の実行）のテレメトリに workflow.run_id と workflow.name の属性が含まれるようになり、ワークフロー全体の実行を OTel から再構築できるようになりました。workflow.run_id でエージェントのイベントをまとめて、1 回の実行のファンアウトを再構築し、workflow.name でスライスしてください。フィールド一覧については、../analytics/references/otel-fields.md の「From 2.1.202」を参照してください。通常のセッションイベントにはこれらの属性がないため、最初に select(.["workflow.run_id"] != null) でフィルタリングしてください。

関連項目

• lib/telemetry-schemas.ts — スキーマで固定されたパスの信頼できる情報源
• analytics — セッション間のデータを集計します（用途が異なります）
• M121「Observability Consolidation」マイルストーン