feat(python): Document metrics

Author: alexander-alderman-webb

docs/platforms/python/metrics/index.mdx

@@ -0,0 +1,28 @@
+---
+title: Set Up Metrics
+sidebar_title: Metrics
+description: "Metrics allow you to send, view and query counts and measurements sent from your applications within Sentry."
+sidebar_order: 5755
+---
+
+With Sentry Metrics, you can send numeric counts and measurements from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors.
+
+## 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="logs/default-attributes/core" />
+
+<Include name="logs/default-attributes/server" />
+
+<Include name="logs/default-attributes/user" />

platform-includes/metrics/options/python.mdx

@@ -0,0 +1,35 @@
+#### before_send_log
+
+To filter logs, 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 info level logs
+    if log["severity_text"] == "info":
+        return None
+    return log
+
+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 log.
+- `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 `-.-.-` 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,26 @@
+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("test.counter", 1)
+metrics.gauge("test.gauge", 42)
+metrics.distribution("test.distribution", 200)
+```
+
+You can also pass additional attributes directly to `count`, `gauge`, and `distribution` via the `attributes` kwarg.
+
+```python
+from sentry_sdk import metrics
+
+metrics.count(
+    "test.counter",
+    1,
+    attributes={
+        "endpoint": "/api/test",
+        "status": "success"
+    },
+)
+```