Step-by-step instructions for adding performance monitoring to your Flutter applications for Android and iOS.
The BugSnag Performance Flutter integration automatically instruments your app’s start time and, by using our simple wrapper packages, will instrument navigation events and network requests. Arbitrary operations can also be manually instrumented in your code.
New to BugSnag? Create an account
Looking for error monitoring? See our integration guide
Add bugsnag_flutter_performance to your application with the flutter command line tool:
$ flutter pub add bugsnag_flutter_performance
You can also manually add bugsnag_flutter_performance to your pubspec.yaml:
dependencies:
bugsnag_flutter_performance: ^1.0.0
The latest available version of bugsnag_flutter_performance is v1.0.0.
The BugSnag Flutter Performance SDK is compatible with v3.10+ of the Dart SDK.
To configure the bugsnag_flutter_performance package, call bugsnag_performance.start as early as possible in your main method and wrap your runApp call as follows:
import 'package:bugsnag_flutter_performance/bugsnag_flutter_performance.dart';
Future<void> main() async {
await bugsnag_performance.start(
apiKey: 'YOUR_API_KEY_HERE'
);
bugsnag_performance.measureRunApp(
() async => runApp(const MainApp())
);
}
This is the same API key used by the BugSnag Error Monitoring library.
You can find your API key in Project Settings from your BugSnag dashboard.
With measureRunApp wrapping your runApp call, as described above, the BugSnag Performance SDK will measure the startup time of your app. This is recorded from the point at which bugsnag_performance.start is called until the first frame is rendered. These timings are shown under the “App starts” tab in the BugSnag Performance dashboard.
By instrumenting the views in your app, the timings for app navigation events can be shown on the BugSnag Performance dashboard.
If you use the Navigator widget or any solution compatible with NavigatorObservers, such as go_router, these navigation events can be automatically measured using our BugsnagPerformanceNavigatorObserver.
To track navigation events, pass the BugSnag observer in when you create the MaterialApp widget:
@override
Widget build(BuildContext context) {
return MaterialApp(
// ...
navigatorObservers: [BugsnagPerformanceNavigatorObserver()],
// ...
);
}
To track navigation events on nested navigators, wrap your Navigator with a BugsnagNavigationContainer and pass in a named BugSnag observer:
BugsnagNavigationContainer(
child: Navigator(
observers: [BugsnagPerformanceNavigatorObserver(navigatorName: 'MyNestedNavigator')],
),
)
If your app uses the go_router package, pass in a BugSnag observer when you create GoRouter:
final GoRouter _router = GoRouter(
routes: <RouteBase>[
/* Your routes */
],
observers: [BugsnagPerformanceNavigatorObserver()],
);
By default, navigation spans will end as soon as the first frame displaying the content of the route is rendered. However sometimes the app is not yet ready for use, for example because more data needs to be loaded first.
Use the BugsnagLoadingIndicator widget to let the navigation instrumentation know that the content is still being loaded: the navigation span will not end while any BugsnagLoadingIndicator widgets exist in the view:
@override
Widget build(BuildContext context) {
final data = _data;
return Column(
children: [
if (data == null) const BugsnagLoadingIndicator(),
HeaderWidget(),
ContentWidget(data: data),
],
);
}
The indicator widget itself has no appearance, but you can wrap any loading widgets – such as spinners – with a BugsnagLoadingIndicator by providing it as the child argument:
@override
Widget build(BuildContext context) {
final data = _data;
if (data == null) {
return const BugsnagLoadingIndicator(child: Text('Loading...'));
}
return ContentWidget(data: data);
}
To instrument navigation events manually, call startNavigationSpan when a navigation is started and end on the resulting span when the navigation is complete:
final span = bugsnag_performance.startNavigationSpan('HomeScreen')
// When your screen has finished rendering
span.end()
The BugSnag Flutter Performance SDK contains packages to detect and report network requests from the http, dart:io and dio libraries. These timings are shown under the “Network requests” tab in the BugSnag Performance dashboard.
To instrument network requests made with the http package, add the bugsnag_http_client package to your application:
$ flutter pub add bugsnag_http_client
As part of your app initialization, add bugsnag_performance as a subscriber.
In your application code, use package:bugsnag_http_client instead of package:http. bugsnag_http_client wraps http, maintaining an identical interface, so you can make network requests through either the top-level functions or a Client:
import 'package:bugsnag_http_client/bugsnag_http_client.dart' as http;
// add subscriber(s) as part of app initialization
http.addSubscriber(bugsnag_performance.networkInstrumentation);
http.addSubscriber(bugsnag.networkInstrumentation);
// use http; requests will be instrumented by BugSnag
http.get('http://myurl.com');
If you are using the BugSnag Flutter Error SDK, you will need to ensure you are using v3.1.0+ with the same bugsnag_http_client package, then register bugsnag as a subscriber in order to also capture network breadcrumbs in your BugSnag error events.
To instrument network requests made with dart:io, add the bugsnag_flutter_dart_io_http_client package to your application:
$ flutter pub add bugsnag_flutter_dart_io_http_client
As part of your app initialization, add bugsnag_performance as a subscriber.
In your application code, use package:bugsnag_flutter_dart_io_http_client instead of package:dart_io. bugsnag_flutter_dart_io_http_client wraps dart_io, maintaining an identical interface, so you can make network requests by creating a client Client:
import 'package:bugsnag_flutter_dart_io_http_client/bugsnag_flutter_dart_io_http_client.dart'
as dart_io;
// add subscriber(s) as part of app initialization
dartIo.addSubscriber(bugsnag.networkInstrumentation);
dartIo.addSubscriber(bugsnag_performance.networkInstrumentation);
// use dart_io; requests will be instrumented by BugSnag
final client = dartIo.HttpClient();
final request = await client.getUrl('http://myurl.com');
If you are using the BugSnag Flutter Error SDK, you will need to ensure you are using v3.1.0+ with the same bugsnag_flutter_dart_io_http_client package, then register bugsnag as a subscriber in order to also capture network breadcrumbs in your BugSnag error events.
dio uses dart:io by default. dio allows you to specify an alternative client adapter, so you can instrument the network requests by using bugsnag_flutter_dart_io_http_client, the BugSnag dart:io wrapper (as described above).
Add bugsnag_flutter_dart_io_http_client to your application:
$ flutter pub add bugsnag_flutter_dart_io_http_client
Then add the BugSnag Performance and BugSnag (for breadcrumbs) subscribers to bugsnag_flutter_dart_io_http_client as part of app initialization. When you instantiate Dio, replace its httpClientAdapter:
import 'package:dio/dio.dart';
import 'package:bugsnag_flutter_dart_io_http_client/bugsnag_flutter_dart_io_http_client.dart'
as dart_io;
// add subscriber(s) as part of app initialization
dart_io.addSubscriber(bugsnag.networkInstrumentation);
dart_io.addSubscriber(bugsnag_performance.networkInstrumentation);
// replace dio's http client adapter
final dio = Dio();
if (!kIsWeb) {
dio.httpClientAdapter = IOHttpClientAdapter(
createHttpClient: () {
return dart_io.HttpClient();
},
);
}
// use dio; requests will be instrumented by BugSnag
dio.get('http://www.myurl.com');
The networkRequestCallback configuration option allows you to control the data sent in these network request spans using a callback.
To instrument network requests manually, call startNetworkRequestSpan when a navigation is started and end on the resulting span when the navigation is complete:
final span = bugsnag_performance.startNetworkSpan('http://www.myurl.com','GET');
// When the network request has completed
span.end()
To send custom spans to BugSnag for any other operations you wish to measure, use bugsnag_performance.startSpan to start a span, and call the span’s end method to end the measurement:
final span = bugsnag_performance.startSpan('Login');
await LoginApi.login();
span.end();
If a custom span is “first class”, its performance characteristics will be aggregated and shown in the “Custom” tab of the BugSnag dashboard. If the custom span is useful only for adding insight into the performance of its parent (through the waterfall diagram on the span instance page), you should set the isFirstClass span option to false:
final span = bugsnag_performance.startSpan('always-nested',isFirstClass: false,);
// something you want to measure
span.end();
When viewing a single instance of a span in the BugSnag dashboard, a waterfall diagram will show you that instance’s children and their children, and so on. This allows you to see in more detail where the time was spent, and aid diagnosing and fixing any problems. When creating your own spans, you can use the options parameter to control their parent-child relationships to produce a meaningfully representative hierarchy in your dashboard. See Maintaining span context for more information.
By default, a span will use the current timestamp as its start time. However, you can use the startTime span option to report spans that have already started by providing your own timestamp. You can also end a span with your own timestamp to provide a retrospective end time:
bugsnag_performance.startSpan('custom-start-time', startTime: DateTime(1985));