PostHog Production Checklist Skill

PostHog Production Checklist

Overview

Production readiness verification for PostHog integrations. Covers SDK configuration hardening, graceful degradation when PostHog is unavailable, health check endpoints, proper shutdown hooks for serverless, and rollback procedures.

Prerequisites

PostHog integration tested in staging
Production PostHog project with phc_ key
Personal API key (phx_) for server-side features
Deployment pipeline configured

Instructions

Pre-Deployment Checklist

SDK Configuration:

[ ] api_host set to correct region (us.i.posthog.com or eu.i.posthog.com)
[ ] capture_pageview: false if using SPA with manual pageview tracking
[ ] capture_pageleave: true for session duration accuracy
[ ] Reverse proxy configured to bypass ad blockers (see posthog-sdk-patterns)
[ ] posthog.debug() disabled in production (guarded by NODE_ENV)
[ ] autocapture configured to exclude noisy elements

Server-Side:

[ ] posthog.shutdown() called in SIGTERM handler and serverless function cleanup
[ ] personalApiKey set for local flag evaluation (not just project key)
[ ] flushAt and flushInterval tuned (default 20/10s is fine for most apps)

Security:

[ ] Personal API key (phx_) never in client bundles or NEXT_PUBLIC_ vars
[ ] .env files in .gitignore
[ ] Separate PostHog project per environment

Step 1: Production SDK Configuration

// lib/posthog-production.ts
import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
  personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
  flushAt: 20,
  flushInterval: 10000,
  requestTimeout: 10000,
  maxRetries: 3,
});

// Graceful shutdown
async function shutdown() {
  await posthog.shutdown();
  process.exit(0);
}
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

Step 2: Graceful Degradation

// PostHog should never break your app — wrap all calls
function safeCapture(distinctId: string, event: string, properties?: Record<string, any>) {
  try {
    posthog.capture({ distinctId, event, properties });
  } catch (error) {
    // Log but never throw — analytics should not crash your app
    console.error('[PostHog] Capture failed:', (error as Error).message);
  }
}

async function safeGetFlag(flagKey: string, userId: string, defaultValue: boolean = false): Promise<boolean> {
  try {
    const result = await posthog.isFeatureEnabled(flagKey, userId);
    return result ?? defaultValue;
  } catch (error) {
    console.error('[PostHog] Flag evaluation failed:', (error as Error).message);
    return defaultValue; // Always return safe default
  }
}

Step 3: Health Check Endpoint

// api/health.ts (Next.js API route or Express handler)
export async function GET() {
  const checks: Record<string, { status: string; latencyMs?: number }> = {};

  // PostHog capture test
  const captureStart = performance.now();
  try {
    posthog.capture({
      distinctId: 'healthcheck',
      event: '$healthcheck',
      properties: { test: true },
    });
    await posthog.flush();
    checks.posthog_capture = {
      status: 'ok',
      latencyMs: Math.round(performance.now() - captureStart),
    };
  } catch {
    checks.posthog_capture = { status: 'degraded' };
  }

  // PostHog flag evaluation test
  const flagStart = performance.now();
  try {
    await posthog.getAllFlags('healthcheck');
    checks.posthog_flags = {
      status: 'ok',
      latencyMs: Math.round(performance.now() - flagStart),
    };
  } catch {
    checks.posthog_flags = { status: 'degraded' };
  }

  const overall = Object.values(checks).every(c => c.status === 'ok') ? 'healthy' : 'degraded';
  return Response.json({ status: overall, checks }, { status: overall === 'healthy' ? 200 : 503 });
}

Step 4: Serverless Function Pattern

// For Vercel Edge Functions, AWS Lambda, etc.
import { PostHog } from 'posthog-node';

export async function handler(request: Request) {
  // Create client per invocation in serverless (or use module-level singleton)
  const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    host: 'https://us.i.posthog.com',
    flushAt: 1,       // Flush immediately in serverless
    flushInterval: 0,  // Don't wait
  });

  try {
    posthog.capture({
      distinctId: getUserId(request),
      event: 'api_called',
      properties: { endpoint: new URL(request.url).pathname },
    });

    const result = await doWork(request);
    return Response.json(result);
  } finally {
    // CRITICAL: Always flush before function exits
    await posthog.shutdown();
  }
}

Step 5: Pre-Flight Verification

set -euo pipefail
# 1. Verify PostHog is reachable from production
curl -sf "https://us.i.posthog.com/healthz" && echo "PostHog: OK" || echo "PostHog: UNREACHABLE"

# 2. Verify capture works
curl -s -X POST 'https://us.i.posthog.com/capture/' \
  -H 'Content-Type: application/json' \
  -d "{\"api_key\":\"$NEXT_PUBLIC_POSTHOG_KEY\",\"event\":\"deploy_preflight\",\"distinct_id\":\"deploy\"}" | jq .

# 3. Verify feature flags load
curl -s -X POST 'https://us.i.posthog.com/decide/?v=3' \
  -H 'Content-Type: application/json' \
  -d "{\"api_key\":\"$NEXT_PUBLIC_POSTHOG_KEY\",\"distinct_id\":\"deploy-check\"}" | \
  jq '{flags_count: (.featureFlags | length), session_recording: (.sessionRecording != false)}'

# 4. Verify admin API (if using server-side features)
curl -sf "https://app.posthog.com/api/projects/$POSTHOG_PROJECT_ID/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" | jq '.name' && echo "Admin API: OK"

Error Handling

| Alert | Trigger | Severity | Action | |-------|---------|----------|--------| | PostHog capture failing | Error rate > 1% | P3 | Check API host, verify key | | Flag evaluation slow | p95 > 500ms | P2 | Enable local evaluation with personalApiKey | | Events not appearing | Zero events for 30min | P2 | Check shutdown() is called, verify flush | | Admin API 401 | Personal key rejected | P1 | Rotate key in PostHog settings |

Rollback Procedure

set -euo pipefail
# Quick rollback if PostHog causes issues
# Option 1: Disable PostHog via env var
kubectl set env deployment/app POSTHOG_ENABLED=false
kubectl rollout restart deployment/app

# Option 2: Roll back deployment
kubectl rollout undo deployment/app
kubectl rollout status deployment/app

Output

Production-hardened PostHog SDK configuration
Graceful degradation wrappers (never crash on analytics failure)
Health check endpoint verifying capture and flag evaluation
Serverless shutdown pattern
Pre-flight verification commands

Resources

Next Steps

For version upgrades, see posthog-upgrade-migration.

Agent Skills: PostHog Production Checklist

Install this agent skill to your local

Skill Files