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 sentrydart 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'; });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/1export 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'}, ); }} 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-missingdart 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.
ProductNotFound
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.
