diff --git a/docs/platforms/python/metrics/index.mdx b/docs/platforms/python/metrics/index.mdx new file mode 100644 index 0000000000000..f363173e3ea51 --- /dev/null +++ b/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 +--- + + + +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. + + + +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 + + + +## Setup + + + +## Usage + + + +## Options + + + +## Default Attributes + + diff --git a/includes/metrics/default-attributes/core.mdx b/includes/metrics/default-attributes/core.mdx new file mode 100644 index 0000000000000..6d5523b05538a --- /dev/null +++ b/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`. diff --git a/includes/metrics/default-attributes/server.mdx b/includes/metrics/default-attributes/server.mdx new file mode 100644 index 0000000000000..537849aab220b --- /dev/null +++ b/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. diff --git a/includes/metrics/default-attributes/user.mdx b/includes/metrics/default-attributes/user.mdx new file mode 100644 index 0000000000000..3dd200514a22a --- /dev/null +++ b/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. diff --git a/platform-includes/metrics/default-attributes/python.mdx b/platform-includes/metrics/default-attributes/python.mdx new file mode 100644 index 0000000000000..f3ee0a14b486a --- /dev/null +++ b/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: + + + + + + diff --git a/platform-includes/metrics/options/python.mdx b/platform-includes/metrics/options/python.mdx new file mode 100644 index 0000000000000..c4b1065a903ce --- /dev/null +++ b/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. diff --git a/platform-includes/metrics/requirements/python.mdx b/platform-includes/metrics/requirements/python.mdx new file mode 100644 index 0000000000000..2761e66ebf0a0 --- /dev/null +++ b/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" +``` diff --git a/platform-includes/metrics/setup/python.mdx b/platform-includes/metrics/setup/python.mdx new file mode 100644 index 0000000000000..2f6c90d04b9a9 --- /dev/null +++ b/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, + }, +) +``` diff --git a/platform-includes/metrics/usage/python.mdx b/platform-includes/metrics/usage/python.mdx new file mode 100644 index 0000000000000..2e9553cd06843 --- /dev/null +++ b/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", + }, +) +``` diff --git a/src/middleware.ts b/src/middleware.ts index 19ed89f303fcf..6a2ceaa9d20d8 100644 --- a/src/middleware.ts +++ b/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/',