feat(python): Document metrics (#15299)

Document trace-connected metrics use in the Python SDK.

Author: alexander-alderman-webb

docs/platforms/python/metrics/index.mdx

@@ -0,0 +1,34 @@
+---
+title: Set Up Metrics
+sidebar_title: Metrics
+description: "Metrics allow you to send, view and query counters, gauges and measurements sent from your applications within Sentry."
+sidebar_order: 5755
+---
+
+<Alert>
+
+This feature is currently in limited beta. Please reach out on [GitHub](https://github.com/getsentry/sentry-python/discussions/5042) if you have feedback or questions. Features in beta are still in-progress and may have bugs. We recognize the irony.
+
+</Alert>
+
+With Sentry Metrics, you can send counters, gauges and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.
+
+## Requirements
+
+<PlatformContent includePath="metrics/requirements" />
+
+## Setup
+
+<PlatformContent includePath="metrics/setup" />
+
+## Usage
+
+<PlatformContent includePath="metrics/usage" />
+
+## Options
+
+<PlatformContent includePath="metrics/options" />
+
+## Default Attributes
+
+<PlatformContent includePath="metrics/default-attributes" />

includes/metrics/default-attributes/core.mdx

@@ -0,0 +1,7 @@
+### Core Attributes
+
+- `environment`: The environment set in the SDK if defined. This is sent from the SDK as `sentry.environment`.
+- `release`: The release set in the SDK if defined. This is sent from the SDK as `sentry.release`.
+- `trace.parent_span_id`: The span ID of the span that was active when the metric was collected (only set if there was an active span). This is sent from the SDK as `sentry.trace.parent_span_id`.
+- `sdk.name`: The name of the SDK that sent the metric. This is sent from the SDK as `sentry.sdk.name`.
+- `sdk.version`: The version of the SDK that sent the metric. This is sent from the SDK as `sentry.sdk.version`.

includes/metrics/default-attributes/server.mdx

@@ -0,0 +1,3 @@
+### Server Attributes
+
+- `server.address`: The address of the server that sent the metric. Equivalent to `server_name` that gets attached to Sentry errors.

includes/metrics/default-attributes/user.mdx

@@ -0,0 +1,7 @@
+### User Attributes
+
+If user information is available in the current scope, the following attributes are added to the metric:
+
+- `user.id`: The user ID.
+- `user.name`: The username.
+- `user.email`: The email address.

platform-includes/metrics/default-attributes/python.mdx

@@ -0,0 +1,7 @@
+The Python SDK automatically sets several default attributes on all metrics to provide context and improve debugging:
+
+<Include name="metrics/default-attributes/core" />
+
+<Include name="metrics/default-attributes/server" />
+
+<Include name="metrics/default-attributes/user" />

platform-includes/metrics/options/python.mdx

@@ -0,0 +1,36 @@
+#### before_send_metric
+
+To filter metrics, or update them before they are sent to Sentry, you can use the `before_send_metric` option.
+
+```python
+import sentry_sdk
+from sentry_sdk.types import Metric, Hint
+from typing import Optional
+
+def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]:
+    # Filter out all failed checkouts on the acme tenant
+    if metric["name"] == "checkout.failed" and metric["attributes"].get("tenant") == "acme":
+        return None
+
+    return metric
+
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    _experiments={
+        "enable_metrics": True,
+        "before_send_metric": before_metric,
+    },
+)
+```
+
+The `before_send_metric` function receives a metric object, and should return the metric object if you want it to be sent to Sentry, or `None` if you want to discard it.
+
+The metric dict has the following keys:
+
+- `name`: (`str`) The name of the metric.
+- `type`: (`str` - one of `counter`, `gauge`, `distribution`) The type of metric.
+- `value`: (`float`) The numeric value of the metric.
+- `unit`: (`int`) The unit of measurement for the metric value.
+- `attributes`: (`dict[str, str | bool | float | int]`) Additional attributes to be sent with the metric.
+- `timestamp`: (`float`) Timestamp in seconds (epoch time) indicating when the metric was recorded.
+- `trace_id`: (`Optional[str]`) The trace ID of the trace this metric belongs to.

platform-includes/metrics/requirements/python.mdx

@@ -0,0 +1,9 @@
+Metrics for Python are supported in Sentry Python SDK version `2.43.0` and above.
+
+```bash {tabTitle:pip}
+pip install "sentry-sdk"
+```
+
+```bash {tabTitle:uv}
+uv add "sentry-sdk"
+```

platform-includes/metrics/setup/python.mdx

@@ -0,0 +1,10 @@
+To enable metrics, you need to initialize the SDK with the `enable_metrics` option set to `True`.
+
+```python
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    _experiments={
+        enable_metrics: True,
+    },
+)
+```

platform-includes/metrics/usage/python.mdx

@@ -0,0 +1,27 @@
+Once the feature is enabled on the SDK and the SDK is initialized, you can send metrics using the `sentry_sdk.metrics` APIs.
+
+The `metrics` namespace exposes three methods that you can use to capture different types of metric information: `count`, `gauge`, and `distribution`.
+
+```python
+from sentry_sdk import metrics
+
+metrics.count("checkout.failed", 1)
+metrics.gauge("queue.depth", 42)
+metrics.distribution("cart.amount_usd", 187.5)
+```
+
+You can also pass additional attributes directly to `count`, `gauge`, and `distribution` via the `attributes` kwarg.
+
+```python
+from sentry_sdk import metrics
+
+metrics.count(
+    "checkout.failed",
+    1,
+    attributes={
+        "route": "/checkout",
+        "tenant": "acme",
+        "provider": "stripe",
+    },
+)
+```

src/middleware.ts

@@ -1766,10 +1766,6 @@ const USER_DOCS_REDIRECTS: Redirect[] = [
     to: '/platforms/javascript/guides/:guide/opentelemetry/',
   },
   // START redirecting deprecated generic metrics docs to concepts
-  {
-    from: '/platforms/python/metrics/',
-    to: '/platforms/python/tracing/span-metrics/',
-  },
   {
     from: '/platforms/ruby/metrics/',
     to: '/concepts/key-terms/tracing/span-metrics/',