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..25fe0beb03b99f --- /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 (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. + +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..18e00df26d020d 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, metrics, and spans (only in stream mode): + +```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..dfeeec373b67a8 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 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 00daae2e404174..4a09814c1d5332 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 logs, metrics, and spans (only in stream mode) while the scope is active. + +See Attributes for more information.