Instrument Metrics

PostHogOfficialCreated by PostHog

Skill
Tool integration
Data and AI
MIT
Low risk

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

Download the skill as a ZIP:
https://autogineer.com/agent-skills/posthog/instrument-metrics/download

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

ATTRIBUTION.mdAdded by AutoGineer940 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md6.5 KiB
references/COMMANDMENTS.md1.5 KiB
references/architecture.md7.0 KiB
references/basics.md5.4 KiB
references/javascript.md4.4 KiB
references/kubernetes.md9.0 KiB
references/nodejs.md4.6 KiB
references/other.md4.5 KiB
references/python.md4.5 KiB
references/start-here.md6.6 KiB

references/basics.md

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

Why you need metrics

Canonical URL: https://posthog.com/docs/metrics/basics

Metrics are numbers about your system measured over time: how many requests you served, how long they took, how deep the job queue is, how much memory a process is using. Where logs record individual events and traces follow individual requests, metrics summarize everything. They answer "how is the system doing?" at a glance, cheaply, all the time.

What is a metric?

A metric is a named time series. You pick a name like http.server.duration, record values against it, and PostHog turns those values into points on a chart. Three shapes cover almost everything:

A counter counts things that only accumulate: requests handled, jobs completed, errors raised. You never care about a counter's absolute value, only how fast it grows. That's why counters are charted as a rate (per second) or an increase (per time bucket).
A gauge is a value that goes up and down: queue depth, open connections, temperature, memory. The current value is the interesting part, so gauges are charted with avg or the latest reading.
A histogram records a distribution: every request duration, every payload size. Histograms let you ask for percentiles, so instead of an average that hides your slowest users, you see the p95 or p99 they actually experience.

Attributes add dimensions to a metric. Record http.server.duration with a route and status attribute and you can later split one chart into a line per route, or filter to only the 5xx responses.

What metrics show you that nothing else does

Logs and traces are records of individual things that happened. They're the right tool when you need to know what happened to one request. But they're expensive to keep at full volume and slow to aggregate across millions of events.

Metrics are pre-aggregated by design. A burst of a million requests becomes a handful of data points per series, which means you can afford to measure everything, keep it always on, and chart a month of history instantly. That makes metrics the right tool for:

Trends: is latency creeping up week over week? Is the queue draining slower than it fills?
Capacity: how close to saturation are your workers, connections, and disks?
Health at a glance: one dashboard that tells you in five seconds whether production is fine.
Alerting ground truth: the numbers you page on need to be cheap, fast, and reliable to compute.

When metrics save you

A queue that grows by 2% an hour never shows up in logs. Every individual job is processed fine, every trace looks healthy, and three weeks later the backlog takes the system down. A gauge on queue depth makes that failure visible on day one as a line that isn't flat.

The same goes for error budgets and latency. A rate on an error counter divided by a rate on a request counter is your error ratio, and a p95 on a duration histogram is what your slowest users feel. Watching those two numbers per service catches most production regressions before your customers report them.

What good metrics look like

Stable names. Pick a convention and keep it. OpenTelemetry style dotted names like http.server.duration and Prometheus style names like jobs_processed_total both work; mixing conventions inside one system makes metrics hard to find.
The right type. Counting things? Counter. Measuring a level? Gauge. Measuring durations or sizes? Histogram.
Low cardinality attributes. Attach dimensions with a bounded set of values (route, status, plan). Never attach user IDs or request IDs; each unique value becomes its own series.
Units in the name or metadata. duration_ms or a unit field saves everyone from guessing.

How PostHog makes metrics useful

Most teams keep metrics in a separate system from everything else, so answering "did that latency spike affect signups?" means tab switching and timestamp matching. In PostHog, metrics live alongside your logs, traces, product analytics, and session replays, in the same project with the same query language.

Everything is queryable as SQL through the posthog.metrics table, and the PostHog MCP server exposes metrics to AI agents, so your tools can chart, compare, and investigate metrics for you. When you chart a metric that has moved against its baseline, an anomaly badge surfaces the change and the label values behind it, and the raw samples stay linked to the logs and traces that explain them.

Next steps

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

2026-11-09

AutoGineer is not affiliated with or endorsed by PostHog or PostHog.

Download ZIP

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