Telemetry & Metrics Collection

[ashu17706]

What

Opt-in local telemetry that collects usage metrics to `~/.smriti/telemetry.json` — session counts, tool frequencies, search patterns, ingestion performance, and error rates. No network calls, fully local.

Why

Without telemetry, we're flying blind on how Smriti is actually used: which commands are popular, how large databases get, whether search is fast enough, and what errors users hit. Local-only collection respects privacy while enabling data-driven improvements.

Tasks

• Telemetry store: append-only `~/.smriti/telemetry.json` (JSONL format)
• Automatic collection (opt-in via `SMRITI_TELEMETRY=1` or `smriti telemetry --enable`):
  • Command invocations: which CLI commands are run, how often
  • Ingestion metrics: sessions ingested, messages processed, duration, errors
  • Search metrics: query count, result count, latency, filter usage
  • Database size: total sessions, messages, sidecar table row counts
  • Embedding metrics: vectors built, search latency
• `smriti telemetry` command:
  • `smriti telemetry --enable` / `--disable` to toggle collection
  • `smriti telemetry --show` to view collected metrics
  • `smriti telemetry --clear` to delete collected data
  • `smriti telemetry --export` to dump as JSON for analysis
• Event structure: `{ timestamp, event, data, version }`
• Rotation: auto-rotate when file exceeds 10MB
• Privacy: never collect message content, file paths, or search queries — only counts and durations
• Performance: telemetry writes must not impact CLI latency (async append)

Files

• `src/telemetry/collector.ts` — new Event collection and storage
• `src/telemetry/events.ts` — new Event type definitions
• `src/telemetry/report.ts` — new Telemetry reporting/export
• `src/index.ts` — Add `telemetry` command, instrument existing commands
• `src/config.ts` — Add `SMRITI_TELEMETRY` config
• `test/telemetry.test.ts` — new Telemetry collection tests

Data We Collect

Metric	Example Value	Purpose
`command_invoked`	`{ command: "search", flags: ["--agent"] }`	Command popularity
`ingest_completed`	`{ agent: "claude-code", sessions: 5, messages: 120, durationMs: 340 }`	Ingestion performance
`search_executed`	`{ resultCount: 8, latencyMs: 12, hasFilters: true }`	Search performance
`db_stats`	`{ sessions: 200, messages: 15000, toolUsage: 8500 }`	Database growth
`error_occurred`	`{ command: "ingest", errorType: "parse_error" }`	Error tracking
`embed_completed`	`{ vectors: 500, latencyMs: 2100 }`	Embedding performance

Acceptance Criteria

• Telemetry is off by default — requires explicit opt-in
• `smriti telemetry --enable` starts collecting, `--disable` stops
• `smriti telemetry --show` displays human-readable summary
• No message content, file paths, or search queries are ever recorded
• Telemetry writes don't add > 1ms to CLI command latency
• File auto-rotates at 10MB
• `smriti telemetry --clear` completely removes all collected data

Testing

bun test test/telemetry.test.ts   # Collection + rotation tests
SMRITI_TELEMETRY=1 smriti ingest claude  # Verify metrics recorded
smriti telemetry --show            # View collected data
smriti telemetry --clear           # Verify deletion