Docker metrics installation

Contents

Note: Metrics is in alpha. Setup details, including the ingestion endpoint, may change before general availability.

If your services already expose Prometheus-format /metrics endpoints, the PostHog metrics agent scrapes them and forwards everything to PostHog. One docker run, no application changes.

Running Kubernetes? Use the Helm chart instead, which also discovers annotated pods automatically.

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

  2. Run the agent

    Required

    Point the agent at one or more host:port targets that expose /metrics:

    Terminal
    docker run -d --name posthog-metrics-agent \
      -e POSTHOG_API_KEY=<ph_project_token> \
      -e POSTHOG_HOST=https://us.i.posthog.com \
      -e SCRAPE_TARGETS=your-app:9090,your-worker:9091 \
      posthog/metrics-agent:latest

    The agent scrapes each target every 15 seconds by default. Two common adjustments:

    Terminal
    -e SCRAPE_INTERVAL=30s \
      -e SCRAPE_METRICS_PATH=/custom/metrics \

    Set SCRAPE_JOB_NAME to control the service_name your metrics arrive under. It defaults to posthog-metrics-agent.

  3. Verify metrics are flowing

    Recommended
    1. Check the agent started cleanly:
    Terminal
    docker logs posthog-metrics-agent

    You should see Everything is ready. Begin running and processing data. Scrape or export errors appear in the same log.

    1. Open Metrics in PostHog and pick a metric from the name picker. Data points should appear within a minute.

    The agent also exposes its own health: :13133 answers health probes, and :8888/metrics serves the agent's own metrics, including scrape successes, queue depth, and points sent or dropped.

    View your metrics in PostHog

  4. Keep data through restarts

    Optional

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

    Terminal
    docker run -d --name posthog-metrics-agent \
      -e POSTHOG_API_KEY=<ph_project_token> \
      -e SCRAPE_TARGETS=your-app:9090 \
      -e PERSIST_QUEUE=1 \
      -v posthog-agent-queue:/var/lib/posthog-agent \
      posthog/metrics-agent:latest

    Samples scraped during an outage then survive restarts and deliver when PostHog is reachable again.

  5. Scale out with shards

    Optional

    One agent scrapes every target itself, which is enough for most setups. For a large target set, run a fleet: set SHARD_COUNT on every instance and give each one a distinct SHARD_INDEX from 0 to SHARD_COUNT - 1. Each instance then scrapes only the targets whose address hashes to its shard, so nothing is scraped twice and nothing is missed.

    Don't scale with plain copies of one agent: two unsharded agents scraping the same targets record every metric twice.

  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

VariableDefaultDescription
POSTHOG_API_KEYrequiredProject token (phc_...), sent as a bearer token
POSTHOG_HOSThttps://us.i.posthog.comPostHog ingestion origin. Set to https://eu.i.posthog.com for EU Cloud
SCRAPE_TARGETSrequiredComma-separated host:port list to scrape
SCRAPE_INTERVAL15sHow often to scrape each target
SCRAPE_METRICS_PATH/metricsMetrics path on the targets
SCRAPE_JOB_NAMEposthog-metrics-agentBecomes service_name on every metric
SHARD_COUNT1Fleet size. Above 1, each instance scrapes only its share of the targets
SHARD_INDEXfrom hostname ordinalThis instance's shard, 0 to SHARD_COUNT - 1
PERSIST_QUEUEoffSet to 1 to buffer undelivered batches on disk
QUEUE_DIR/var/lib/posthog-agentWhere the persistent queue is stored
POSTHOG_DEBUGoffSet to 1 to also log exported batches to stdout

For custom Prometheus scrape_configs or a full OpenTelemetry Collector config, mount them into the container. The agent README documents both escape hatches.

Exemplars: link metrics to traces

If your Prometheus client attaches exemplars (trace and span IDs on counters and histograms), the agent preserves them, and the metrics viewer links those data points to the matching traces. The agent requests the OpenMetrics format automatically, because it's the only Prometheus format that carries exemplars. If your endpoint only serves classic Prometheus text, metrics still flow, only without trace links.

Still have questions?

Was this page useful?