feat: comprehensive telemetry instrumentation

Merged
AN
8mo ago
+995-9

Summary

  • 25 telemetry event types instrumented across the CLI lifecycle β€” up from 10 defined (many never emitted) to full coverage
  • Error visibility: auth failures, MCP server errors, Python engine crashes, provider errors, permission denials, doom loops
  • Privacy-safe helpers: categorizeToolName() for tool classification, bucketCount() for anonymized counts
  • Telemetry docs page with event table, privacy policy, opt-out instructions, and contributor guide
  • 25 unit tests covering all helpers, event types, privacy validation, and naming conventions

Files changed (15)

FileChanges
src/telemetry/index.ts25 event types, categorizeToolName(), bucketCount(), sequence_index/previous_tool on tool_call
src/session/processor.tstool_call sequencing, context_utilization, error_recovered, provider_error, doom_loop_detected
src/session/prompt.tsagent_outcome tracking
src/mcp/index.tsmcp_server_status + mcp_server_census
src/bridge/engine.tsengine_started, engine_error
src/cli/cmd/auth.tsauth_login (7 paths), auth_logout
src/installation/index.tsupgrade_attempted
src/session/index.tssession_forked
src/session/compaction.tscompaction_triggered (was defined, never emitted)
src/permission/next.tspermission_denied
src/tool/project-scan.tsenvironment_census
test/telemetry/telemetry.test.ts25 tests, 81 assertions
docs/docs/configure/telemetry.mdNew telemetry docs page
docs/docs/network.mdAppInsights firewall endpoint
docs/mkdocs.ymlNav entry for telemetry docs

Test plan

  • npx tsc --noEmit β€” no new type errors (2 pre-existing)
  • bun test β€” 1413 pass, 0 fail across 85 files (including 25 new telemetry tests)
  • Privacy: no SQL/code/credentials/file paths sent; error messages truncated to 500 chars; counts bucketed
  • All events use snake_case domain_action naming convention
  • Manual: start altimate, trigger tool calls, verify tool_category and sequence_index appear in events
  • Manual: disconnect network, verify telemetry failures are silent

πŸ€– Generated with Claude Code