---
title: "Telemetry Inspect"
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."
---

<span className="badge badge-blue">Command</span> <span className="badge badge-green">low</span>

```bash title="Invoke"
/ork:telemetry-inspect
```

<ContextualSkillSidebar slug="telemetry-inspect" />


# /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)
5. **Growth trend** — bytes per hour since session start (fire alert if > 100 KB/hr)

## Usage

```bash
/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-04-23 13:45
────────────────────────────────────

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                   ◆ 18 lines 12 KB   ✓ healthy
  .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/feedback/skill-usage.json              ◆ (N/A)    1.2 KB  ✓ healthy

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

Orphan files (0)
  (none detected)

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
```

## Implementation plan (for an agent/LLM running this skill)

1. **List known files** — read `lib/telemetry-schemas.ts`'s `SCHEMA_LOCKED` inventory for the 7 locked paths. Extend with a hardcoded inventory of the other 14 unlocked paths (copy from the skill-local `references/telemetry-inventory.md`).
2. **For each file**:
   - Use `Glob` to resolve `.claude/state/ork-metrics-*.json` pattern → may be multiple
   - Use `Read` with `limit: 10` to see shape and `Bash wc -l` for line count
   - Use `Bash stat` for mtime + size
3. **Classify health**:
   - size > 1 MB → critical
   - size > 256 KB → warn
   - mtime > 7 days → "no recent writes"
   - line count 0 → "no writes"
4. **Orphan scan** — `Bash find .claude/\{telemetry,logs,state,feedback\} -type f` cross-check against registered paths. Any on-disk files not in inventory → orphan.
5. **Render report** — ASCII table by default, JSON if `--json` argument passed.

Core logic is deterministic + read-only. Do NOT write to any telemetry file — this skill is an observer.

## Upstream OTel metric notes

When inspecting Claude Code's own OTel metrics (downstream of this skill — `claude_code.*` in your collector):

- **CC 2.1.129+**: `claude_code.pull_request.count` now also counts PRs/MRs filed via MCP tools (e.g., GitHub MCP `create_pull_request`), not just shell commands run through the Bash tool. Dashboards built before 2.1.129 will see a step-function increase at the cutover — annotate, don't alert. See `references/../monitoring-observability/references/metrics-collection.md` for the join pattern that distinguishes MCP- from shell-filed PRs.

## Related

- `lib/telemetry-schemas.ts` — source of truth for schema-locked paths
- `/ork:analytics` — aggregates data across sessions (different use case)
- M121 "Observability Consolidation" milestone


---

## References (1)

### Telemetry Inventory

# OrchestKit Telemetry File Inventory

Single source of truth listing every known file that OrchestKit hooks write to. The `telemetry-inspect` skill reads this inventory to distinguish "expected" files from orphans.

Last updated: 2026-04-23 (M121 #1491)

## Schema-locked files (7) — validators in `src/hooks/src/lib/telemetry-schemas.ts`

| Path | Writer | Readers | Schema |
|------|--------|---------|--------|
| `.claude/telemetry/image-responses.jsonl` | `posttool/context-crossing-warn` | #1479 cache-aware nudge (future) | `isValidImageResponseEntry` |
| `.claude/telemetry/pre-compact-decisions.jsonl` | `lifecycle/pre-compact-task-done-prompt` | #1476 outcome tracker (future) | `isValidPreCompactDecisionEntry` |
| `.claude/logs/decisions.jsonl` | multiple hooks | `handoff-writer`, `decision-history`, `/ork:analytics` | `isValidDecisionLogEntry` |
| `.claude/logs/subagent-spawns.jsonl` | subagent-start hooks | `pre-compact-guard`, `watchdog`, `pre-compact-task-done-prompt` | `isValidSubagentSpawnEntry` |
| `.claude/state/edit-history.jsonl` | `posttool/write/edit-history-tracker` | `edit-history-tracker`, `decision-history` | `isValidEditHistoryEntry` |
| `.claude/state/ork-metrics-*.json` | `posttool/metrics-bridge` | `lifecycle/session-metrics-summary` | `isValidOrkMetricsSnapshot` |
| `.claude/feedback/skill-usage.json` | `posttool/skill/skill-usage-optimizer` | `skill-usage-optimizer` | `isValidSkillUsageFile` |

## Unlocked telemetry files (14) — no schema validator yet

### `.claude/feedback/` (8)

| Path | Writer |
|------|--------|
| `.claude/feedback/changelog-decisions.json` | changelog-related hook |
| `.claude/feedback/code-style-profile.json` | `posttool/write/code-style-learner` |
| `.claude/feedback/consent-log.json` | `lifecycle/analytics-consent-check` |
| `.claude/feedback/consent-status.json` | `lifecycle/analytics-consent-check` |
| `.claude/feedback/dependency-check-cache.json` | `lifecycle/dependency-version-check` |
| `.claude/feedback/learned-patterns.json` | pattern sync |
| `.claude/feedback/naming-conventions.json` | `posttool/write/naming-convention-learner` |
| `.claude/feedback/patterns-queue.json` | pattern sync |
| `.claude/feedback/permission-denials.jsonl` | permission hooks |
| `.claude/feedback/sync-config.json` | pattern sync |

### `.claude/logs/` (3)

| Path | Writer |
|------|--------|
| `.claude/logs/agent-state.json` | agent state persistence |
| `.claude/logs/config-audit.jsonl` | `posttool/config-change/security-auditor` |
| `.claude/logs/config-changes.jsonl` | `config-change/settings-reload` |

### `.claude/state/` (2)

| Path | Writer |
|------|--------|
| `.claude/state/last-test-run.json` | test-aware hooks |
| `.claude/state/recent-deletes.json` | delete-tracking hook |

## Directory health budgets

| Directory | Target max total size | Action if exceeded |
|-----------|----------------------|-------------------|
| `.claude/telemetry/` | 5 MB | rotate oldest JSONL lines |
| `.claude/logs/` | 10 MB | archive to `.claude/logs/archive/` |
| `.claude/state/` | 2 MB | truncate; state is ephemeral |
| `.claude/feedback/` | 5 MB | consolidate patterns |

## How to add a new telemetry file

1. Add the writer (hook) that produces it
2. Add an entry to the appropriate section above
3. If the file has a stable shape, add a validator to `lib/telemetry-schemas.ts` + promote to Schema-locked table
4. Update the `SCHEMA_LOCKED` array export
5. Add tests to `__tests__/lib/telemetry-schemas.test.ts`

