analytics git:20260807.975fe85A

Immutable. This exact content never changes and is served at /api/v1/blob/34970dc91c51b1cb.

---
name: analytics
description: Plan and implement product analytics, error monitoring, health checks, dashboards, and optional admin reporting. Use when adding or auditing app measurement.
license: MIT
---

# Analytics

Build a measurement system that answers product and operational questions. Support PostHog, Google Analytics, Supabase-backed reporting, Sentry, health endpoints, and an optional internal dashboard. Do not install every provider by default.

Before implementation, identify the decisions the data must support: acquisition, activation, retention, feature adoption, revenue, reliability, or incident response. Then choose the smallest stack that can answer them.

## 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 Define the measurement plan

List the questions, events, properties, identity rules, sensitive fields to exclude, retention needs, and who will read the data. Distinguish product analytics from traffic analytics, operational monitoring, and business reporting.

### 1.4 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](references/posthog.md) before adding client or server tracking, page views, identification, or typed events.
- **Sentry error tracking:** Read [references/sentry.md](references/sentry.md) before configuring Sentry, error boundaries, or structured logging.
- **Health endpoint:** Read [references/health-endpoint.md](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.