Node.js metrics installation

npm install posthog-node

Metrics requires an up-to-date SDK version, so upgrade if you're on an older release.

Set a service name so metrics from different systems stay easy to tell apart. It's attached to every series and used by the Metrics UI for filtering.

import { PostHog } from 'posthog-node'

const posthog = new PostHog('<ph_project_token>', {
    host: 'https://us.i.posthog.com',
    metrics: { serviceName: 'billing-worker' },
})

Use your project token (the same one you use for capturing events), not a personal API key.

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

// Counters only go up: things you count
posthog.metrics.count('jobs.processed', 1, { attributes: { queue: 'default' } })

// Gauges go up and down: current values
posthog.metrics.gauge('queue.depth', 7)

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

Samples aggregate in memory and flush as one OTLP data point per series every few seconds, so recording in hot paths is cheap. A burst of 10k count() calls costs one data point on the wire.

Keep attribute values small and bounded: route, status, and plan are good attributes; user IDs, session IDs, and request IDs are not. Every unique combination creates a new series.

If your service already records metrics with Prometheus, StatsD, or 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.

For short-lived processes (cron jobs, CLIs, serverless functions), flush before exiting so the last aggregation window isn't lost:

await posthog.metrics.flush()
// or, when tearing down the whole client:
await posthog.shutdown()

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