Connect a Dart Shelf service to Bugsink

When a Shelf handler catches an exception, Bugsink can preserve the Dart stack and application context while your service remains in control of the HTTP response.

This guide adds the Dart SDK to an existing Shelf service. You’ll initialize the SDK, capture a failed checkout with its stack trace, and attach the request values needed to investigate it.

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

Configure your DSN

Initialize the SDK before starting the HTTP server. Reading the DSN from the environment keeps the project key out of source control and makes a missing configuration fail clearly:

final dsn = Platform.environment['SENTRY_DSN'];
if (dsn == null || dsn.isEmpty) {
  stderr.writeln('SENTRY_DSN must contain the DSN from a Bugsink project');
  exitCode = 2;
  return;
}

await Sentry.init((options) {
  options.dsn = dsn;
  options.release = 'inventory-dart@1.0.0';
});

Set SENTRY_DSN to the DSN shown by your Bugsink project when you start the service:

export SENTRY_DSN=https://key@bugsink.example/1

The release identifies the deployed application version. The SDK also adds the Dart runtime, operating system, and other runtime context automatically.

Capture a handled exception

Shelf does not have automatic request-error middleware in the Dart SDK. Capture an exception where your handler has decided how to respond, and pass the stackTrace from the Dart catch clause so Bugsink receives the application frame:

} catch (exception, stackTrace) {
  await Sentry.captureException(
    exception,
    stackTrace: stackTrace,
    withScope: (scope) async {
      await scope.setTag('component', 'inventory');
      await scope.setContexts('checkout', {
        'sku': sku,
        'method': request.method,
        'path': '/${request.url.path}',
      });
      await scope.addBreadcrumb(
        Breadcrumb(
          message: 'Rejected an inventory checkout',
          category: 'inventory',
          data: {'sku': sku},
        ),
      );
    },
  );
  return Response.internalServerError(
    body: jsonEncode({'error': exception.toString()}),
    headers: {'content-type': 'application/json'},
  );
}

withScope keeps the inventory tag, checkout values, and breadcrumb on this event instead of leaking them into later requests. Because this is manual capture rather than a Shelf integration, the SDK does not create a Sentry request object; the explicit method and path above remain available under the Checkout context.

Send a test error

Start the service, then request a product which does not exist:

dart run bin/server.dart
:::bash
curl http://127.0.0.1:8085/checkout/dart-missing

The handler returns its own 500 JSON response after captureException finishes sending the event.

See the error in Bugsink

Open your Bugsink project. The new ProductNotFound issue contains the Dart stack and identifies the handler line which raised it.

Bugsink preview

The event-level platform is other, as sent by this version of the Dart SDK. Its sentry.dart SDK identity, Dart runtime context, and Dart stack-frame platform still identify the event precisely.

That’s it: handled Shelf failures can now be reported to Bugsink while the handler continues to control the response.

For automatic zone errors, messages, tags, context, breadcrumbs, releases, and shutdown behavior, continue with the plain Dart guide.