Monitoring & Error Tracking Setup

Configure Sentry error tracking and PostHog analytics for your TinyKit Pro application. Both services are optional and independently configurable — the app works normally without either.

Overview

TinyKit Pro integrates two monitoring services:

• Sentry — Error tracking with stack traces, error grouping, alerting, and automatic GitHub issue creation
• PostHog — Product analytics with user journey tracking, autocapture, and error-to-conversion correlation

Both services follow the graceful degradation pattern: if an API key is missing, that service is silently disabled with zero impact on the application.

Why Both Services?

Sentry Setup

1. Create a Sentry Account

1. Sign up at sentry.io
2. Create a new project — select Browser JavaScript as the platform
3. Copy the DSN from Settings > Projects > [Your Project] > Client Keys (DSN)

2. Configure the Environment Variable

Add your Sentry DSN to .env.local:

NEXT_PUBLIC_SENTRY_DSN=https://examplekey@o1234.ingest.sentry.io/5678

Or use the setup wizard:

bun setup:analytics

3. How It Works

Sentry is initialized automatically via instrumentation-client.ts when the DSN is present. The integration includes:

• Error boundaries — React errors caught by ConvexErrorBoundary and ErrorBoundary are reported to Sentry with component stack traces
• Global error handler — global-error.tsx catches layout-level errors outside the component tree
• User context — Authenticated user IDs are attached to Sentry events (no PII like email)
• ConvexError classification — Intentional errors (validation, auth) are downgraded to info severity to reduce alert noise

Error Severity Strategy

Frontend Error
  ├─► ConvexError (validation, auth, business logic) → Sentry level: "info"
  └─► Unexpected error (bugs, crashes)               → Sentry level: "error"

This ensures Sentry alerts only fire for real bugs, not expected validation errors.

4. Convex Backend Errors (Optional)

Convex's native Sentry integration captures backend function errors with zero code changes:

1. Go to your Convex Dashboard > Deployment Settings > Integrations
2. Select the Sentry card
3. Paste the same DSN
4. Requires Convex Pro plan

Auto-applied tags include: func, func_type, func_runtime, request_id, environment, and user.

See Convex Sentry docs for details.

5. GitHub Integration (Optional)

Configure Sentry to auto-create GitHub issues from errors:

1. Settings > Integrations > GitHub — Connect your repo
2. Alerts > Issue Alerts — Create a rule:
   • Condition: "A new issue is created"
   • Filter: Level is error (excludes info-level ConvexErrors)
   • Action: "Create a GitHub Issue"
3. Use fixes SENTRY-XXX in commit messages to auto-resolve issues

PostHog Setup

1. Create a PostHog Account

1. Sign up at posthog.com (generous free tier)
2. Copy your Project API Key from Settings > Project > API Key

2. Configure Environment Variables

Add to .env.local:

NEXT_PUBLIC_POSTHOG_KEY=phc_your_posthog_key_here
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

3. How It Works

PostHog is initialized in instrumentation-client.ts with autocapture enabled. The configuration includes:

• Autocapture — Automatic click, page view, and form tracking
• Exception capture — Frontend errors linked to analytics sessions
• Privacy-first — Session replay, feature flags, and surveys are disabled by default
• Dev mode — Reduced network activity during local development

Error Capture Overlap

By default, both PostHog (capture_exceptions: true) and Sentry capture frontend errors. They serve different purposes:

• PostHog: Links errors to analytics sessions — "which user journey led to this error?"
• Sentry: Deep error debugging — stack traces, breadcrumbs, grouping, alerting

To let Sentry handle all error tracking, disable PostHog's error capture:

// instrumentation-client.ts
posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
  capture_exceptions: false, // Let Sentry handle errors
  // ... rest of config
});

Graceful Degradation

Architecture

Key Files

Error Flow

Component Error
  ├─► ErrorBoundary.componentDidCatch
  │     ├─► logger.error(...)                // Structured logging
  │     ├─► captureError(error, context)     // Sentry (if configured)
  │     └─► Render fallback UI
  │
  ├─► PostHog (if capture_exceptions: true)
  │     └─► Error linked to analytics session
  │
  └─► Sentry Dashboard
        ├─► Grouped by error type
        ├─► User context (userId only)
        └─► Component stack trace

Verification

After configuring either service:

1. Sentry: Trigger a test error in development, then check the Sentry dashboard (errors only appear when NODE_ENV=production, or temporarily set enabled: true in sentry.ts for testing)
2. PostHog: Visit your app and check the PostHog dashboard for page view events
3. Graceful degradation: Remove the DSN/key from .env.local and verify the app still works without errors