diff --git a/contents/docs/metrics/index.mdx b/contents/docs/metrics/index.mdx
index f381c227cb6c..617369b0d956 100644
--- a/contents/docs/metrics/index.mdx
+++ b/contents/docs/metrics/index.mdx
@@ -50,7 +50,7 @@ The `metrics` config also accepts `flushIntervalMs`, `maxSeriesPerFlush` (a card
Metrics deliberately carry no user or session context: every distinct attribute value creates a new series, so attach low-cardinality dimensions like plan, route, or status. Never attach user IDs.
-> **Note:** `posthog.metrics` is currently available in posthog-js (web). Support in posthog-node and other SDKs is coming. If you're on another SDK, or not using PostHog SDKs at all, use the OpenTelemetry setup below.
+> **Note:** `posthog.metrics` is available in [posthog-js (web)](/docs/metrics/installation/javascript), [posthog-node](/docs/metrics/installation/nodejs), and [posthog-python](/docs/metrics/installation/python). See the [installation guides](/docs/metrics/installation) for per-platform setup. If you're on another SDK, or not using PostHog SDKs at all, use the OpenTelemetry setup below.
## Set up metrics with OpenTelemetry
diff --git a/contents/docs/metrics/installation/_snippets/metrics-next-steps.mdx b/contents/docs/metrics/installation/_snippets/metrics-next-steps.mdx
new file mode 100644
index 000000000000..6224cbf3a501
--- /dev/null
+++ b/contents/docs/metrics/installation/_snippets/metrics-next-steps.mdx
@@ -0,0 +1,15 @@
+
+
+| Action | Description |
+| --- | --- |
+| **[Why you need metrics](/docs/metrics/basics)** | What metrics show you that events and logs don't |
+| **[Getting started guide](/docs/metrics/start-here)** | Pick the right metric type, add attributes carefully, and chart what matters |
+| **Group and filter** | Group by an attribute for one line per value, or filter with `key=value` chips |
+| **[How metrics works](/docs/metrics/architecture)** | How metrics are ingested, stored, and queried |
+| **Query with SQL** | Every metric lands in the `posthog.metrics` table, queryable from the SQL tab |
+
+
+Continue with the getting started guide
+
+
+
diff --git a/contents/docs/metrics/installation/index.mdx b/contents/docs/metrics/installation/index.mdx
new file mode 100644
index 000000000000..bef8da829434
--- /dev/null
+++ b/contents/docs/metrics/installation/index.mdx
@@ -0,0 +1,23 @@
+---
+title: Install metrics
+---
+
+> **Note:** Metrics is in alpha. Setup details, including the ingestion endpoint, may change before general availability.
+
+There are two ways to get metrics into PostHog:
+
+- **PostHog SDKs**: if a PostHog SDK is already in your app, record metrics with the `posthog.metrics` API. No new packages, no extra authentication.
+- **OpenTelemetry (OTLP)**: if you use OpenTelemetry anywhere else, point your OTLP metrics exporter at PostHog. No PostHog packages required.
+
+Already capturing metrics with Prometheus, StatsD, or Datadog? You don't need to replace anything: add the PostHog call next to your existing instrumentation, using the same metric name and attributes, and migrate at your own pace.
+
+## Platforms
+
+| Platform | Method |
+| --- | --- |
+| [JavaScript (web)](/docs/metrics/installation/javascript) | `posthog.metrics` API in [posthog-js](/docs/libraries/js) |
+| [Node.js](/docs/metrics/installation/nodejs) | `posthog.metrics` API in [posthog-node](/docs/libraries/node) |
+| [Python](/docs/metrics/installation/python) | `posthog.metrics` API in [posthog-python](/docs/libraries/python) |
+| [Other languages](/docs/metrics/installation/other) | Any OpenTelemetry-compatible OTLP metrics exporter |
+
+> **Note:** Metrics uses the OpenTelemetry Protocol (OTLP) standard. If your language isn't listed, check the [OpenTelemetry documentation](https://opentelemetry.io/docs/) for compatible libraries and see [other languages](/docs/metrics/installation/other).
diff --git a/contents/docs/metrics/installation/javascript.mdx b/contents/docs/metrics/installation/javascript.mdx
new file mode 100644
index 000000000000..de99deda3c03
--- /dev/null
+++ b/contents/docs/metrics/installation/javascript.mdx
@@ -0,0 +1,81 @@
+---
+title: JavaScript (web) metrics installation
+platformLogo: javascript
+showStepsToc: true
+---
+
+import { Steps, Step } from 'components/Docs/Steps'
+import MetricsNextSteps from './_snippets/metrics-next-steps.mdx'
+
+> **Note:** Metrics is in alpha. Setup details may change before general availability.
+
+If [posthog-js](/docs/libraries/js) is already running on your site, you can record metrics directly with the `posthog.metrics` API. No new packages, no extra authentication.
+
+
+
+
+
+If you haven't already, [install posthog-js](/docs/libraries/js#installation) via the snippet or npm and initialize it with your project token. Metrics requires an up-to-date SDK version, so upgrade if you're on an older release.
+
+There is no metrics-specific setup required: the metrics API authenticates with the same project token the SDK already uses. Optionally, set a service name so your metrics are easy to find and filter:
+
+```js
+posthog.init('', {
+ api_host: '',
+ metrics: {
+ serviceName: 'storefront-web',
+ environment: 'production',
+ },
+})
+```
+
+
+
+
+
+Use the metric type that matches what you're measuring:
+
+```js
+// Counters only go up: things you count
+posthog.metrics.count('checkout.completed')
+
+// Gauges go up and down: current values
+posthog.metrics.gauge('cart.items', 3)
+
+// Histograms record distributions: durations, sizes
+posthog.metrics.histogram('api.request.duration', 187, { unit: 'ms' })
+```
+
+Add attributes to slice a metric by dimension, keeping the set of values small and bounded:
+
+```js
+posthog.metrics.count('checkout.completed', 1, { attributes: { plan: 'pro' } })
+```
+
+Good attributes: `route`, `status`, `plan`. Bad attributes: user IDs, session IDs, request IDs. Every unique combination of attribute values creates a new series, so high-cardinality dimensions belong in [logs](/docs/logs) or [traces](/docs/distributed-tracing), not metrics.
+
+Samples aggregate in memory and flush as one data point per series every few seconds, so recording in hot paths is cheap.
+
+
+
+
+
+If your app already records metrics with another system, don't rip it out. Add the PostHog call next to the existing one, reusing the same metric name and attributes, so both systems chart the same series while you evaluate.
+
+
+
+
+
+1. Trigger the code path that records a metric
+2. Open **Metrics** in the PostHog sidebar and pick your metric from the name picker
+3. Data points should appear within a minute of sending
+
+
+View your metrics in PostHog
+
+
+
+
+
+
+
diff --git a/contents/docs/metrics/installation/nodejs.mdx b/contents/docs/metrics/installation/nodejs.mdx
new file mode 100644
index 000000000000..f158e15c3613
--- /dev/null
+++ b/contents/docs/metrics/installation/nodejs.mdx
@@ -0,0 +1,96 @@
+---
+title: Node.js metrics installation
+platformLogo: nodejs
+showStepsToc: true
+---
+
+import { Steps, Step } from 'components/Docs/Steps'
+import MetricsNextSteps from './_snippets/metrics-next-steps.mdx'
+
+> **Note:** Metrics is in alpha. Setup details may change before general availability.
+
+The [posthog-node](/docs/libraries/node) SDK includes the `posthog.metrics` API, so you can record metrics with the same client you use for events and feature flags.
+
+
+
+
+
+```bash
+npm install posthog-node
+```
+
+Metrics requires an up-to-date SDK version, so upgrade if you're on an older release.
+
+
+
+
+
+Set a service name so metrics from different systems stay easy to tell apart. It's attached to every series and used by the Metrics UI for filtering.
+
+```js
+import { PostHog } from 'posthog-node'
+
+const posthog = new PostHog('', {
+ host: '',
+ metrics: { serviceName: 'billing-worker' },
+})
+```
+
+Use your **project token** (the same one you use for capturing events), not a [personal API key](/docs/api#authentication).
+
+
+
+
+
+Use the metric type that matches what you're measuring:
+
+```js
+// Counters only go up: things you count
+posthog.metrics.count('jobs.processed', 1, { attributes: { queue: 'default' } })
+
+// Gauges go up and down: current values
+posthog.metrics.gauge('queue.depth', 7)
+
+// Histograms record distributions: durations, sizes
+posthog.metrics.histogram('job.duration', 42, { unit: 'ms' })
+```
+
+Samples aggregate in memory and flush as one OTLP data point per series every few seconds, so recording in hot paths is cheap. A burst of 10k `count()` calls costs one data point on the wire.
+
+Keep attribute values small and bounded: `route`, `status`, and `plan` are good attributes; user IDs, session IDs, and request IDs are not. Every unique combination creates a new series.
+
+
+
+
+
+If your service already records metrics with Prometheus, StatsD, or another system, don't rip it out. Add the PostHog call next to the existing one, reusing the same metric name and attributes, so both systems chart the same series while you evaluate.
+
+
+
+
+
+For short-lived processes (cron jobs, CLIs, serverless functions), flush before exiting so the last aggregation window isn't lost:
+
+```js
+await posthog.metrics.flush()
+// or, when tearing down the whole client:
+await posthog.shutdown()
+```
+
+
+
+
+
+1. Trigger the code path that records a metric
+2. Open **Metrics** in the PostHog sidebar and pick your metric from the name picker
+3. Data points should appear within a minute of sending
+
+
+View your metrics in PostHog
+
+
+
+
+
+
+
diff --git a/contents/docs/metrics/installation/other.mdx b/contents/docs/metrics/installation/other.mdx
new file mode 100644
index 000000000000..4e678514f76d
--- /dev/null
+++ b/contents/docs/metrics/installation/other.mdx
@@ -0,0 +1,87 @@
+---
+title: Other languages metrics installation
+platformIconName: IconCode
+showStepsToc: true
+---
+
+import { Steps, Step } from 'components/Docs/Steps'
+import MetricsNextSteps from './_snippets/metrics-next-steps.mdx'
+
+> **Note:** Metrics is in alpha. Setup details, including the ingestion endpoint, may change before general availability.
+
+PostHog Metrics works with any OpenTelemetry-compatible client. If your app or infrastructure already exports OTLP metrics, point the exporter at PostHog. No PostHog packages required.
+
+
+
+
+
+The key requirements are:
+- Use OTLP (OpenTelemetry Protocol) for metrics export over HTTP
+- Send metrics to your Metrics endpoint (see configuration step below)
+- Include your project token in the Authorization header or as a `?token=` query parameter
+
+Find the OpenTelemetry SDK for your language in the [official registry](https://opentelemetry.io/ecosystem/registry/). If you already run an OpenTelemetry Collector, you can add PostHog as an additional exporter without touching application code.
+
+
+
+
+
+You'll need your PostHog project token to authenticate metrics requests. This is the same key you use for capturing events and exceptions 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](https://app.posthog.com/settings).
+
+
+
+
+
+Most OpenTelemetry SDKs pick up standard environment variables, so configuration is often no more than:
+
+```bash
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="/i/v1/metrics"
+OTEL_EXPORTER_OTLP_METRICS_HEADERS="Authorization=Bearer "
+OTEL_SERVICE_NAME="my-app"
+```
+
+Set `OTEL_SERVICE_NAME` so metrics from different systems stay easy to tell apart. It's attached to every series and used by the Metrics UI for filtering.
+
+If you configure the exporter in code instead:
+
+**Endpoint:**
+
+```
+/i/v1/metrics
+```
+
+**Authentication:** Include your project token either as an `Authorization` header:
+
+```
+Authorization: Bearer
+```
+
+Or as a query parameter on the endpoint:
+
+```
+/i/v1/metrics?token=
+```
+
+
+
+
+
+1. Trigger the code path that records a metric
+2. Open **Metrics** in the PostHog sidebar and pick your metric from the name picker
+3. Data points should appear within a minute of sending
+
+If nothing shows up, check that the endpoint ends in `/i/v1/metrics`, that the token starts with `phc_`, and see the [troubleshooting section](/docs/metrics#troubleshooting).
+
+
+View your metrics in PostHog
+
+
+
+
+
+
+
diff --git a/contents/docs/metrics/installation/python.mdx b/contents/docs/metrics/installation/python.mdx
new file mode 100644
index 000000000000..4c8fdcf2e26e
--- /dev/null
+++ b/contents/docs/metrics/installation/python.mdx
@@ -0,0 +1,95 @@
+---
+title: Python metrics installation
+platformLogo: python
+showStepsToc: true
+---
+
+import { Steps, Step } from 'components/Docs/Steps'
+import MetricsNextSteps from './_snippets/metrics-next-steps.mdx'
+
+> **Note:** Metrics is in alpha. Setup details may change before general availability.
+
+The [posthog-python](/docs/libraries/python) SDK includes the `posthog.metrics` API, so you can record metrics with the same client you use for events and feature flags.
+
+
+
+
+
+```bash
+pip install posthog
+```
+
+Metrics requires an up-to-date SDK version, so upgrade if you're on an older release.
+
+
+
+
+
+Set a service name so metrics from different systems stay easy to tell apart. It's attached to every series and used by the Metrics UI for filtering.
+
+```python
+from posthog import Posthog
+
+posthog = Posthog(
+ "",
+ host="",
+ metrics={"service_name": "billing-worker"},
+)
+```
+
+Use your **project token** (the same one you use for capturing events), not a [personal API key](/docs/api#authentication).
+
+
+
+
+
+Use the metric type that matches what you're measuring:
+
+```python
+# Counters only go up: things you count
+posthog.metrics.count("invoices.processed", 1, attributes={"plan": "pro"})
+
+# Gauges go up and down: current values
+posthog.metrics.gauge("queue.depth", 42)
+
+# Histograms record distributions: durations, sizes
+posthog.metrics.histogram("job.duration", 187, unit="ms")
+```
+
+The client is thread-safe and pre-aggregates: samples fold into per-series aggregates in memory and flush as one OTLP data point per series every few seconds, so recording in hot paths is cheap. A burst of 10k `count()` calls costs one data point on the wire.
+
+Keep attribute values small and bounded: `route`, `status`, and `plan` are good attributes; user IDs, session IDs, and request IDs are not. Every unique combination creates a new series.
+
+
+
+
+
+If your service already records metrics with Prometheus, StatsD, or another system, don't rip it out. Add the PostHog call next to the existing one, reusing the same metric name and attributes, so both systems chart the same series while you evaluate.
+
+
+
+
+
+For short-lived processes (cron jobs, CLIs, serverless functions), flush before exiting so the last aggregation window isn't lost:
+
+```python
+posthog.metrics.flush()
+```
+
+
+
+
+
+1. Trigger the code path that records a metric
+2. Open **Metrics** in the PostHog sidebar and pick your metric from the name picker
+3. Data points should appear within a minute of sending
+
+
+View your metrics in PostHog
+
+
+
+
+
+
+
diff --git a/contents/docs/metrics/start-here.mdx b/contents/docs/metrics/start-here.mdx
index 37154de4088e..905a1b941a28 100644
--- a/contents/docs/metrics/start-here.mdx
+++ b/contents/docs/metrics/start-here.mdx
@@ -36,7 +36,7 @@ OTEL_SERVICE_NAME="my-app"
`` and `` are filled in with your project's values when you're logged in. Use your **project token** (the same one you use for capturing events), not a [personal API key](/docs/api#authentication).
-For full setup details, including Python and Node.js code samples and Collector configuration, see the [metrics overview](/docs/metrics).
+For per-platform setup, including the `posthog.metrics` API in [Node.js](/docs/metrics/installation/nodejs) and [Python](/docs/metrics/installation/python), see the [installation guides](/docs/metrics/installation).
diff --git a/src/navs/index.js b/src/navs/index.js
index 7e1db9a58bc5..71d1f9137baa 100644
--- a/src/navs/index.js
+++ b/src/navs/index.js
@@ -7382,6 +7382,20 @@ export const docsMenu = {
color: 'orange',
featured: true,
},
+ {
+ name: 'Install metrics',
+ url: '/docs/metrics/installation',
+ icon: 'IconCode',
+ color: 'blue',
+ featured: true,
+ children: [
+ { name: 'Overview', url: '/docs/metrics/installation' },
+ { name: 'JavaScript (web)', url: '/docs/metrics/installation/javascript' },
+ { name: 'Node.js', url: '/docs/metrics/installation/nodejs' },
+ { name: 'Python', url: '/docs/metrics/installation/python' },
+ { name: 'Other languages', url: '/docs/metrics/installation/other' },
+ ],
+ },
{
name: 'Why you need metrics',
url: '/docs/metrics/basics',