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

personalApiKey

shutdown()

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

• PostHog Node.js SDK
• PostHog Status Page
• PostHog Support

Next Steps

For version upgrades, see

posthog-upgrade-migration