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 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));

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the application:

export 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);
}

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.

Bugsink preview

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},
        ),
      );
    },
  );
}

Bugsink preview

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,
);

Bugsink preview

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');

Bugsink preview: component tag
Bugsink preview

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});

Bugsink preview: order context
Bugsink preview

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},
  ),
);

Bugsink preview: order breadcrumb
Bugsink preview

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.