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.

Copied
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.

Copied
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.

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.

Copied
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.

Copied
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:

Copied
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.

http.Client Library Instrumentation

The http.Client instrumentation, once added the SentryHttpClient and enabled the networkTracing feature, starts a span out of the active transaction bound to the scope for each HTTP Request. The SDK sets the span operation to http.client and description to request $method and $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 out of the active transaction bound to the scope for 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.

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

If you want to opt out, you can flip the enableAutoPerformanceTracking flag:

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

Future<void> main() async {
  await SentryFlutter.init(
    (options) => options.enableAutoPerformanceTracking = 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.

If you want to opt out, you can flip the enableAutoPerformanceTracking flag:

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

Future<void> main() async {
  await SentryFlutter.init(
    (options) => options.enableAutoPerformanceTracking = 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.

Copied
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 out of the active transaction bound to the scope for each load and loadString call. The SDK sets the span operation to file.read.

You can also enable the instrumentation for the loadStructuredData method by providing the enableStructuredDataTracing flag.

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

SentryAssetBundle(enableStructuredDataTracing: true)

The SentryAssetBundle instrumentation starts a span out of the active transaction bound to the scope for each loadStructuredData call. The SDK sets the span operation to serialize.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").