AutoGineer
Generated banner for Instrument Metrics
Generated logo for Instrument Metrics

Instrument Metrics

PostHogOfficialCreated by PostHog

  • Skill
  • Tool integration
  • Data and AI
  • MIT
  • Low risk
Download ZIP

From the author

Add PostHog metric capture to track counters, gauges, and histograms. Use after implementing features or reviewing PRs to ensure key operations are measured, or when asked to add metrics, counters, or track a value over time. Also handles mirroring existing Prometheus/StatsD/OpenTelemetry metrics into PostHog and initial OTLP exporter setup.
— the description by PostHog

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to instrumenting applications with PostHog metrics. It supports various platforms including Web, Node.js, Python, and Kubernetes, and offers a path for integrating existing OpenTelemetry setups. The skill emphasizes non-intrusive instrumentation, advising developers to add PostHog calls alongside existing metrics rather than replacing them. It includes guidance on selecting appropriate metric types, maintaining low cardinality for performance, and configuring environment variables securely.

What it does

  • Detects existing metrics instrumentation and platform-specific requirements.
  • Implements PostHog metric capture for counters, gauges, and histograms.
  • Mirrors existing Prometheus, StatsD, or OpenTelemetry metrics into PostHog.
  • Configures OTLP exporters for applications already using OpenTelemetry.
  • Provides guidance on setting up necessary environment variables for authentication.
  • Ensures metrics are correctly flushed in short-lived processes.

When to use it

  • After implementing new features that require performance or usage tracking.
  • When asked to add specific counters or gauges to an existing codebase.
  • When you need to track values over time, such as queue depths or API durations.
  • When migrating or mirroring existing metrics from other providers into PostHog.
  • When you need to set up initial OTLP exporter configurations.

Advantages

  • Non-destructive: adds metrics alongside existing instrumentation without restructuring code.
  • Flexible: supports native SDKs and standard OpenTelemetry protocols.
  • Performance-conscious: provides clear rules on maintaining low cardinality to prevent series explosion.
  • Secure: mandates the use of environment variables for sensitive configuration keys.
  • Robust: includes error handling guidelines to ensure metrics collection does not break application boot.

Usage examples

“Add a counter to track the number of successful user signups in my Python application.”
The agent will analyze the Python environment, identify the appropriate PostHog SDK or OTLP setup, and insert a counter increment call at the successful signup logic point.
“Mirror my existing Prometheus metrics into PostHog.”
The agent will identify the existing OTLP exporter or Prometheus client, configure the endpoint to point to PostHog, and ensure the project token is correctly set via environment variables.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/posthog/instrument-metrics/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip instrument-metrics.zip -d .agents/skills

Documentation by PostHog

Add PostHog metric capture

Use this skill to add PostHog metric capture (counters, gauges, and histograms) for new or changed code. Use it after implementing features or reviewing PRs to ensure key operations are measured, when the user asks to add metrics or counters, or to mirror existing metrics instrumentation into PostHog. Supports any platform or language.

Supported platforms: Web (JavaScript), Node.js, Python via the posthog.metrics SDK API, Kubernetes via the metrics agent, and any language via OpenTelemetry (OTLP).

Instructions

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

  • Detect the language, framework, and existing metrics setup.

  • Look for dependency files and project files (package.json, requirements.txt, pyproject.toml, go.mod, pom.xml, etc.).

  • Look for existing metrics instrumentation: Prometheus clients (prom-client, prometheus_client), StatsD/Datadog clients, OpenTelemetry meters, or an OpenTelemetry Collector config.

  • Check whether a PostHog SDK (posthog-js, posthog-node, posthog-python) is already installed.

STEP 2: Choose the capture path.

  • If a PostHog SDK is installed (or the platform supports one), use the posthog.metrics API — no OpenTelemetry packages needed. Read the matching platform reference now.

  • If the codebase already exports OpenTelemetry metrics, point the existing OTLP metrics exporter (or Collector) at PostHog instead — read the "Other Languages" reference. No application code changes needed beyond exporter config.

  • If neither applies, use the "Other Languages" reference as a fallback — it covers the generic OpenTelemetry approach.

STEP 3: Instrument alongside existing metrics.

  • Where the codebase already records a metric (a Prometheus counter, a StatsD call, an OTel instrument), add the PostHog call next to the existing one, reusing the same metric name and attributes. Do NOT remove or restructure the existing instrumentation.

  • Do not alter the fundamental architecture of existing files. Make additions minimal and targeted.

  • You must read a file immediately before attempting to write it.

STEP 4: Add new metrics where they belong.

  • Where the user asked for new metrics, or key operations have no coverage, add PostHog metric calls at the sites they belong: count successes and failures of critical flows, time external calls and jobs with histograms, gauge queue depths and pool sizes.

  • Pick the right type: counters for things that only go up, gauges for values that go up and down, histograms for distributions like durations. Set an explicit unit on histograms (ms, bytes).

  • Use stable, descriptive, dot-separated names (jobs.processed, api.request.duration) and set a service name so systems stay easy to tell apart.

STEP 5: Keep cardinality low.

  • Attributes like route, status, plan, or queue are good; user IDs, session IDs, request IDs, and timestamps are not. Every unique attribute combination creates a new series.

  • If something needs per-user or per-request detail, that's a job for PostHog logs or traces, not metrics.

STEP 6: Set up environment variables. (Skip if the PostHog SDK is already configured — posthog.metrics reuses the SDK's existing project token.)

  • Check if the project already has PostHog environment variables configured (e.g. in .env, .env.local, or framework-specific env files). If valid values already exist, skip this step.

  • If the PostHog project token is missing, use the PostHog MCP server's projects-get tool to retrieve the project's api_token. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.

  • For the PostHog host URL: check the projects-get MCP response for a region field — US maps to https://us.i.posthog.com, EU maps to https://eu.i.posthog.com. If the region is not available from the MCP response or from existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.

  • For the OTLP metrics endpoint, use https://us.i.posthog.com/i/v1/metrics (US) or https://eu.i.posthog.com/i/v1/metrics (EU), matching the region determined above, with the project token as an Authorization: Bearer header.

  • Write these values to the appropriate env file using the framework's naming convention.

  • Reference these environment variables in code instead of hardcoding them.

STEP 7: Verify metrics arrive.

  • For short-lived processes (scripts, cron jobs, serverless), flush before exit (posthog.metrics.flush(), or the OTel provider's forceFlush()/shutdown()).

  • Open Metrics in the PostHog sidebar and pick the metric from the name picker; data points should appear within a minute of sending.

Reference files

  • references/javascript.md - JavaScript (web) metrics installation

  • references/nodejs.md - Node.js metrics installation

  • references/python.md - Python metrics installation

  • references/kubernetes.md - Kubernetes metrics installation

  • references/other.md - Other languages metrics installation

  • references/start-here.md - Getting started with metrics

  • references/basics.md - Why you need metrics

  • references/architecture.md - How metrics works

  • references/COMMANDMENTS.md - Framework-specific rules the integration must follow

Each platform reference contains specific SDK setup, OTLP configuration, and integration patterns. Find the one matching the user's stack.

Key principles

  • Environment variables: Always use environment variables for PostHog keys and OpenTelemetry endpoints. Never hardcode them.

  • Minimal changes: Add PostHog metric capture alongside existing metrics. Don't replace or restructure existing instrumentation.

  • Prefer the SDK: When a PostHog SDK is present, posthog.metrics needs no new packages and no extra authentication. Reserve OTLP setup for codebases already invested in OpenTelemetry or languages without SDK support.

  • Low cardinality: Every unique attribute combination creates a new series. Attach bounded dimensions like route, status, or plan — never user IDs, session IDs, or request IDs.

Files

references/kubernetes.md

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

Kubernetes metrics installation

Canonical URL: https://posthog.com/docs/metrics/installation/kubernetes

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

  • Prerequisites

  • Get your project token

  • Install the Helm chart

  • Configure metric discovery

  • Verify metrics are flowing

  • Keep data through restarts

  • Scale out with shards

  • Next steps

  • Configuration reference

Note: Metrics is in open alpha. Any team can turn it on — open Metrics 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.

  3. 3

    Install the Helm chart

    Required

    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.

  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:

    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:

    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.

  5. 5

    Verify metrics are flowing

    Recommended

    1. Confirm the agent pod is running:

    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:

    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.

    View your metrics in PostHog

  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:

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

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

    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
shards1Agent fleet size. Above 1, a StatefulSet partitions targets so each is scraped once
persistence.enabledfalseBuffer undelivered batches on a persistent volume so restarts lose nothing
persistence.size10GiSize of each agent's queue volume
persistence.storageClass''StorageClass for the queue volume. Empty uses the cluster default
podEnv{}Extra environment variables for the agent container
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

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Python, Needs Node.js

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
PostHog
Publisher
PostHog (Official)
Source
PostHog/skills · skills/omnibus/instrument-metrics · commit a5d30e7
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by PostHog.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download instrument-metrics.zip