Automatic Instrumentation

Routing Instrumentation

Automatic routing instrumentation can be enabled by adding an instance of SentryNavigationObserver to your application's navigatorObservers. Transactions are started automatically when routing to new pages in your application.

import 'package:flutter/material.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

return MaterialApp(
  title: 'Home',
  home: HomeScreen(),
  navigatorObservers: [
    SentryNavigatorObserver()
  ],
);

The main route of your application will have the name root "/". In order for transactions to be created automatically when navigation changes, you need to provide route names through your routes setttings parameter.

import 'package:flutter/material.dart';

MaterialPageRoute(
  builder: (BuildContext context) => Settings(),
  settings: RouteSettings(name: 'Settings'),
)

The SDK sets the span operation to navigation and the name to the one provided in RouteSettings.

Transactions will be bound to the scope if no other transaction is currently bound to it.

If the transaction has no spans, the transaction will be dropped and not sent to Sentry, the reason is that there's no callback to identify when the screen has been loaded, so we rely on the child spans.

The started transactions will idle for a fixed amount of time, for which the default is three seconds. You can also change this by setting autoFinishAfter in the navigators constuctor.

import 'package:sentry_flutter/sentry_flutter.dart';

/// Change how long navigation transactions idle before being finished
SentryNavigatorObserver(
  autoFinishAfter: Duration(seconds: 5)
)

Child spans started will be attached to the transaction. If they run longer than the idle time, the transaction will be extended and finished when all its children are complete.

If children are finished before the idle timeout, the transaction end will be trimmed, and its end time will be set to the last child end time.

You can also opt out of this behaviour by setting enableAutoTransactions to false in the SentryNavigatorObserver constructor. You might do this when you only want to use navigation breadcrumbs, which can be enabled by setting the constructor parameter setRouteNameAsTransaction to true.

import 'package:sentry_flutter/sentry_flutter.dart';

/// Only track navigation breadcrums
SentryNavigatorObserver(
  enableAutoTransactions: false,
  setRouteNameAsTransaction: true
)

GoRouter Instrumentation

When using the go_router library, the automatic routing instrumentation can be enabled by adding an instance of SentryNavigationObserver to your application's GoRouter.observers:

import 'package:go_router/go_router.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

final router = GoRouter(
  routes: ...,
  observers: [SentryNavigatorObserver()],
);

Everything else follows the routing instrumentation setup.

User Interaction Instrumentation

The UI instrumentation, once enabled, captures transactions and adds breadcrumbs for a set of different user interactions, which include clicks, long clicks, taps, and so on.

Learn more in our User Interaction Instrumentation.

http.Client Library Instrumentation

The http.Client instrumentation, once added the SentryHttpClient and enabled the performance feature, starts a span from an active transaction that's bound to the scope of each HTTP Request. The SDK sets the span operation to http.client and description to request $METHOD $url; for example, GET https://sentry.io.

The span finishes once the request has been executed. The span status depends on either the HTTP Response code or SpanStatus.internalError() if the code does not match any of Sentry's SpanStatus.

When the HTTP request throws an Exception, Sentry's SDK associates this exception to the running span. If you haven't set the SDK to swallow the exception and capture it, the span and SentryEvent will be linked when viewing it on the Issue Details page in sentry.io.

For more information see our SentryHttpClient integration.

Dio HTTP Library Instrumentation

The Dio instrumentation starts a span from an active transaction that's bound to the scope of each HTTP request. The SDK sets the span operation to http.client and the description to request $METHOD $url. For example, GET https://sentry.io.

The span finishes once the request has been executed. The span status depends on either the HTTP response code or SpanStatus.internalError() if the code does not match any of Sentry's SpanStatus options.

When the HTTP request throws an Exception, Sentry's SDK associates this exception to the running span. If you haven't set the SDK to swallow the exception and capture it, the span and SentryEvent will be linked when viewing it on the Issue Details page in sentry.io.

Learn more in our Dio integration documentation.

App Start Instrumentation

The App Start Instrumentation provides insight into how long your application takes to launch. It tracks the length of time from the earliest native process initialization until the very first PostFrameCallback is triggered.

The SDK differentiates between a cold and a warm start, but doesn't track hot starts/resumes.

If you don't initialize the SDK early in the app's lifecycle, you can also customize the ending of the app start by disabling the autoAppStart flag and calling the SentryFlutter.setAppStartEnd function.

import 'package:sentry_flutter/sentry_flutter.dart';

// Run my App and do my things first

// Initialize the Flutter SDK
Future<void> main() async {
  await SentryFlutter.init(
    (options) => options.autoAppStart = false,
  );
}

// End the App start
SentryFlutter.setAppStartEnd(DateTime.now().toUtc());

To opt out, flip the enableAutoPerformanceTracing flag:

import 'package:flutter/widgets.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
  await SentryFlutter.init(
    (options) => options.enableAutoPerformanceTracing = false,
    appRunner: () => runApp(MyApp()),
  );
}

Cold and warm start are Mobile Vitals, which you can learn about in the full documentation.

Slow and Frozen Frames

Unresponsive UI and animation hitches annoy users and degrade the user experience. Two measurements to track these types of experiences are slow frames and frozen frames. If you want your app to run smoothly, you should try to avoid both. The SDK adds these two measurements for the transactions you capture.

To start getting the Mobile Vitals data, you have to set up the routing instrumentation or the GoRouter instrumentation.

To opt out, flip the enableAutoPerformanceTracing flag:

import 'package:flutter/widgets.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
  await SentryFlutter.init(
    (options) => options.enableAutoPerformanceTracing = false,
    appRunner: () => runApp(MyApp()),
  );
}

Slow and frozen frames are Mobile Vitals, which you can learn about in the full documentation.

AssetBundle Instrumentation

The AssetBundle instrumentation provides insight into how long your app takes to load its assets, such as files. It can be enabled by wrapping the runApp method with a DefaultAssetBundle and SentryAssetBundle.

import 'package:flutter/widgets.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
  await SentryFlutter.init(
    (options) => options.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0',
    appRunner: () => runApp(
      DefaultAssetBundle(
        bundle: SentryAssetBundle(),
        child: MyApp(),
      ),
    ),
  );
}

The SentryAssetBundle instrumentation starts a span from an active transaction that's bound to the scope of each load and loadString call. The SDK sets the span operation to file.read.

The SentryAssetBundle instrumentation starts a span from an active transaction that's bound to the scope of each loadStructuredData call. The SDK sets the span operation to serialize.

The loadStructuredData is an opt-out feature. The following example shows how to disable it:

import 'package:sentry_flutter/sentry_flutter.dart';

SentryAssetBundle(enableStructuredDataTracing: false)

File I/O Instrumentation

The Sentry-specific file I/O instrumentation starts a span from an active transaction that's bound to the scope of each file I/O operation. The SDK sets the span operation to file.copy, file.write, file.delete, file.open, file.read or file.rename, and description to filename (for example, file.txt).

In addition, the span contains other useful information such as file.size (raw number of bytes), file.path (an absolute path to the file) and file.async (true if the called method returns a Future, or false if it's a Sync call) as part of the data payload.

The span finishes once the operation has been executed. The span status is then set to SpanStatus.ok if successful, or SpanStatus.internalError if there was an error.

When the operation throws an Exception, Sentry's SDK associates it with the running span. If you haven't set the SDK to swallow and capture the exception, the span and SentryEvent will be shown as linked on the Issue Details page in sentry.io.

Learn more about our file I/O integration.

sqflite Database Instrumentation

The sqflite database instrumentation starts a span from an active transaction that's bound to the scope of each CRUD operation.

The span finishes once the operation has been executed. The span status is then set to SpanStatus.ok if successful, or SpanStatus.internalError if there was an error.

When the operation throws an Exception, Sentry's SDK associates it with the running span. If you haven't set the SDK to swallow and capture the exception, the span and SentryEvent will be shown as linked on the Issue Details page in sentry.io.

Learn more about our sqflite Database Instrumentation.