|
| 1 | +--- |
| 2 | +name: diagnosing-analytics |
| 3 | +description: 'Use when checking TraceDecay adoption or telemetry health — usage analytics, silent hooks, stale hook logs, or empty analytics tables. Uses the analytics, doctor, and sessions CLI, never raw database queries.' |
| 4 | +--- |
| 5 | + |
| 6 | +# Diagnosing TraceDecay analytics |
| 7 | + |
| 8 | +TraceDecay records three telemetry streams: durable `analytics_events` in the |
| 9 | +user-level global store (`mcp_tool_call` rows from the MCP server, |
| 10 | +`hook_route` rows from daemon routing, and `hook_<agent>` rows bridged from |
| 11 | +hook logs), append-only `hook_analytics.jsonl` files (one per project store |
| 12 | +plus a user-level fallback for hooks that could not resolve a project), and |
| 13 | +the per-project session store used for message-level usage. Adoption and |
| 14 | +health questions are answered from the durable table — never by opening |
| 15 | +store databases directly. |
| 16 | + |
| 17 | +## Commands |
| 18 | + |
| 19 | +1. **`tracedecay analytics diagnostics`** — the one-stop summary. Imports any |
| 20 | + new hook-log rows into the durable table first, then prints event, tool, |
| 21 | + and hook counts, the TraceDecay tool-call count, per-tool/per-hook rollups, |
| 22 | + `hook_sources` with per-file row counts, and usage ratios. Flags: |
| 23 | + `--all` (every project, not just the current one), `--no-sync` (skip the |
| 24 | + import pass; read-only). |
| 25 | +2. **`tracedecay analytics sync`** — run only the hook-log import and report |
| 26 | + how many rows each source contributed. |
| 27 | +3. **`tracedecay doctor`** — per-agent install health: hook registration, MCP |
| 28 | + config, binary staleness. Run this first when a hook seems silent |
| 29 | + (Codex hooks may exist but stay skipped until trusted in Codex's own |
| 30 | + hooks approval prompt). |
| 31 | +4. **`tracedecay tool lcm_status --provider all --json`** and |
| 32 | + **`tracedecay tool lcm_doctor --provider codex --mode diagnose --json`** — |
| 33 | + session-store ingest and compression health per provider. |
| 34 | +5. **`tracedecay sessions search "mcp__tracedecay" --provider all`** — find |
| 35 | + tool usage evidence inside ingested transcripts across providers. |
| 36 | +6. **`tracedecay gain`** / **`tracedecay cost`** — token savings ledger and |
| 37 | + spend rollups. |
| 38 | +7. **Dashboard**: `tracedecay dashboard` serves the same summaries at |
| 39 | + `/api/plugins/analytics/overview|diagnostics|usage|hints`. |
| 40 | + |
| 41 | +## Reading the diagnostics output |
| 42 | + |
| 43 | +- `source: "analytics_events"` means durable data answered; a |
| 44 | + `session_messages_and_hook_analytics` source means no durable events matched |
| 45 | + and the summary fell back to hook logs only. |
| 46 | +- `hook_sources` lists each hook-log file with `rows_total` vs |
| 47 | + `rows_included`. A large gap means rows written before project attribution |
| 48 | + existed; they are visible under `--all` but cannot be assigned to a project. |
| 49 | +- `project_id: null` means the command ran outside an indexed project and |
| 50 | + reported globally. Run from an indexed project root for per-project scope, |
| 51 | + or pass `--all` deliberately. |
| 52 | +- `import.imported` greater than zero means a hook-log backlog was just |
| 53 | + bridged — re-read the counts, they include it. |
| 54 | +- A high hook-call count with a low TraceDecay tool-call count is an adoption gap: |
| 55 | + hooks fire, but sessions are not using tracedecay tools. Check |
| 56 | + `by_prompt_category` to see which task types miss it. |
| 57 | + |
| 58 | +## Guardrails |
| 59 | + |
| 60 | +- A zero-row `analytics_events` table inside a project store is not evidence |
| 61 | + that telemetry is broken — durable events live in the user-level store. Run |
| 62 | + `tracedecay analytics diagnostics` before concluding anything is dead. |
| 63 | +- Never query store databases with sqlite3 or scripts; schemas are internal. |
| 64 | + The diagnostics JSON already merges every relevant source. |
| 65 | +- If the MCP transport is down, every command above still works — they are |
| 66 | + plain CLI subcommands (see `tracedecay:using-the-cli`). |
| 67 | + |
| 68 | +## Output |
| 69 | + |
| 70 | +- Headline counts (events, MCP tool calls, tracedecay calls, hook calls) with |
| 71 | + the exact command used, plus any gaps found: unattributed hook rows, stale |
| 72 | + or missing sources, providers with hooks firing but zero tool usage. |
0 commit comments