Automatic Instrumentation
Capturing transactions requires that you first set up performance monitoring if you haven't already.
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.
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").
- Package:
- pub:sentry_flutter
- Version:
- 7.4.0
- Repository:
- https://github.com/getsentry/sentry-dart