add-analytics

Add event tracking, error monitoring, and a status endpoint to the detected web stack.

Phase 1: Detect the Stack

Read the project and figure out what to install.

1.1 Framework

next.config.* → Next.js (check App Router vs Pages Router)
vite.config.* → Vite / React SPA
astro.config.* → Astro
nuxt.config.* → Nuxt
Python backend (main.py, app.py, manage.py) → FastAPI / Django / Flask

1.2 Existing Analytics

Check if any analytics/monitoring is already installed:

posthog-js or posthog-node → PostHog already present
@sentry/nextjs or @sentry/react or sentry-sdk → Sentry already present
@vercel/analytics → Vercel Analytics present
@google-analytics or gtag → GA present

If already installed, audit the setup instead of installing fresh. Check for gaps (missing error boundaries, no server-side tracking, no health endpoint).

1.3 Ask the User

Detected: [framework]
Existing analytics: [what's already there, or "none"]

I'll set up:
1. PostHog — event tracking, user identification, feature flags
2. Sentry — error tracking with source maps
3. Health endpoint — /api/status for uptime monitoring

Need your project keys:
- PostHog API key (get from app.posthog.com → Project Settings)
- Sentry DSN (get from sentry.io → Project Settings → Client Keys)

Or I can set up the code and you add the keys later.

Phase 2: Implement Observability

Load only the implementation references needed for this project:

PostHog analytics: Read references/posthog.md before adding client or server tracking, page views, identification, or typed events.
Sentry error tracking: Read references/sentry.md before configuring Sentry, error boundaries, or structured logging.
Health endpoint: Read references/health-endpoint.md before adding a Next.js or FastAPI status route and uptime monitoring.

Preserve existing integrations. If a system is already present, use its reference to audit gaps instead of installing it again. Match every example to the detected framework and authentication model.

Phase 3: Environment Variables

Add to .env.local (or .env):

# PostHog
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_API_KEY=phc_...  # Same key, used server-side

# Sentry
NEXT_PUBLIC_SENTRY_DSN=https://xxx@o123.ingest.sentry.io/456
SENTRY_AUTH_TOKEN=sntrys_...  # For source map uploads
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

Verify none of these are committed to git. Check .gitignore includes .env*.

Phase 4: Verify

After wiring everything, test each system:

PostHog:
[ ] Open the app → check PostHog dashboard for a pageview event
[ ] Navigate between pages → each page triggers a pageview
[ ] Log in → user appears in PostHog with email/name (identified)
[ ] Track a custom event → appears in PostHog events
[ ] Log out → posthog.reset() called, new anonymous session

Sentry:
[ ] Add a temporary `throw new Error('sentry test')` to a page
[ ] Load the page → error appears in Sentry dashboard
[ ] Check that source maps resolve (you see your actual code, not minified)
[ ] Remove the test error
[ ] Error boundary renders fallback UI (not a white screen)

Health Endpoint:
[ ] GET /api/status returns 200 with uptime and database status
[ ] If database is down, returns 503
[ ] Set up monitoring service to ping it every 5 minutes

Tell the user which systems are live and working.

Important Notes

PostHog free tier: up to 1M events/month. Confirm the current plan limits before relying on them.
Sentry free tier: up to 5K errors/month. Confirm the current plan limits before relying on them.
Don't track PII in PostHog events (no passwords, no credit card numbers). User IDs and emails are fine.
Sample rates matter. 10% tracing in prod keeps costs near zero. Increase only if debugging specific issues.
Source maps are critical for Sentry. Without them, error stack traces show minified code. The Sentry wizard handles this for Next.js. For other frameworks, upload maps during build.