Attributes
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.
Available since: v9.9.0
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<String> |
SentryAttribute.intArray(v) | List<int> |
SentryAttribute.boolArray(v) | List<bool> |
SentryAttribute.doubleArray(v) | List<double> |
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.
Use Sentry.setAttributes to attach attributes to the current scope. This is the easiest way to enrich everything at once:
Sentry.setAttributes({
'org_id': SentryAttribute.string(user.orgId),
'user_tier': SentryAttribute.string(user.tier),
'service': SentryAttribute.string('checkout'),
});
Sentry.setAttributes({
'org_id': SentryAttribute.string(user.orgId),
'user_tier': SentryAttribute.string(user.tier),
'service': SentryAttribute.string('checkout'),
});
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.
In stream mode, you can set attributes when starting a span:
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),
},
);
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:
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();
});
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.
Pass attributes to any Sentry.logger call:
Sentry.logger.info('User ${user.username} added ${product.name} to cart.', attributes: {
'user': SentryAttribute.string(user.username),
'product': SentryAttribute.string(product.name),
});
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.
Pass attributes in the attributes parameter of any metric. Each metric has a 2KB size limit for attributes:
Sentry.metrics.count(
'api_calls',
1,
attributes: {
'endpoint': SentryAttribute.string('/api/orders'),
'user_tier': SentryAttribute.string('pro'),
'region': SentryAttribute.string('us-west'),
},
);
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.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").