From 3fb5e2a9d113525c9f6da913d4469046a86a6c73 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 21 Jul 2026 10:40:16 +0200 Subject: [PATCH 1/4] add attributes page --- .../enriching-events/attributes/index.mdx | 117 ++++++++++++++++++ .../common/enriching-events/tags/index.mdx | 7 ++ platform-includes/logs/usage/dart.mdx | 18 ++- .../metrics/usage/dart.flutter.mdx | 13 +- platform-includes/metrics/usage/dart.mdx | 13 +- 5 files changed, 156 insertions(+), 12 deletions(-) create mode 100644 docs/platforms/dart/common/enriching-events/attributes/index.mdx diff --git a/docs/platforms/dart/common/enriching-events/attributes/index.mdx b/docs/platforms/dart/common/enriching-events/attributes/index.mdx new file mode 100644 index 00000000000000..856c64cf39e138 --- /dev/null +++ b/docs/platforms/dart/common/enriching-events/attributes/index.mdx @@ -0,0 +1,117 @@ +--- +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. + +Each attribute value is created with a typed `SentryAttribute` factory: + +| Factory | Dart Type | +| -------------------------------- | -------------- | +| `SentryAttribute.string(v)` | `String` | +| `SentryAttribute.int(v)` | `int` | +| `SentryAttribute.bool(v)` | `bool` | +| `SentryAttribute.double(v)` | `double` | +| `SentryAttribute.stringArray(v)` | `List` | +| `SentryAttribute.intArray(v)` | `List` | +| `SentryAttribute.boolArray(v)` | `List` | +| `SentryAttribute.doubleArray(v)` | `List` | + + + +Attributes on spans require stream mode. In stream mode, spans have no contexts, data, or tags — everything is a typed attribute, so `setData` and `setTag` are replaced by `setAttribute` and `setAttributes`. + +Attributes on logs and metrics don't require stream mode and work by default. + + + +## Add Attributes to the Current Scope + +Use `Sentry.setAttributes` to attach attributes to the current scope. This is the easiest way to enrich everything at once: + +```dart +Sentry.setAttributes({ + 'org_id': SentryAttribute.string(user.orgId), + 'user_tier': SentryAttribute.string(user.tier), + 'service': SentryAttribute.string('checkout'), +}); +``` + +## 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: + +```dart +await Sentry.startSpan( + 'process-order', + (_) async { + await processOrder(); + }, + attributes: { + 'sentry.op': SentryAttribute.string('queue.process'), + 'order.id': SentryAttribute.string('abc-123'), + 'order.item_count': SentryAttribute.int(5), + 'order.priority': SentryAttribute.bool(true), + }, +); +``` + +Or add them to an already running span with `setAttribute` or `setAttributes`. Use `removeAttribute` to remove an attribute: + +```dart +await Sentry.startSpan('handle-request', (span) async { + span.setAttribute( + 'http.response.status_code', + SentryAttribute.int(200), + ); + + span.setAttributes({ + 'http.route': SentryAttribute.string('/api/users'), + 'user.id': SentryAttribute.string('user-42'), + }); + + await handleRequest(); +}); +``` + +See Add Attributes for more on span attributes. + +### Logs + +Pass attributes to any `Sentry.logger` call: + +```dart +Sentry.logger.info('User ${user.username} added ${product.name} to cart.', attributes: { + 'user': SentryAttribute.string(user.username), + 'product': SentryAttribute.string(product.name), +}); +``` + +See Logs for more. + +### Metrics + +Pass attributes in the `attributes` parameter of any metric. Each metric has a 2KB size limit for attributes: + +```dart +Sentry.metrics.count( + 'api_calls', + 1, + attributes: { + 'endpoint': SentryAttribute.string('/api/orders'), + 'user_tier': SentryAttribute.string('pro'), + 'region': SentryAttribute.string('us-west'), + }, +); +``` + +See Metrics for more. diff --git a/docs/platforms/dart/common/enriching-events/tags/index.mdx b/docs/platforms/dart/common/enriching-events/tags/index.mdx index c039db2e96944d..fba563d51096c6 100644 --- a/docs/platforms/dart/common/enriching-events/tags/index.mdx +++ b/docs/platforms/dart/common/enriching-events/tags/index.mdx @@ -7,6 +7,13 @@ description: "Tags power UI features such as filters and tag-distribution maps. 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 or metrics. If you're using SDK version + `9.23.0` or above and want to attach context to logs or metrics, 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 (`-`). _Tag values_ have a maximum length of 200 characters and they cannot contain the newline (`\n`) character. diff --git a/platform-includes/logs/usage/dart.mdx b/platform-includes/logs/usage/dart.mdx index 92937eef24b8fe..94fa27eb2eec51 100644 --- a/platform-includes/logs/usage/dart.mdx +++ b/platform-includes/logs/usage/dart.mdx @@ -7,7 +7,8 @@ Aside from the primary logging methods, we've provided a format text function, ` These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column. - When using the `fmt` function, you must use the `%s` placeholder for each value you want to insert. + When using the `fmt` function, you must use the `%s` placeholder for each + value you want to insert. ```dart @@ -31,4 +32,17 @@ Sentry.logger.info('User ${user.username} added ${product.name} to cart.', attri 'user': SentryAttribute.string(user.username), 'product': SentryAttribute.string(product.name), }); -``` \ No newline at end of file +``` + +### Shared Attributes + +Use `Sentry.setAttributes` to attach attributes that are automatically included on all logs (as well as your metrics): + +```dart +Sentry.setAttributes({ + 'org_id': SentryAttribute.string(user.orgId), + 'user_tier': SentryAttribute.string(user.tier), +}); +``` + +See Attributes for more information. diff --git a/platform-includes/metrics/usage/dart.flutter.mdx b/platform-includes/metrics/usage/dart.flutter.mdx index 65e5453d10f232..a118255cddc76e 100644 --- a/platform-includes/metrics/usage/dart.flutter.mdx +++ b/platform-includes/metrics/usage/dart.flutter.mdx @@ -4,10 +4,10 @@ ### Metric Types -| Type | Use For | -|------|---------| -| `count` | Events (orders, clicks, API calls) | -| `gauge` | Current values (queue depth, connections) | +| Type | Use For | +| -------------- | -------------------------------------------- | +| `count` | Events (orders, clicks, API calls) | +| `gauge` | Current values (queue depth, connections) | | `distribution` | Value ranges (response times, payload sizes) | No setup required beyond SDK initialization. @@ -45,6 +45,7 @@ Sentry.metrics.distribution( #### Filtering and Grouping Attributes let you filter and group metrics in Sentry. Use them for: + - Environment segmentation - Feature flag tracking - User tier analysis @@ -74,7 +75,9 @@ Sentry.metrics.count( #### Scope Attributes -Use scope APIs to set attributes that apply to all metrics while the scope is active. +Use scope APIs to set attributes that apply to all metrics (and logs) while the scope is active. + +See Attributes for more information. diff --git a/platform-includes/metrics/usage/dart.mdx b/platform-includes/metrics/usage/dart.mdx index 00daae2e404174..1339b738e17d64 100644 --- a/platform-includes/metrics/usage/dart.mdx +++ b/platform-includes/metrics/usage/dart.mdx @@ -4,10 +4,10 @@ ### Metric Types -| Type | Use For | -|------|---------| -| `count` | Events (orders, clicks, API calls) | -| `gauge` | Current values (queue depth, connections) | +| Type | Use For | +| -------------- | -------------------------------------------- | +| `count` | Events (orders, clicks, API calls) | +| `gauge` | Current values (queue depth, connections) | | `distribution` | Value ranges (response times, payload sizes) | No setup required beyond SDK initialization. @@ -45,6 +45,7 @@ Sentry.metrics.distribution( #### Filtering and Grouping Attributes let you filter and group metrics in Sentry. Use them for: + - Environment segmentation - Feature flag tracking - User tier analysis @@ -74,7 +75,9 @@ Sentry.metrics.count( #### Scope Attributes -Use scope APIs to set attributes that apply to all metrics while the scope is active. +Use scope APIs to set attributes that apply to all metrics (and logs) while the scope is active. + +See Attributes for more information. From 2bd6c524f8c923ea65adffa0ebd8735c8b607f90 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 21 Jul 2026 12:03:56 +0200 Subject: [PATCH 2/4] update SDK version numbers --- .../dart/common/enriching-events/attributes/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/dart/common/enriching-events/attributes/index.mdx b/docs/platforms/dart/common/enriching-events/attributes/index.mdx index 856c64cf39e138..25fe0beb03b99f 100644 --- a/docs/platforms/dart/common/enriching-events/attributes/index.mdx +++ b/docs/platforms/dart/common/enriching-events/attributes/index.mdx @@ -3,9 +3,9 @@ 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). +**Attributes** are key-value pairs you can attach to your telemetry (like spans (SDK version `9.23.0`+), logs, and metrics). Common uses include subscription tier, feature flags, or any business context that helps you filter and query your telemetry. From 864fc1872227cbc2177f9a343565e50219437517 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 21 Jul 2026 12:18:24 +0200 Subject: [PATCH 3/4] update wording on logs and metrics pages --- platform-includes/logs/usage/dart.mdx | 2 +- platform-includes/metrics/usage/dart.flutter.mdx | 2 +- platform-includes/metrics/usage/dart.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/platform-includes/logs/usage/dart.mdx b/platform-includes/logs/usage/dart.mdx index 94fa27eb2eec51..18e00df26d020d 100644 --- a/platform-includes/logs/usage/dart.mdx +++ b/platform-includes/logs/usage/dart.mdx @@ -36,7 +36,7 @@ Sentry.logger.info('User ${user.username} added ${product.name} to cart.', attri ### Shared Attributes -Use `Sentry.setAttributes` to attach attributes that are automatically included on all logs (as well as your metrics): +Use `Sentry.setAttributes` to attach attributes that are automatically included on all logs, metrics, and spans (only in stream mode): ```dart Sentry.setAttributes({ diff --git a/platform-includes/metrics/usage/dart.flutter.mdx b/platform-includes/metrics/usage/dart.flutter.mdx index a118255cddc76e..dfeeec373b67a8 100644 --- a/platform-includes/metrics/usage/dart.flutter.mdx +++ b/platform-includes/metrics/usage/dart.flutter.mdx @@ -75,7 +75,7 @@ Sentry.metrics.count( #### Scope Attributes -Use scope APIs to set attributes that apply to all metrics (and logs) while the scope is active. +Use scope APIs to set attributes that apply to all logs, metrics, and spans (only in stream mode) while the scope is active. See Attributes for more information. diff --git a/platform-includes/metrics/usage/dart.mdx b/platform-includes/metrics/usage/dart.mdx index 1339b738e17d64..4a09814c1d5332 100644 --- a/platform-includes/metrics/usage/dart.mdx +++ b/platform-includes/metrics/usage/dart.mdx @@ -75,7 +75,7 @@ Sentry.metrics.count( #### Scope Attributes -Use scope APIs to set attributes that apply to all metrics (and logs) while the scope is active. +Use scope APIs to set attributes that apply to all logs, metrics, and spans (only in stream mode) while the scope is active. See Attributes for more information. From e17cc01986ade5155142e4fd714e9afd447016ea Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Mon, 27 Jul 2026 06:47:09 +0200 Subject: [PATCH 4/4] Update docs/platforms/dart/common/enriching-events/attributes/index.mdx Co-authored-by: Alex Krawiec --- .../platforms/dart/common/enriching-events/attributes/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/dart/common/enriching-events/attributes/index.mdx b/docs/platforms/dart/common/enriching-events/attributes/index.mdx index 25fe0beb03b99f..52122facafbb45 100644 --- a/docs/platforms/dart/common/enriching-events/attributes/index.mdx +++ b/docs/platforms/dart/common/enriching-events/attributes/index.mdx @@ -1,6 +1,6 @@ --- 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." +description: "Attributes automatically enrich your telemetry with typed key-value data. Use them to add business context that you can then filter and search in Sentry." ---