telemetry-inspect

name	telemetry-inspect
license	MIT
compatibility	Claude Code 2.1.220+.
author	OrchestKit
description	Inspects the OrchestKit telemetry pipeline for the current project — lists all known telemetry files with write counts, sizes, schema status, growth trend, and orphan detection. Use when verifying the observability pipeline is healthy, debugging a missing writer, or auditing which files have schema locks vs. which are drift-vulnerable. Read-only — never modifies telemetry files.
argument-hint	[--session <id>] [--json]
context	inherit
version	1.0.0
tags	["telemetry","observability","diagnostics","metrics","session","health","schema","inspection"]
user-invocable	true
allowed-tools	["Bash","Read","Grep","Glob"]
disallowed-tools	["Write","Edit","MultiEdit","NotebookEdit"]
complexity	low
persuasion-type	collaborative
effort	low
model	haiku
metadata	{"category":"diagnostic"}

/ork:telemetry-inspect

One-shot health check for OrchestKit's telemetry pipeline. Reports writer activity, file sizes, schema lock coverage, orphan files, and growth warnings. Use when verifying the pipeline is flowing correctly or debugging a missing writer.

When to use

• Before or after a risky hook refactor, to prove telemetry still writes as expected
• Weekly health check on a long-running project
• When /ork:analytics output looks suspicious — inspect the underlying data first
• When adding a new telemetry file and wanting to confirm it's picked up
• Auditing which files are schema-locked vs. drift-vulnerable

What it checks

1. Writer activity — for each registered telemetry file, recent write count (from mtime scan) and last-write delta
2. File health — size (warn at 256 KB, critical at 1 MB), line count, mtime
3. Schema lock status — which files have validators in lib/telemetry-schemas.ts
4. Orphan detection — files on disk under .claude/{telemetry,logs,state,feedback}/ that aren't in the registry (possible stale writer or new file needing schema), plus inventory rows whose writer hook no longer exists in src/hooks/src/ (dead writer → orphan)
5. Growth trend — bytes per hour since session start (fire alert if > 100 KB/hr)
6. Coordination layer (M168) — live counts from sessions.db (running sessions, held locks, pending worktree links, skill invocations) plus write throughput from coordination-metrics.jsonl
7. Runtime fired-census — which hooks actually fired, from the per-invocation records run-hook.mjs writes to ~/.claude/analytics/hook-timing.jsonl. Checks 1–4 answer "is the file being written?"; this answers "is the writer running at all?" — the upstream question. A hook can be wired and reachable (the closure gate proves that statically) and still never fire: #2886 shipped exactly that with 12 green tests.

Usage

/ork:telemetry-inspect
/ork:telemetry-inspect --session sess-abc123
/ork:telemetry-inspect --json

Default mode: terminal-friendly ASCII report. --json emits a structured result suitable for piping into another tool or uploading.

Output shape (ASCII mode)

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