Kubernetes metrics installation

Contents

Note: Metrics is in alpha. 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-replica Deployment by design – two replicas would double-scrape every target and double-count all metrics.

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

  3. Install the Helm chart

    Required
    Terminal
    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
    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:

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

  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:

    AnnotationDefaultDescription
    prometheus.io/scrape–Set to "true" to opt a pod in
    prometheus.io/path/metricsOverride the metrics path
    prometheus.io/portPod's container portOverride the scrape port

    Example pod annotation:

    YAML
    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:

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

  5. Verify metrics are flowing

    Recommended
    1. Confirm the agent pod is running:
    Terminal
    kubectl get pods -l app.kubernetes.io/name=posthog-metrics-agent
    1. Open Metrics in PostHog and pick a metric from the name picker
    2. 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
    kubectl logs -l app.kubernetes.io/name=posthog-metrics-agent
    View your metrics in PostHog

  6. Next steps

    Checkpoint
    What you can do with your metrics

    ActionDescription
    Why you need metricsWhat metrics show you that events and logs don't
    Getting started guidePick the right metric type, add attributes carefully, and chart what matters
    Group and filterGroup by an attribute for one line per value, or filter with key=value chips
    How metrics worksHow metrics are ingested, stored, and queried
    Query with SQLEvery metric lands in the posthog.metrics table, queryable from the SQL tab

    Continue with the getting started guide

Configuration reference

ValueDefaultDescription
posthog.apiKey''Project token (phc_...). Stored in a chart-managed Secret
posthog.existingSecret''Name of an existing Secret with a posthog-api-key key. Takes precedence over apiKey
posthog.hosthttps://us.i.posthog.comPostHog ingestion origin. Set to https://eu.i.posthog.com for EU Cloud
scrape.interval15sHow often to scrape targets
scrape.annotationDiscoverytrueDiscover pods via prometheus.io/scrape annotations
scrape.staticTargets[]Fixed host:port targets, e.g. ['my-svc:9090']
scrape.extraScrapeConfigs''Raw Prometheus scrape_configs YAML appended verbatim
resources.requests.cpu100mCPU request
resources.requests.memory256MiMemory request
resources.limits.memory512MiMemory limit
rbac.createtrueCreate a ClusterRole for pod discovery
serviceAccount.createtrueCreate a dedicated ServiceAccount
serviceAccount.name''Override the ServiceAccount name. Required when serviceAccount.create is false
nodeSelector{}Kubernetes node selector
tolerations[]Kubernetes tolerations
affinity{}Kubernetes affinity rules

Was this page useful?