Instrument Metrics

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

How metrics works

Canonical URL: https://posthog.com/docs/metrics/architecture

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

• Ingestion

• The series model

• Metric types and temporality

• Querying

• Anomaly detection and samples

• Storage and SQL access

• What the alpha means here

• Next steps

Note: Metrics is in open alpha. Any team can turn it on — open Metrics and select Enable metrics in the onboarding view. The details on this page describe current behavior and may change before general availability.

This page explains what happens to a metric between your application and a chart: how ingestion works, what a series is, how aggregations are computed, and where the data lives. You don't need any of this to use metrics, but it helps when you're deciding what to instrument or debugging why a chart looks the way it does.

Ingestion

Metrics arrive over the OpenTelemetry Protocol (OTLP) via HTTP at /i/v1/metrics, as JSON or protobuf, authenticated with your project token. PostHog accepts the standard OTLP metrics model, so anything that can export OTLP (an OpenTelemetry SDK, a Collector, or the posthog.metrics API in posthog-js, which speaks OTLP under the hood) can send metrics without PostHog specific packages.

Each incoming data point carries a metric name, a metric type, a value (or histogram buckets), a timestamp, resource attributes describing the sender (service name, host), and data point attributes describing the measurement (route, status). Ingestion validates the payload, applies your project's quota, and writes data points to a columnar time series store.

Not every metric arrives over OTLP. A log-based metric is generated at ingestion from your logs: log lines matching a rule are tallied as they arrive and emitted as a metric into the same store, so it shows up in the metrics viewer like any instrumented metric.

The series model

A series is one stream of values identified by the combination of:

• the metric name

• the metric type (gauge, sum, histogram, exponential_histogram, or summary)

• the service name

• the full set of attribute key/value pairs

Record http.requests.total with route=/api/checkout and status=200, then again with status=500, and you have two series. Group a chart by status and each series becomes its own line.

This is why attribute cardinality matters. Ten routes times five status codes is fifty series: cheap, useful, chartable. A user ID attribute with a million values is a million series: expensive, and no chart with a million lines answers a question. Keep attributes to dimensions with a bounded set of values, and reach for logs or traces when you need per user or per request detail.

Metric types and temporality

Counters are where most charting mistakes happen, so PostHog handles their sharp edges for you:

• Cumulative counters (the OpenTelemetry default) report an ever growing total since process start. The absolute value is meaningless for charting; what matters is how much it grew in each time bucket. The rate and increase aggregations compute per series differences, so a counter reported by twenty processes is twenty series diffed independently and then summed.

• Counter resets happen when a process restarts and its total drops back toward zero. rate and increase detect resets the same way Prometheus does, so a restart never shows up as a huge negative spike.

• Delta counters report only what happened since the last export. PostHog reads the temporality that your SDK declares and sums deltas as they are, without differencing.

• Histograms arrive as bucket counts with bucket boundaries. Percentile aggregations combine the buckets across the query window and interpolate the requested quantile, which is how p95 works without storing every raw observation.

• Gauges are stored as reported and aggregate naturally with avg, sum, or percentiles.

If an aggregate overflows what a float can represent, the affected time bucket is returned as an explicit null gap rather than an infinity or a silently wrong number.

Querying

Queries resolve over a shared time grid. PostHog picks a bucket size automatically so a chart has roughly sixty points across the selected range, from one second buckets for short windows up to daily and weekly buckets for long ones, and you can pin the interval explicitly through the API. Every series in a response shares the same grid, which is what makes cross series math line up.

Filters match attribute values with equality, negation, or regular expressions, and can target resource attributes, data point attributes, or both. Group by splits the result into one series per attribute value, keeping the largest series when there are too many to chart.

Through the query API you can also combine multiple metrics with a formula, for example an error ratio computed as errors / requests, evaluated server side on the shared grid.

Anomaly detection and samples

Two more things sit between storage and the chart:

• Anomaly detection. When you chart a metric, PostHog compares the most recent slice of the window against a baseline and, if they differ statistically, finds the onset and ranks which label values drove the move. That powers the anomaly badge and biggest-movers panel in the viewer.

• Raw samples. Alongside the aggregated series, PostHog keeps the individual emissions. The Samples view in the viewer reads these to show the exact data points behind a chart, and to link each one to the trace it was recorded in when trace context is present.

Storage and SQL access

Metrics are stored in a columnar time series table and exposed to SQL as posthog.metrics, scoped to your project like every other PostHog table. The SQL tab in the metrics viewer is a full escape hatch: anything the chart controls can't express, you can write directly, and join against the rest of your PostHog data.

What the alpha means here

While metrics is in open alpha, ingestion details and limits may still change, and metrics data is kept for 30 days. The OTLP endpoint, the series model, and the aggregation semantics described above are the stable core the product is built on.

Next steps

• Get started with metrics

• Why you need metrics

• Set up and send metrics