From 9e2cb1b1643b01d929c10163409121716f1ce382 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 19 Nov 2025 10:08:41 +0100 Subject: [PATCH 1/6] feat(python): Illustrate types of metrics --- docs/platforms/python/metrics/index.mdx | 4 +- platform-includes/metrics/options/python.mdx | 10 ++- platform-includes/metrics/usage/python.mdx | 66 +++++++++++++++----- 3 files changed, 61 insertions(+), 19 deletions(-) diff --git a/docs/platforms/python/metrics/index.mdx b/docs/platforms/python/metrics/index.mdx index dee9d349e62a22..ced271596cc89a 100644 --- a/docs/platforms/python/metrics/index.mdx +++ b/docs/platforms/python/metrics/index.mdx @@ -11,7 +11,9 @@ This feature is currently in open beta. Please reach out on [GitHub](https://git -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. +Sentry metrics help you pinpoint and solve issues that impact user experience and app performance by measuring the data points that are important to you. You can track things like processing time, event size, user signups, and conversion rates, then correlate them back to tracing data in order to get deeper insights and solve issues faster. + +Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes. ## Requirements diff --git a/platform-includes/metrics/options/python.mdx b/platform-includes/metrics/options/python.mdx index bb6fd7b0b230ad..6920e6d159fd59 100644 --- a/platform-includes/metrics/options/python.mdx +++ b/platform-includes/metrics/options/python.mdx @@ -2,16 +2,20 @@ To filter metrics, or update them before they are sent to Sentry, you can use the `before_send_metric` option. +The `before_send_metric` argument is a callback function that is called before a metric is emitted. If the callback returns `None`, the metric is not emitted. Attributes can also be updated in the callback function. + ```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": +def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]:t + if metric["name"] == "removed-metric": return None + metric["attributes"]["extra"] = "foo" + del metric["attributes"]["release"] + return metric sentry_sdk.init( diff --git a/platform-includes/metrics/usage/python.mdx b/platform-includes/metrics/usage/python.mdx index 2e9553cd068433..97182e21a95960 100644 --- a/platform-includes/metrics/usage/python.mdx +++ b/platform-includes/metrics/usage/python.mdx @@ -2,26 +2,62 @@ Once the feature is enabled on the SDK and the SDK is initialized, you can send The `metrics` namespace exposes three methods that you can use to capture different types of metric information: `count`, `gauge`, and `distribution`. +## Emit a Counter + +Counters are one of the more basic types of metrics and can be used to count certain event occurrences. + +To emit a counter, do the following: + ```python -from sentry_sdk import metrics +import sentry_sdk -metrics.count("checkout.failed", 1) -metrics.gauge("queue.depth", 42) -metrics.distribution("cart.amount_usd", 187.5) +# Increment a counter by one for each button click. +sentry_sdk.metrics.count( + name="button_click", + value=1, + attributes={ + "browser": "Firefox", + "app_version": "1.0.0" + }, +) ``` -You can also pass additional attributes directly to `count`, `gauge`, and `distribution` via the `attributes` kwarg. +## Emit a Distribution + +Distributions help you get the most insights from your data by allowing you to obtain aggregations such as `p90`, `min`, `max`, and `avg`. + +To emit a distribution, do the following: ```python -from sentry_sdk import metrics - -metrics.count( - "checkout.failed", - 1, - attributes={ - "route": "/checkout", - "tenant": "acme", - "provider": "stripe", - }, +import sentry_sdk + +# Add '15.0' to a distribution used for tracking the loading times per page. +sentry_sdk.metrics.distribution( + name="page_load", + value=15.0, + unit="millisecond", + attributes={ + "page": "/home" + }, +) +``` + +## Emit a Gauge + +Gauges let you obtain aggregates like `min`, `max`, `avg`, `sum`, and `count`. They can be represented in a more space-efficient way than distributions, but they can't be used to get percentiles. If percentiles aren't important to you, we recommend using gauges. + +To emit a gauge, do the following: + +```python +import sentry_sdk + +# Add '15.0' to a gauge used for tracking the loading times for a page. +sentry_sdk.metrics.gauge( + name="page_load", + value=15.0, + unit="millisecond", + attributes={ + "page": "/home" + }, ) ``` From 528fbbb13a485fafd888c9c57f49995859ef807e Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 19 Nov 2025 10:26:41 +0100 Subject: [PATCH 2/6] . --- platform-includes/metrics/options/python.mdx | 4 +++- platform-includes/metrics/usage/python.mdx | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/platform-includes/metrics/options/python.mdx b/platform-includes/metrics/options/python.mdx index 6920e6d159fd59..3c21e41b84a26d 100644 --- a/platform-includes/metrics/options/python.mdx +++ b/platform-includes/metrics/options/python.mdx @@ -14,7 +14,9 @@ def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]:t return None metric["attributes"]["extra"] = "foo" - del metric["attributes"]["release"] + + if "browser" in metric["attributes"]: + del metric["attributes"]["browser"] return metric diff --git a/platform-includes/metrics/usage/python.mdx b/platform-includes/metrics/usage/python.mdx index 97182e21a95960..b778e9295d5fd7 100644 --- a/platform-includes/metrics/usage/python.mdx +++ b/platform-includes/metrics/usage/python.mdx @@ -11,10 +11,10 @@ To emit a counter, do the following: ```python import sentry_sdk -# Increment a counter by one for each button click. +# Record five total button clicks sentry_sdk.metrics.count( name="button_click", - value=1, + value=5, attributes={ "browser": "Firefox", "app_version": "1.0.0" From eed08093d3fb853dd8704ddf5ce8a33fb3bc7ec9 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 19 Nov 2025 10:27:22 +0100 Subject: [PATCH 3/6] . --- platform-includes/metrics/options/python.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/metrics/options/python.mdx b/platform-includes/metrics/options/python.mdx index 3c21e41b84a26d..7616691e96ef00 100644 --- a/platform-includes/metrics/options/python.mdx +++ b/platform-includes/metrics/options/python.mdx @@ -9,7 +9,7 @@ import sentry_sdk from sentry_sdk.types import Metric, Hint from typing import Optional -def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]:t +def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]: if metric["name"] == "removed-metric": return None From a2d4b4683e089d69e5de6d26db3d32589015150c Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 19 Nov 2025 10:40:14 +0100 Subject: [PATCH 4/6] . --- platform-includes/metrics/options/python.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/metrics/options/python.mdx b/platform-includes/metrics/options/python.mdx index 7616691e96ef00..be4f30009356c6 100644 --- a/platform-includes/metrics/options/python.mdx +++ b/platform-includes/metrics/options/python.mdx @@ -9,7 +9,7 @@ import sentry_sdk from sentry_sdk.types import Metric, Hint from typing import Optional -def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]: +def before_metric(metric: Metric, hint: Hint) -> Optional[Metric]: if metric["name"] == "removed-metric": return None From f0f2e3003336bbdded266676b824e7bb99434f90 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 19 Nov 2025 11:21:20 +0100 Subject: [PATCH 5/6] merge before send metric paragraphs --- platform-includes/metrics/options/python.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/platform-includes/metrics/options/python.mdx b/platform-includes/metrics/options/python.mdx index be4f30009356c6..a6664900959354 100644 --- a/platform-includes/metrics/options/python.mdx +++ b/platform-includes/metrics/options/python.mdx @@ -1,8 +1,6 @@ #### before_send_metric -To filter metrics, or update them before they are sent to Sentry, you can use the `before_send_metric` option. - -The `before_send_metric` argument is a callback function that is called before a metric is emitted. If the callback returns `None`, the metric is not emitted. Attributes can also be updated in the callback function. +To filter metrics, or update them before they are sent to Sentry, you can use the `before_send_metric` option. If the callback returns `None`, the metric is not emitted. Attributes can also be updated in the callback function. ```python import sentry_sdk From 3e181d2c59de44d0a7ea32176716916f69adb93d Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Wed, 19 Nov 2025 11:30:38 +0100 Subject: [PATCH 6/6] argument style --- platform-includes/metrics/usage/python.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/platform-includes/metrics/usage/python.mdx b/platform-includes/metrics/usage/python.mdx index b778e9295d5fd7..51b1d37ddb8c07 100644 --- a/platform-includes/metrics/usage/python.mdx +++ b/platform-includes/metrics/usage/python.mdx @@ -13,8 +13,8 @@ import sentry_sdk # Record five total button clicks sentry_sdk.metrics.count( - name="button_click", - value=5, + "button_click", + 5, attributes={ "browser": "Firefox", "app_version": "1.0.0" @@ -33,8 +33,8 @@ import sentry_sdk # Add '15.0' to a distribution used for tracking the loading times per page. sentry_sdk.metrics.distribution( - name="page_load", - value=15.0, + "page_load", + 15.0, unit="millisecond", attributes={ "page": "/home" @@ -53,8 +53,8 @@ import sentry_sdk # Add '15.0' to a gauge used for tracking the loading times for a page. sentry_sdk.metrics.gauge( - name="page_load", - value=15.0, + "page_load", + 15.0, unit="millisecond", attributes={ "page": "/home"