From b32cdbb4591bbd76bd0eb6fcef54e678faf85ef9 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 21 Jul 2026 12:02:28 +0200 Subject: [PATCH 1/3] add Attributes page --- .../enriching-events/attributes/index.mdx | 124 ++++++++++++++++++ .../python/enriching-events/tags/index.mdx | 8 +- platform-includes/logs/usage/python.mdx | 15 +++ platform-includes/metrics/usage/python.mdx | 25 ++++ 4 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 docs/platforms/python/enriching-events/attributes/index.mdx diff --git a/docs/platforms/python/enriching-events/attributes/index.mdx b/docs/platforms/python/enriching-events/attributes/index.mdx new file mode 100644 index 00000000000000..1e7fba10548659 --- /dev/null +++ b/docs/platforms/python/enriching-events/attributes/index.mdx @@ -0,0 +1,124 @@ +--- +title: Attributes +description: "Attributes automatically enrich your telemetry with typed key-value data. Use them to add business context that you can filter and search in Sentry." +--- + + + +**Attributes** are key-value pairs you can attach to your telemetry (like spans, logs, and metrics). + +Common uses include subscription tier, feature flags, or any business context that helps you filter and query your telemetry. + +Attribute values can be `str`, `int`, `float`, or `bool`, as well as arrays of these types. + + + +Attributes on spans require stream mode (SDK version `2.62.0`+). In stream mode, spans have no contexts, data, or tags — everything is an attribute, so `set_data()`, `set_tag()`, and `set_context()` are replaced by `set_attribute()` and `set_attributes()`. + +Attributes on logs and metrics don't require stream mode — they work regardless of your `trace_lifecycle` setting. + + + +## Add Attributes to a Scope + +Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that are automatically included on all logs and metrics — and, in stream mode, on all spans. These write to the isolation scope, so they apply for the current request or session: + +```python +import sentry_sdk + +sentry_sdk.set_attributes({ + "org_id": user.org_id, + "user_tier": user.tier, +}) +sentry_sdk.set_attribute("service", "checkout") +``` + +To attach attributes more broadly or more narrowly, set them on a specific scope instead: + +```python +import sentry_sdk + +# Global scope — applies to every event for the life of the app +sentry_sdk.get_global_scope().set_attribute("app.version", "1.2.3") + +# Current scope — applies only within this block +with sentry_sdk.new_scope() as scope: + scope.set_attribute("checkout.step", "payment") + sentry_sdk.logger.info("Processing payment") +``` + +See Scopes for more on the global, isolation, and current scopes. + +## Setting Attributes on Individual Telemetry + +You can also attach attributes to a single span, log, or metric directly, which is useful when the data only makes sense for that one item. + +### Spans + +In stream mode, you can set attributes when starting a span: + +```python +import sentry_sdk + +with sentry_sdk.traces.start_span( + name="process-order", + attributes={ + "sentry.op": "queue.process", + "order.id": "abc-123", + "order.item_count": 5, + "order.priority": True, + }, +): + process_order() +``` + +Or add them to an already running span: + +```python +import sentry_sdk + +with sentry_sdk.traces.start_span(name="handle-request") as span: + span.set_attribute("http.response.status_code", 200) + + span.set_attributes({ + "http.route": "/api/users", + "user.id": "user-42", + }) +``` + +See Add Span Attributes for more. + +### Logs + +Pass attributes to any `sentry_sdk.logger` call via the `attributes` kwarg: + +```python +sentry_sdk.logger.error( + "Payment processing failed", + attributes={ + "payment.provider": "stripe", + "payment.method": "credit_card", + } +) +``` + +See Logs for more. + +### Metrics + +Pass attributes in the `attributes` parameter of any metric: + +```python +import sentry_sdk + +sentry_sdk.metrics.count( + "button_click", + 5, + attributes={ + "browser": "Firefox", + "app_version": "1.0.0" + }, +) +``` + +See Application Metrics for more. diff --git a/docs/platforms/python/enriching-events/tags/index.mdx b/docs/platforms/python/enriching-events/tags/index.mdx index 68ac3216e2585b..ad9085a0484f49 100644 --- a/docs/platforms/python/enriching-events/tags/index.mdx +++ b/docs/platforms/python/enriching-events/tags/index.mdx @@ -5,7 +5,13 @@ description: "Tags power UI features such as filters and tag-distribution maps. **Tags** are key/value string pairs that are both indexed and searchable. Tags power features in sentry.io such as filters and tag-distribution maps. Tags also help you quickly both access related events and view the tag distribution for a set of events. Common uses for tags include hostname, platform version, and user language. -We’ll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the number of distinct tags and can assist you in determining hotspots for various issues. +We'll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the number of distinct tags and can assist you in determining hotspots for various issues. + + + +Tags are **not** applied to logs, metrics, or spans in stream mode. If you want to attach that data to logs, metrics, or spans in stream mode, use Attributes instead. + + _Tag keys_ have a maximum length of 200 characters and can contain only letters (`a-zA-Z`), numbers (`0-9`), underscores (`_`), periods (`.`), colons (`:`), and dashes (`-`). diff --git a/platform-includes/logs/usage/python.mdx b/platform-includes/logs/usage/python.mdx index ad073e66a0c60c..ad9e2892661d46 100644 --- a/platform-includes/logs/usage/python.mdx +++ b/platform-includes/logs/usage/python.mdx @@ -36,3 +36,18 @@ sentry_sdk.logger.error( Attribute values should be primitives — strings, numbers, or booleans. Sentry's log storage only retains these scalar types, so other values are handled inconsistently. A `list` or `tuple` of same-typed scalars (for example `[1, 2, 3]`) is sent as an array, which is **not currently stored** and shows up empty in the Logs UI. Mixed lists and `dict`s are stored as their string representation. To keep a complex value searchable, serialize it to a string before logging, for example `json.dumps(workflow_ids)`. + +### Shared Attributes + +Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that are automatically included on all logs (and metrics). These write to the isolation scope, so they apply for the current request or session: + +```python +import sentry_sdk + +sentry_sdk.set_attributes({ + "org_id": user.org_id, + "user_tier": user.tier, +}) +``` + +To target a broader or narrower scope instead, see Attributes. diff --git a/platform-includes/metrics/usage/python.mdx b/platform-includes/metrics/usage/python.mdx index 546d77c4711f59..aa9673ac7c61db 100644 --- a/platform-includes/metrics/usage/python.mdx +++ b/platform-includes/metrics/usage/python.mdx @@ -61,3 +61,28 @@ sentry_sdk.metrics.gauge( }, ) ``` + +## Attributes + +Attributes let you filter and group metrics in Sentry. Use them for: + +- Environment segmentation +- Feature flag tracking +- User tier analysis + +You've already seen attributes passed directly to individual metric calls in the examples above. See Attributes for more information on how attributes work across spans, logs, and metrics. + +### Shared Attributes + +Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that apply to all metrics (and logs). These write to the isolation scope, so they apply for the current request or session: + +```python +import sentry_sdk + +sentry_sdk.set_attributes({ + "is_admin": True, + "auth_provider": "google", +}) +``` + +To target a broader or narrower scope instead, see Attributes. From df144c0f4545037cec086e7a783ac50302693b89 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 21 Jul 2026 12:19:50 +0200 Subject: [PATCH 2/3] update wording on logs and metrics pages --- platform-includes/logs/usage/python.mdx | 2 +- platform-includes/metrics/usage/python.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/platform-includes/logs/usage/python.mdx b/platform-includes/logs/usage/python.mdx index ad9e2892661d46..df058da93be0fd 100644 --- a/platform-includes/logs/usage/python.mdx +++ b/platform-includes/logs/usage/python.mdx @@ -39,7 +39,7 @@ Attribute values should be primitives — strings, numbers, or booleans. Sentry' ### Shared Attributes -Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that are automatically included on all logs (and metrics). These write to the isolation scope, so they apply for the current request or session: +Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that are automatically included on all logs, metrics, and spans (only in stream mode). These write to the isolation scope, so they apply for the current request or session: ```python import sentry_sdk diff --git a/platform-includes/metrics/usage/python.mdx b/platform-includes/metrics/usage/python.mdx index aa9673ac7c61db..a1c9c243d688ce 100644 --- a/platform-includes/metrics/usage/python.mdx +++ b/platform-includes/metrics/usage/python.mdx @@ -74,7 +74,7 @@ You've already seen attributes passed directly to individual metric calls in the ### Shared Attributes -Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that apply to all metrics (and logs). These write to the isolation scope, so they apply for the current request or session: +Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that apply to all logs, metrics, and spans (only in stream mode). These write to the isolation scope, so they apply for the current request or session: ```python import sentry_sdk From 405f07f10a55464541cbfab5e5be61ef91645fb8 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Wed, 22 Jul 2026 09:20:35 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Ivana Kellyer --- .../python/enriching-events/attributes/index.mdx | 8 +++----- platform-includes/logs/usage/python.mdx | 8 +++----- platform-includes/metrics/usage/python.mdx | 8 +++----- 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/platforms/python/enriching-events/attributes/index.mdx b/docs/platforms/python/enriching-events/attributes/index.mdx index 1e7fba10548659..00ab7e83c2307e 100644 --- a/docs/platforms/python/enriching-events/attributes/index.mdx +++ b/docs/platforms/python/enriching-events/attributes/index.mdx @@ -21,15 +21,13 @@ Attributes on logs and metrics don't require stream mode — they work regardles ## Add Attributes to a Scope -Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that are automatically included on all logs and metrics — and, in stream mode, on all spans. These write to the isolation scope, so they apply for the current request or session: +Use `sentry_sdk.set_attribute` to attach attributes that are automatically included on all logs and metrics — and, in stream mode, on all spans. These write to the isolation scope, so they apply for the current request or session: ```python import sentry_sdk -sentry_sdk.set_attributes({ - "org_id": user.org_id, - "user_tier": user.tier, -}) +sentry_sdk.set_attribute("org_id", user.org_id) +sentry_sdk.set_attribute("user_tier", user.tier) sentry_sdk.set_attribute("service", "checkout") ``` diff --git a/platform-includes/logs/usage/python.mdx b/platform-includes/logs/usage/python.mdx index df058da93be0fd..0a0b21633b64ea 100644 --- a/platform-includes/logs/usage/python.mdx +++ b/platform-includes/logs/usage/python.mdx @@ -39,15 +39,13 @@ Attribute values should be primitives — strings, numbers, or booleans. Sentry' ### Shared Attributes -Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that are automatically included on all logs, metrics, and spans (only in stream mode). These write to the isolation scope, so they apply for the current request or session: +Use `sentry_sdk.set_attribute` to attach attributes that are automatically included on all logs, metrics, and spans (only in stream mode). These write to the isolation scope, so they apply for the current request or session: ```python import sentry_sdk -sentry_sdk.set_attributes({ - "org_id": user.org_id, - "user_tier": user.tier, -}) +sentry_sdk.set_attribute("org_id", user.org_id) +sentry_sdk.set_attribute("user_tier", user.tier) ``` To target a broader or narrower scope instead, see Attributes. diff --git a/platform-includes/metrics/usage/python.mdx b/platform-includes/metrics/usage/python.mdx index a1c9c243d688ce..ca8ab34869d8ba 100644 --- a/platform-includes/metrics/usage/python.mdx +++ b/platform-includes/metrics/usage/python.mdx @@ -74,15 +74,13 @@ You've already seen attributes passed directly to individual metric calls in the ### Shared Attributes -Use `sentry_sdk.set_attribute` and `sentry_sdk.set_attributes` to attach attributes that apply to all logs, metrics, and spans (only in stream mode). These write to the isolation scope, so they apply for the current request or session: +Use `sentry_sdk.set_attribute` to attach attributes that apply to all logs, metrics, and spans (only in stream mode). These write to the isolation scope, so they apply for the current request or session: ```python import sentry_sdk -sentry_sdk.set_attributes({ - "is_admin": True, - "auth_provider": "google", -}) +sentry_sdk.set_attribute("is_admin", True) +sentry_sdk.set_attribute("auth_provider", "google") ``` To target a broader or narrower scope instead, see Attributes.