Connect a Dart application to Bugsink
When a Dart application fails, Bugsink gives you the exception, Dart stack, release, and application context you need to investigate it.
This guide covers the initial setup, automatic zone error reporting, other ways to capture failures, and the useful context you can attach to them. You’ll start by connecting the SDK and triggering one deliberate error to confirm that it reaches Bugsink.
To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.
Install the SDK
Add the open-source Sentry Dart SDK to your package. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:
dart pub add sentrydart pub add sentry
Initialize the SDK
Initialize the SDK before running your application. Reading the DSN from the
environment keeps the project key out of source control. Passing your
application as appRunner places it in the SDK’s guarded Dart zone, where
uncaught synchronous and asynchronous errors can be reported automatically:
await Sentry.init((options) { options.dsn = dsn; options.environment = Platform.environment['SENTRY_ENVIRONMENT'] ?? 'production'; options.release = Platform.environment['SENTRY_RELEASE'] ?? 'inventory-dart@1.0.0'; }, appRunner: () => runScenario(arguments));await Sentry.init((options) { options.dsn = dsn; options.environment = Platform.environment['SENTRY_ENVIRONMENT'] ?? 'production'; options.release = Platform.environment['SENTRY_RELEASE'] ?? 'inventory-dart@1.0.0'; }, appRunner: () => runScenario(arguments));
Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the
application:
export SENTRY_DSN=https://key@bugsink.example/1export SENTRY_DSN=https://key@bugsink.example/1
Send a test error
Temporarily throw an error from a path inside appRunner. This inventory
command raises its domain error when an order has no useful quantity; there is
no Bugsink-specific call at the point of failure:
if (quantity <= 0) { throw InvalidOrder(orderId); }if (quantity <= 0) { throw InvalidOrder(orderId); }
Run that path once. The error retains its normal unhandled behavior while the guarded zone reports it to Bugsink.
See the error in Bugsink
Open your Bugsink project. The new InvalidOrder issue contains the Dart stack
and points at the application function which raised it.
InvalidOrder
That’s it: unhandled errors inside the guarded application zone will now be
reported to Bugsink. Remove the deliberate failure and leave appRunner in
place.
Capture other kinds of errors
Automatic zone capture covers errors that escape your asynchronous application code. You can also report exceptions your code catches and exceptional conditions which do not have an exception.
Handled exceptions
Handled exceptions let your application recover while preserving the original
Dart stack in Bugsink. Call captureException() inside catch and pass the
stackTrace from that same clause. withScope keeps event-specific values
from leaking into later work:
try { processOrder(orderId, 0); } catch (exception, stackTrace) { await Sentry.captureException( exception, stackTrace: stackTrace, withScope: (scope) async { await scope.setTag('component', 'orders'); await scope.setContexts('order', {'id': orderId, 'quantity': 0}); await scope.addBreadcrumb( Breadcrumb( category: 'order', message: 'Starting order processing', data: {'order_id': orderId}, ), ); }, ); }try { processOrder(orderId, 0); } catch (exception, stackTrace) { await Sentry.captureException( exception, stackTrace: stackTrace, withScope: (scope) async { await scope.setTag('component', 'orders'); await scope.setContexts('order', {'id': orderId, 'quantity': 0}); await scope.addBreadcrumb( Breadcrumb( category: 'order', message: 'Starting order processing', data: {'order_id': orderId}, ), ); }, ); }
InvalidOrder
Messages without exceptions
A captured message records an exceptional condition without inventing an
exception. Use captureMessage() for a failed health check or stalled queue,
and set the level Bugsink should display. There is no exception stack, so use
an exception when its origin matters:
await Sentry.captureMessage( 'Order queue is not responding', level: SentryLevel.error, );await Sentry.captureMessage( 'Order queue is not responding', level: SentryLevel.error, );
error Order queue is not respondingLog Entry
Add useful context
An exception tells you what failed; context helps explain why. Add values on a temporary scope when they belong to one operation, or configure the current scope when they should remain on later events.
Tags
Tags add short, searchable key/value pairs to an event. Bugsink already records
values such as environment and release; add your own tag for a component,
region, plan, or feature flag. Here the temporary scope makes the order failure
searchable as component:orders:
await scope.setTag('component', 'orders');await scope.setTag('component', 'orders');
ordersBugsink preview: component tag
Tags
Structured context
Structured context adds a named group of diagnostic values to an event. Use it
for details you want to inspect but not search, such as the order or job being
processed. setContexts('order', ...) creates an Order section with the
identifier and quantity:
await scope.setContexts('order', {'id': orderId, 'quantity': 0});await scope.setContexts('order', {'id': orderId, 'quantity': 0});
dart-handled 0Bugsink preview: order context
Contexts
ORDER
Breadcrumbs
Breadcrumbs record the steps which happened before an error. Add one for an application action the SDK cannot infer, such as beginning an order or retrying an external call. It does not create an event; its category, message, and data appear with the next error on the scope:
await scope.addBreadcrumb( Breadcrumb( category: 'order', message: 'Starting order processing', data: {'order_id': orderId}, ), );await scope.addBreadcrumb( Breadcrumb( category: 'order', message: 'Starting order processing', data: {'order_id': orderId}, ), );
Bugsink preview: order breadcrumb
order
Starting order processing
event time
Release and environment
Release and environment identify where a failure happened and which build
introduced it. Set SENTRY_RELEASE and SENTRY_ENVIRONMENT in your deployment,
or provide stable defaults during initialization as above. The Dart SDK also
adds its runtime and operating-system context automatically.
Close a short-lived application cleanly
Sentry.close() flushes buffered SDK work and closes its HTTP client. Call it
during the normal shutdown path of a command, worker, or test process. A
long-running server can instead await it from its signal or lifecycle handler.
Limitations
The Dart SDK currently sends the event-level platform as other. Bugsink still
shows the Dart runtime, SDK identity, and Dart stack frames, so errors remain
recognizable and useful.
The SDK’s Sentry.logger API sends structured log envelope items. Bugsink
2.6.4 accepts that request but does not store it as an issue or display it in
the event UI. Use captureMessage() for a log-like condition that should
appear in Bugsink today.
Dart server frameworks
Handled failures retain their Dart stack and scoped application context while the service keeps control of its response.
