PostHog Performance Tuning

Overview

Optimize PostHog event capture, feature flag evaluation, and analytics queries. Focus on client-side batching, local flag evaluation to eliminate network calls, event sampling for high-volume apps, and efficient HogQL queries.

Prerequisites

• PostHog project with API key
• posthog-node SDK installed
• Understanding of PostHog event model
• Feature flags configured (if applicable)

Instructions

Step 1: Configure Optimal Client Batching

import { PostHog } from 'posthog-node';

const posthog = new PostHog(process.env.POSTHOG_API_KEY!, {
  host: 'https://us.i.posthog.com',
  flushAt: 20,         // Batch size before sending (default 20)
  flushInterval: 5000, // Max wait time in ms (default 10000)  # 5000: 10000: 5 seconds in ms
  requestTimeout: 10000,  # 10 seconds in ms
  maxRetries: 3,
  // Disable for tests
  ...(process.env.NODE_ENV === 'test' && { enable: false }),
});

// Ensure events are sent before process exits
process.on('SIGTERM', async () => {
  await posthog.shutdown();
  process.exit(0);
});

Step 2: Local Feature Flag Evaluation

// Fetch flag definitions once, evaluate locally (no network per-call)
let flagDefinitions: any = null;
let lastFetch = 0;
const CACHE_TTL = 30000; // 30 seconds  # 30000: 30 seconds in ms

async function getFeatureFlag(
  flagKey: string,
  distinctId: string,
  properties?: Record<string, any>
) {
  // Refresh definitions periodically
  if (!flagDefinitions || Date.now() - lastFetch > CACHE_TTL) {
    flagDefinitions = await posthog.getAllFlags(distinctId, {
      personProperties: properties,
    });
    lastFetch = Date.now();
  }

  return flagDefinitions[flagKey] ?? false;
}

// For boolean flags in hot paths
async function isFeatureEnabled(flagKey: string, userId: string) {
  const flags = await posthog.getAllFlags(userId);
  return !!flags[flagKey];
}

Step 3: Event Sampling for High-Volume Capture

function shouldSample(eventName: string): boolean {
  const sampleRates: Record<string, number> = {
    '$pageview': 1.0,       // Capture all pageviews
    'button_clicked': 1.0,  // Capture all clicks
    'api_call': 0.1,        // Sample 10% of API calls
    'scroll_depth': 0.05,   // Sample 5% of scroll events
  };

  const rate = sampleRates[eventName] ?? 0.5;
  return Math.random() < rate;
}

function captureWithSampling(
  distinctId: string,
  event: string,
  properties?: Record<string, any>
) {
  if (!shouldSample(event)) return;

  posthog.capture({
    distinctId,
    event,
    properties: {
      ...properties,
      $sample_rate: getSampleRate(event),
    },
  });
}

Step 4: Efficient HogQL Queries

async function queryPostHog(hogql: string) {
  const response = await fetch(
    `https://us.i.posthog.com/api/projects/${process.env.POSTHOG_PROJECT_ID}/query/`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`,
      },
      body: JSON.stringify({
        query: { kind: 'HogQLQuery', query: hogql },
      }),
    }
  );
  return response.json();
}

// Optimized: filter early, limit results
const efficientQuery = `
  SELECT
    properties.$current_url AS url,
    count() AS views,
    uniq(distinct_id) AS unique_visitors
  FROM events
  WHERE event = '$pageview'
    AND timestamp > now() - interval 7 day
  GROUP BY url
  ORDER BY views DESC
  LIMIT 50
`;

Error Handling

Issue	Cause	Solution
Events dropped	Flush not called on exit	Add shutdown hook with posthog.shutdown()
Flag evaluation slow	Network call per evaluation	Use getAllFlags with caching
High event volume cost	Capturing everything	Implement sampling for noisy events
HogQL timeout	Unfiltered full-table scan	Add date filters and LIMIT

Examples

Feature Flag A/B Test Tracking

async function trackExperiment(userId: string, experimentKey: string) {
  const variant = await posthog.getFeatureFlag(experimentKey, userId);

  posthog.capture({
    distinctId: userId,
    event: 'experiment_viewed',
    properties: {
      experiment: experimentKey,
      variant: variant || 'control',
    },
  });

  return variant;
}

Resources

• PostHog Node SDK
• PostHog Feature Flags
• HogQL Documentation

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale