JavaScript (web) metrics installation

If you haven't already, install posthog-js via the snippet or npm and initialize it with your project token. Metrics requires an up-to-date SDK version, so upgrade if you're on an older release.

There is no metrics-specific setup required: the metrics API authenticates with the same project token the SDK already uses. Optionally, set a service name so your metrics are easy to find and filter:

posthog.init('<ph_project_api_key>', {
    api_host: 'https://us.i.posthog.com',
    metrics: {
        serviceName: 'storefront-web',
        environment: 'production',
    },
})

Use the metric type that matches what you're measuring:

// Counters only go up: things you count
posthog.metrics.count('checkout.completed')

// Gauges go up and down: current values
posthog.metrics.gauge('cart.items', 3)

// Histograms record distributions: durations, sizes
posthog.metrics.histogram('api.request.duration', 187, { unit: 'ms' })

Add attributes to slice a metric by dimension, keeping the set of values small and bounded:

posthog.metrics.count('checkout.completed', 1, { attributes: { plan: 'pro' } })

Good attributes: route, status, plan. Bad attributes: user IDs, session IDs, request IDs. Every unique combination of attribute values creates a new series, so high-cardinality dimensions belong in logs or traces, not metrics.

Samples aggregate in memory and flush as one data point per series every few seconds, so recording in hot paths is cheap.

If your app already records metrics with another system, don't rip it out. Add the PostHog call next to the existing one, reusing the same metric name and attributes, so both systems chart the same series while you evaluate.

1. Trigger the code path that records a metric
2. Open Metrics in the PostHog sidebar and pick your metric from the name picker
3. Data points should appear within a minute of sending