Kubernetes metrics installation

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.

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.

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:

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

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:

helm install posthog-metrics-agent oci://ghcr.io/posthog/charts/posthog-metrics-agent \
  --set posthog.existingSecret=my-posthog-secret

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

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:

Example pod annotation:

metadata:
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    prometheus.io/path: "/custom/metrics"

Static targets

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

helm install posthog-metrics-agent oci://ghcr.io/posthog/charts/posthog-metrics-agent \
  --set posthog.apiKey=<ph_project_token> \
  --set 'scrape.staticTargets={my-service:9090,another-service:8080}'

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.

1. Confirm the agent pod is running:

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

2. Open Metrics 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:

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

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

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:

--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.

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

--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.