Posthog Prod Checklist

// 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_FEATURE_FLAGS_SECURE_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);

// 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
  }
}

// api/health.ts (Next.js API route or Express handler)
// getPostHogDeliverySnapshot() reads application-owned counters maintained by
// the capture wrapper; it does not send a synthetic event on every health check.
export async function GET() {
  const delivery = getPostHogDeliverySnapshot();
  const degraded = delivery.errorRatio > delivery.reviewedErrorRatio
    || delivery.oldestQueuedEventMs > delivery.reviewedQueueAgeMs
    || delivery.flagFallbackRatio > delivery.reviewedFlagFallbackRatio;

  return Response.json({
    status: degraded ? 'degraded' : 'healthy',
    checks: {
      capture_delivery: delivery.captureStatus,
      queue_age_ms: delivery.oldestQueuedEventMs,
      flag_fallback_ratio: delivery.flagFallbackRatio,
      last_success_at: delivery.lastSuccessAt,
    },
  }, { status: degraded ? 503 : 200 });
}

// 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();
  }
}

set -euo pipefail
: "${POSTHOG_PUBLIC_HOST:?Set the regional ingestion host for this project}"
: "${POSTHOG_PRIVATE_HOST:?Set the matching private API host}"

# 1. Verify PostHog is reachable from the release environment.
curl -sf "$POSTHOG_PUBLIC_HOST/healthz" && echo "PostHog: OK" || echo "PostHog: UNREACHABLE"

# 2. Verify the public project token through the non-capture flags endpoint.
curl -s -X POST "$POSTHOG_PUBLIC_HOST/flags?v=2" \
  -H 'Content-Type: application/json' \
  -d "{\"api_key\":\"$NEXT_PUBLIC_POSTHOG_KEY\",\"distinct_id\":\"deploy-check\"}" | jq '{flags, errorsParsingFlags}'

# 3. Verify private API access only when the integration requires it.
curl -sf "$POSTHOG_PRIVATE_HOST/api/projects/$POSTHOG_PROJECT_ID/" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" | jq '.name' && echo "Admin API: OK"