Skip to content

feat(telemetry): capture error_class on setup_complete failures#144

Merged
George-iam merged 1 commit into
mainfrom
feat/setup-error-class-20260523
May 23, 2026
Merged

feat(telemetry): capture error_class on setup_complete failures#144
George-iam merged 1 commit into
mainfrom
feat/setup-error-class-20260523

Conversation

@George-iam
Copy link
Copy Markdown
Contributor

Summary

When setup fails, the dashboard's Phase Failures view (/admin/analytics → Code → Setup health) showed only the failed phase — auth_check: 7, init_scan: 1 — but error_class was always NULL, so it was impossible to tell why setup failed without grepping logs.

This PR populates error_class on the setup_complete event:

Phase error_class set to Why
auth_check "oauth_missing" No Claude subscription and no ANTHROPIC_API_KEY env var — caller never authenticated. Slug already exists in the bounded ErrorClass vocab.
init_scan classifyError(err) Same classification we already feed into the separate error event; now also stamped onto setup_complete so it's visible in one row of the dashboard's Phase Failures table.

Backend ingestion already reads error_class from any event payload (misc_routes.py:2100) — no migration, no schema change.

Why now

Dashboard at https://cloud.axme.ai/admin/analytics currently shows:

  • auth_check: 7 — looking at raw rows, these are all real users who ran axme-code setup without authenticating. Not a bug — but with this fix the dashboard will show auth_check / oauth_missing: 7 so an operator can read it without DB access.
  • init_scan: 1 — one user's LLM scan threw; error_class was NULL so I couldn't tell from the dashboard whether it was timeout, api_error, api_rate_limit, etc. With this fix the next such failure will be self-describing.

Files changed

src/cli.ts — 5 lines:

  • Add setupErrorClass: ErrorClass | null next to existing setupPhaseFailed.
  • Set on auth_check and init_scan branches.
  • Include error_class in the sendTelemetryBlocking("setup_complete", { ... }) payload.

Test plan

  • Type-check clean (npx tsc --noEmit)
  • Full unit test suite passes (608/608)
  • Bundle builds (npm run build)
  • After next release: verify error_class populated for any new setup-failed rows on the dashboard

After merge

Effective for users on the next CLI release. Existing rows in telemetry_events are unchanged — the historical 7 + 1 stay NULL.

🤖 Generated with Claude Code

When setup fails, the dashboard's Phase Failures view showed only the
phase (auth_check / init_scan) but not WHY. Now we populate error_class:
- auth_check  -> "oauth_missing"
- init_scan   -> classifyError(err) of the underlying exception

Backend already reads error_class from any event payload (no migration).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@George-iam George-iam merged commit 8078551 into main May 23, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant