docs(metrics): add per-platform installation guides for posthog.metrics

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
 

contents/docs/metrics/installation/_snippets/metrics-next-steps.mdx

@@ -0,0 +1,15 @@
+<Step checkpoint title="Next steps" subtitle="What you can do with your metrics">
+
+| 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 |
+
+<CallToAction type="primary" to="/docs/metrics/start-here">
+Continue with the getting started guide
+</CallToAction>
+
+</Step>

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

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.
+
+<Steps>
+
+<Step title="Install posthog-js" badge="required">
+
+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('<ph_project_api_key>', {
+    api_host: '<ph_client_api_host>',
+    metrics: {
+        serviceName: 'storefront-web',
+        environment: 'production',
+    },
+})
+```
+
+</Step>
+
+<Step title="Record metrics" badge="required">
+
+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.
+
+</Step>
+
+<Step title="Instrument alongside existing metrics" badge="optional">
+
+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.
+
+</Step>
+
+<Step title="Test your setup" badge="recommended">
+
+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
+
+<CallToAction type="primary" to="https://app.posthog.com/metrics">
+View your metrics in PostHog
+</CallToAction>
+
+</Step>
+
+<MetricsNextSteps />
+
+</Steps>

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.
+
+<Steps>
+
+<Step title="Install posthog-node" badge="required">
+
+```bash
+npm install posthog-node
+```
+
+Metrics requires an up-to-date SDK version, so upgrade if you're on an older release.
+
+</Step>
+
+<Step title="Initialize the client" badge="required">
+
+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('<ph_project_token>', {
+    host: '<ph_client_api_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).
+
+</Step>
+
+<Step title="Record metrics" badge="required">
+
+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.
+
+</Step>
+
+<Step title="Instrument alongside existing metrics" badge="optional">
+
+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.
+
+</Step>
+
+<Step title="Flush before exit" badge="required">
+
+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()
+```
+
+</Step>
+
+<Step title="Test your setup" badge="recommended">
+
+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
+
+<CallToAction type="primary" to="https://app.posthog.com/metrics">
+View your metrics in PostHog
+</CallToAction>
+
+</Step>
+
+<MetricsNextSteps />
+
+</Steps>

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.
+
+<Steps>
+
+<Step title="Install OpenTelemetry packages" badge="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.
+
+</Step>
+
+<Step title="Get your project token" badge="required">
+
+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).
+
+</Step>
+
+<Step title="Configure the exporter" badge="required">
+
+Most OpenTelemetry SDKs pick up standard environment variables, so configuration is often no more than:
+
+```bash
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="<ph_client_api_host>/i/v1/metrics"
+OTEL_EXPORTER_OTLP_METRICS_HEADERS="Authorization=Bearer <ph_project_token>"
+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:**
+
+```
+<ph_client_api_host>/i/v1/metrics
+```
+
+**Authentication:** Include your project token either as an `Authorization` header:
+
+```
+Authorization: Bearer <ph_project_token>
+```
+
+Or as a query parameter on the endpoint:
+
+```
+<ph_client_api_host>/i/v1/metrics?token=<ph_project_token>
+```
+
+</Step>
+
+<Step title="Test your setup" badge="recommended">
+
+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).
+
+<CallToAction type="primary" to="https://app.posthog.com/metrics">
+View your metrics in PostHog
+</CallToAction>
+
+</Step>
+
+<MetricsNextSteps />
+
+</Steps>