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 0000000000000..00ab7e83c2307 --- /dev/null +++ b/docs/platforms/python/enriching-events/attributes/index.mdx @@ -0,0 +1,122 @@ +--- +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` 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_attribute("org_id", user.org_id) +sentry_sdk.set_attribute("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 68ac3216e2585..ad9085a0484f4 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 ad073e66a0c60..0a0b21633b64e 100644 --- a/platform-includes/logs/usage/python.mdx +++ b/platform-includes/logs/usage/python.mdx @@ -36,3 +36,16 @@ 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` 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_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 546d77c4711f5..ca8ab34869d8b 100644 --- a/platform-includes/metrics/usage/python.mdx +++ b/platform-includes/metrics/usage/python.mdx @@ -61,3 +61,26 @@ 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` 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_attribute("is_admin", True) +sentry_sdk.set_attribute("auth_provider", "google") +``` + +To target a broader or narrower scope instead, see Attributes.