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.