Skip to main content Execute PostHog production deployment checklist and rollback procedures.
Use when deploying PostHog integrations to production, preparing for launch,
or implementing go-live procedures.
Trigger with phrases like "posthog production", "deploy posthog",
"posthog go-live", "posthog launch checklist".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill posthog-prod-checklist ai automation claude-code devops mcp ai-agents
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:
capture_pageleave: true
posthog-sdk-patterns)
posthog.debug() disabled in production (guarded by NODE_ENV)
autocapture configured to exclude noisy elements
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.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
