Kubernetes

Note: Metrics is in open alpha. Any team can turn it on — open Metrics (opens in a new tab) and select Enable metrics in the onboarding view. Setup details, including the ingestion endpoint, may change before general availability.

If your Kubernetes workloads already expose Prometheus-format /metrics endpoints, the PostHog metrics agent scrapes them and forwards everything to PostHog. One helm install, no application changes.

The agent runs as a single instance by default. To scale beyond one pod, use shards rather than replicas: two plain replicas would scrape every target twice and double-count all metrics.

1. 1

   Prerequisites

   Required

   You need:

   • A running Kubernetes cluster with helm v3 installed
   • Pods that expose Prometheus metrics (the standard prometheus.io/scrape: "true" annotation pattern)
   • Your PostHog project token

   The chart creates a ClusterRole and ClusterRoleBinding so the agent can discover pods across all namespaces. If your cluster uses strict RBAC policies, confirm you have permission to create cluster-scoped roles.

2. 2

   Get your project token

   Required

   You’ll need your PostHog project token to authenticate metrics requests. This is the same token you use for capturing events with the PostHog SDK.

   Important: Use your project token, which starts with phc_. Do not use a personal API key (which starts with phx_).

   You can find your project token in Project Settings (opens in a new tab).

3. 3

   Install the Helm chart

   Required

   Terminal

   bashCopy

   helm install posthog-metrics-agent oci://ghcr.io/posthog/charts/posthog-metrics-agent \
     --set posthog.apiKey=<ph_project_token>

   For EU Cloud, set the host explicitly:

   Terminal

   bashCopy

   helm install posthog-metrics-agent oci://ghcr.io/posthog/charts/posthog-metrics-agent \
   
   

4. 4

   Configure metric discovery

   Required

   Annotation discovery (default)

   By default, the agent discovers and scrapes any pod annotated with prometheus.io/scrape: "true". Two optional annotations control the scrape target:

   Annotation	Default	Description
   prometheus.io/scrape	–	Set to "true" to opt a pod in
   prometheus.io/path	/metrics	Override the metrics path
   prometheus.io/port	Pod’s container port	Override the scrape port

   Example pod annotation:

   YAML

   yamlCopy

5. 5

   Verify metrics are flowing

   Recommended

   1. Confirm the agent pod is running:

   Terminal

   bashCopy

   kubectl get pods -l app.kubernetes.io/name=posthog-metrics-agent

   2. Open Metrics (opens in a new tab) in PostHog and pick a metric from the name picker
   3. Data points should appear within a minute of the agent starting

   If nothing shows up, check the agent logs for connection or authentication errors:

   Terminal

   bashCopy

   kubectl logs -l app.kubernetes.io/name=posthog-metrics-agent

6. 6

   Keep data through restarts

   Optional

   By default, if PostHog is briefly unreachable the agent retries from memory, and a pod restart during that window drops whatever was buffered. To keep those samples, back the queue with a persistent volume:

   Terminal

   bashCopy

   --set persistence.enabled=true

   The chart provisions a volume per agent (using persistence.size and persistence.storageClass), and samples scraped during an outage survive restarts and deliver when PostHog is reachable again.

7. 7

   Scale out with shards

   Optional

   One agent scrapes every target itself, which is enough for most clusters. For a large target set, run a fleet:

   Terminal

   bashCopy

   --set shards=4

   The chart switches to a StatefulSet, each pod works out its own shard from its name, and every target is scraped by exactly one pod: nothing is scraped twice, nothing is missed. Combine with persistence.enabled=true to give each shard its own durable queue.

8. Next steps

   Checkpoint

   What you can do with your metrics

   Action	Description
   Why you need metrics (opens in a new tab)	What metrics show you that events and logs don’t
   Getting started guide (opens in a new tab)	Pick the right metric type, add attributes carefully, and chart what matters
   Group and filter	Group by an attribute for one line per value, or filter with key=value chips
   How metrics works

Configuration reference

Still have questions?

Ask PostHog AI

Was this page useful?

HelpfulCould be better

If you manage secrets separately, point the chart at an existing Kubernetes Secret containing a posthog-api-key key instead of passing the token directly:

Terminal

The API key is stored in a Secret and injected as an environment variable – it never appears in the ConfigMap.

Static targets

For services that don’t carry Prometheus annotations, add fixed host:port targets:

Terminal

You can combine annotation discovery with static targets. To disable annotation discovery entirely and only use static targets, set scrape.annotationDiscovery=false.

Extra scrape configs

For advanced use cases, pass raw Prometheus scrape_configs YAML via scrape.extraScrapeConfigs. This is appended verbatim to the collector configuration.

The agent also exposes its own metrics (scrape successes, queue depth, points sent or dropped) on port 8888, so you can monitor the monitor.

View your metrics in PostHog (opens in a new tab)

Continue with the getting started guide (opens in a new tab)