Skip to content

docs(dart, flutter): Add Attributes page #18779

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inventarSarah wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs(dart, flutter): Add Attributes page #18779

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3fb5e2a
add attributes page
inventarSarah Jul 21, 2026
2bd6c52
update SDK version numbers
inventarSarah Jul 21, 2026
864fc18
update wording on logs and metrics pages
inventarSarah Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions docs/platforms/dart/common/enriching-events/attributes/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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."

@coolguyzone coolguyzone Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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."

---

<AvailableSince version="9.9.0" />

**Attributes** are key-value pairs you can attach to your telemetry (like <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">spans</PlatformLink> (SDK version `9.23.0`+), <PlatformLink to="/logs">logs</PlatformLink>, and <PlatformLink to="/metrics">metrics</PlatformLink>).
Comment on lines +6 to +8

@sentry sentry Bot Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The <AvailableSince> tag incorrectly states version 9.9.0. Using attributes for logs or metrics requires SDK version 9.23.0, creating a documentation conflict.
Severity: MEDIUM

Suggested Fix

Update the <AvailableSince version="9.9.0" /> tag to reflect the correct minimum required version. Based on the context, the most restrictive and correct version appears to be 9.23.0 for using attributes with logs or metrics. Align the version number with the requirements stated in other parts of the documentation.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: docs/platforms/dart/common/enriching-events/attributes/index.mdx#L6-L8

Potential issue: The documentation for attributes states availability since version
`9.9.0` via the `<AvailableSince>` tag. However, this contradicts other documentation.
The Dart metrics documentation specifies that SDK version `9.11.0` is required for
metrics, and the tags page indicates that using attributes for logs or metrics requires
SDK version `9.23.0`. This discrepancy can mislead developers into attempting to use
features that are not available in their SDK version, leading to confusion and
implementation errors.

Did we get this right? 👍 / 👎 to inform future reviews.


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 |

@inventarSarah inventarSarah Jul 21, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm considering removing this and instead add a link to the Streamed Spans page (or API docs if it's in there) - wdyt?

| -------------------------------- | -------------- |
| `SentryAttribute.string(v)` | `String` |
| `SentryAttribute.int(v)` | `int` |
| `SentryAttribute.bool(v)` | `bool` |
| `SentryAttribute.double(v)` | `double` |
| `SentryAttribute.stringArray(v)` | `List<String>` |
| `SentryAttribute.intArray(v)` | `List<int>` |
| `SentryAttribute.boolArray(v)` | `List<bool>` |
| `SentryAttribute.doubleArray(v)` | `List<double>` |

<Alert level="info">

Attributes on spans require <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>. 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.

</Alert>

## 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 <PlatformLink to="/tracing/streamed-spans/#add-attributes">Add Attributes</PlatformLink> 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 <PlatformLink to ="/logs">Logs</PlatformLink> 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 <PlatformLink to="/metrics">Metrics</PlatformLink> for more.
7 changes: 7 additions & 0 deletions docs/platforms/dart/common/enriching-events/tags/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Alert level="warning">
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{" "}
<PlatformLink to="/enriching-events/attributes/">Attributes</PlatformLink>{" "}
instead.
</Alert>

_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.
Expand Down
18 changes: 16 additions & 2 deletions platform-includes/logs/usage/dart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Alert level="info">
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.
</Alert>

```dart
Expand All @@ -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),
});
```
```

### Shared Attributes

Use `Sentry.setAttributes` to attach attributes that are automatically included on all logs, metrics, and spans (only in <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>):

```dart
Sentry.setAttributes({
'org_id': SentryAttribute.string(user.orgId),
'user_tier': SentryAttribute.string(user.tier),
});
```

See <PlatformLink to="/enriching-events/attributes">Attributes</PlatformLink> for more information.
13 changes: 8 additions & 5 deletions platform-includes/metrics/usage/dart.flutter.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>) while the scope is active.

See <PlatformLink to="/enriching-events/attributes">Attributes</PlatformLink> for more information.

</SplitSectionText>
<SplitSectionCode>
Expand Down
13 changes: 8 additions & 5 deletions platform-includes/metrics/usage/dart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>) while the scope is active.

See <PlatformLink to="/enriching-events/attributes">Attributes</PlatformLink> for more information.

</SplitSectionText>
<SplitSectionCode>
Expand Down
Loading