BugSnag has many configuration options that can be set to customize the content of events and sessions and how they are sent.
This documentation is for version 3 of the BugSnag Flutter library. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.
Configuration options are optional parameters to the start function:
Future<void> main() async {
await bugsnag.start(
apiKey: 'your-api-key-here',
appVersion: '1.2.3-alpha',
);
runApp(MyApplication());
}
The API key used for events sent to BugSnag.
await bugsnag.start(
apiKey: 'your-api-key-here',
);
You can find your API key in Project Settings from your BugSnag dashboard.
Applies to iOS only.
Enables reporting of non-fatal app hangs from which your app recovered before being terminated by the user or the iOS watchdog.
By default this is set to the constant appHangThresholdFatalOnly, meaning that an error will only be sent to BugSnag if your app hang is fatal.
await bugsnag.start(
appHangThresholdMillis: 5000,
);
If your app’s codebase contains different entry-points/processes, but reports to a single BugSnag project, you might want to add information denoting the type of process the error came from.
This information can be used in the dashboard to filter errors and to determine whether an error is limited to a subset of appTypes.
await bugsnag.start(
appType: 'lite',
);
The version of the application. This is really useful for finding out when errors are introduced and fixed. Additionally BugSnag can re-open closed errors if a later version of the app has a regression.
BugSnag will automatically determine your app’s version.
On Android, the versionName field from your app’s manifest file is used.
On iOS and macOS, CFBundleShortVersionString from Info.plist is used.
If you’d like to override this you can set the appVersion configuration option:
await bugsnag.start(
appVersion: '1.2.3-alpha',
);
By default, we will automatically notify BugSnag of any uncaught errors that we capture. Use this flag to disable all automatic detection.
await bugsnag.start(
autoDetectErrors: false,
);
Setting autoDetectErrors to false will disable all automatic errors, regardless of the error types enabled by the Enabled Error Types configuration option.
By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.
await bugsnag.start(
autoTrackSessions: false,
);
If you want control over what is deemed a session, you can switch off the automatic session tracking option and manage the session manually. See Capturing sessions for more information.
Applies to iOS only.
The bundle version of the application.
We’ll automatically set this from the CFBundleVersion value in your Info.plist file. If you’d like to override this you can set the Bundle Version configuration option:
await bugsnag.start(
bundleVersion: '3.22.0',
);
The “context” is a string that indicates what the user was doing when an error occurs and is given high visual prominence in the dashboard. Set an initial context that you want to send with events – see Setting context for more information.
await bugsnag.start(
context: 'InitialTutorialStep',
);
Allows you to specify which events should be automatically discarded based on their errorClass.
await bugsnag.start(
discardClasses: const {
'java.net.UnknownHostException',
'SIGPIPE',
},
);
By default BugSnag will automatically add breadcrumbs for common application events whilst your application is running. Set this option to configure which of these are enabled and sent to BugSnag.
await bugsnag.start(
enabledBreadcrumbTypes: const {
BugsnagEnabledBreadcrumbType.navigation,
BugsnagEnabledBreadcrumbType.request,
},
);
Automatically captured breadcrumbs can be disabled as follows:
await bugsnag.start(
enabledBreadcrumbTypes: const {},
);
The following automatic breadcrumb types can be enabled:
Error breadcrumbs (BugsnagEnabledBreadcrumbType.error) are left when an error event is sent to the BugSnag API.
Navigation breadcrumbs (BugsnagEnabledBreadcrumbType.navigation) are left for navigation-related notifications to track the user’s journey in the app.
Network request breadcrumbs (BugsnagEnabledBreadcrumbType.request) are left for network requests made by your app. See Customizing breadcrumbs for more information.
State breadcrumbs (BugsnagEnabledBreadcrumbType.state) are left for system broadcast events. For example: network connectivity changes, orientation changes, etc. See Automatically captured data for more information.
User breadcrumbs (BugsnagEnabledBreadcrumbType.user) are left when the user performs certain system operations. See Automatically captured data for more information.
BugSnag will automatically detect different types of error in your application. Set this option if you wish to control exactly which types are enabled.
await bugsnag.start(
enabledErrorTypes: const BugsnagEnabledErrorTypes(
unhandledDartExceptions: false, // Exceptions in Dart
unhandledJvmExceptions: false, // Exceptions in Android JVM
crashes: false, // Native crashes
anrs: false, // Android Application Not Responding
appHangs: false, // iOS native hangs
thermalKills: false, // iOS thermal kills
ooms: false // iOS Out Of Memory
)
);
Setting the Auto Detect Errors configuration option to false will disable all automatic errors, regardless of the error types enabled by enabledErrorTypes.
By default, BugSnag will be notified of events that happen in any releaseStage. Set this option if you would like to change which release stages notify BugSnag.
await bugsnag.start(
enabledReleaseStages: const {'production', 'development', 'testing'},
);
By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.
If you are using BugSnag On-premise you’ll need to set these to your Event Server
and Session Server endpoints. If the notify endpoint is set but the sessions endpoint is not, session tracking
will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.
await bugsnag.start(
endpoints: const BugsnagEndpointConfiguration(
'https://notify.example.com', 'https://sessions.example.com'),
);
Declare feature flag and experiment usage.
await bugsnag.start(
featureFlags: const [
BugsnagFeatureFlag('Checkout button color', 'Blue'),
BugsnagFeatureFlag('Special offer', 'Free Coffee'),
BugsnagFeatureFlag('New checkout flow'),
],
);
See the Feature flags & experiments guide for more information.
The amount of time (in milliseconds) after starting BugSnag that should be considered part of the app’s launch.
By default this value is 5000 milliseconds.
await bugsnag.start(
launchDurationMillis: 0,
);
Events that occur during app launch will have their app.isLaunching property set to true.
Setting this to 0 will cause BugSnag to consider the app to be launching until markLaunchCompleted() has been called. See Identifying crashes at launch for further information.
Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.
By default, 50 breadcrumbs are stored; this can be amended up to a maximum of 100.
await bugsnag.start(
maxBreadcrumbs: 75,
);
Sets the maximum number of events which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest events will be deleted.
By default, 32 events are stored.
await bugsnag.start(
maxPersistedEvents: 50,
);
Sets the maximum number of sessions which will be stored on disk for sending later at times when there is no internet connection available. Once the threshold is reached, the oldest sessions will be deleted.
By default, 128 sessions are stored.
await bugsnag.start(
maxPersistedSessions: 50,
);
The maximum length of a string in metadata. To help avoid excessive event payload sizes, any strings exceeding this length will be truncated.
This limit defaults to 10,000 characters.
await bugsnag.start(
maxStringValueLength: 5000,
);
Set diagnostic metadata that you want to send with all captured events – see Customizing error reports for more information.
await bugsnag.start(
metadata: const {
'company': {
'name': 'Acme Co.',
'country': 'uk'
}
}
);
The top-level keys of the supplied map are section names that are displayed as tabs in the BugSnag dashboard.
Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing error reports for more information.
await bugsnag.start(
onError: [
(event) {
event.addMetadata('game', const {'current_score': 13});
return true;
},
],
);
Applies to Android only.
Sets the directory where BugSnag data, such as event and session payloads, are cached on disk. User information is also persisted here if the Persist User configuration option is true.
await bugsnag.start(
persistenceDirectory: '/my-custom-dir',
);
The default directory for this property is Android’s cache directory.
If you change the value of the persistence directory between application launches, no attempt will be made to migrate data persisted from the original location. This may result in events and sessions not being delivered to BugSnag.
Set whether or not BugSnag should persist user information between application launches.
await bugsnag.start(
persistUser: false,
);
By default persistUser is set to true.
If enabled then any user information set will be re-used until the user information is removed manually by calling setUser with null arguments.
Sets which package names BugSnag should consider as a part of the running application. We mark stacktrace lines as in-project if they originate from any of these packages and this allows us to improve the visual display of the stacktrace on the dashboard.
await bugsnag.start(
projectPackages: BugsnagProjectPackages.withDefaults({'my_flutter_app'}),
);
By default, we attempt to make sensible inferences about which packages are in-project. To keep those defaults but also add other packages, pass the additional package names to BugsnagProjectPackages.withDefaults.
If you are building with --split-debug-info, the package name is not available and so you need pass it here. You also need to pass the names of any additional in-project Dart packages or if you have Android packages in native modules. You do not need to pass any additional iOS package names. For more information, see the Integration guide.
Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.
Any property whose key matches a redacted key will be filtered and replaced with [REDACTED]. By default, any key that contains “password” will be redacted. Be aware that if you set this configuration option, it will replace the default, so you may want to replace “password” in your own set if you want to filter that.
await bugsnag.start(
redactedKeys: const {'credit_card_number'},
);
By default, redactedKeys is set to 'password'
Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).
await bugsnag.start(
releaseStage: 'development',
);
This is automatically configured by the notifier to be “production” for apps built in release mode, otherwise it will be set to “development”.
You can control whether events are sent for specific release stages using the Enabled Release Stages configuration option.
Determines whether launch crashes should be sent synchronously whilst BugSnag starts.
If this option is enabled and the previous run terminated due to a crash during app launch, BugSnag will block the calling thread when it starts for up to 2 seconds while the crash report is sent.
This behavior is enabled by default.
await bugsnag.start(
sendLaunchCrashesSynchronously: false,
);
Controls whether we should capture and serialize the state of all threads at the time of an exception.
await bugsnag.start(
sendThreads: BugsnagThreadSendPolicy.unhandledOnly,
);
By default this option is set to BugsnagThreadSendPolicy.always. This can be set to BugsnagThreadSendPolicy.never to disable the sending of threads entirely or BugsnagThreadSendPolicy.unhandledOnly to only send threads for unhandled errors.
Internal errors are sent when an error is detected within BugSnag, for example when a crash report cannot be processed.
To prevent these from being sent:
await bugsnag.start(
telemetry: const BugsnagTelemetryTypes(internalErrors: false)
);
Usage telemetry helps us improve BugSnag by providing information on how you are configuring the SDK. We record:
We collect only bools, ints and enums. We do not collect any information personal to you or your users. The information is sent as part of error events; there is no additional network call made.
To prevent this from being sent:
await bugsnag.start(
telemetry: const BugsnagTelemetryTypes(usage: false)
);
Set global user data that you want to send with all captured events – see Adding user data for more information.
await bugsnag.start(
user: BugsnagUser(id: '3', email: 'bugs.nag@bugsnag.com', name: 'Bugs Nag'),
);
Applies to Android only.
We’ll automatically pull the versionCode field from your app manifest file. If you’d like to override this you can set this option manually.
await bugsnag.start(
versionCode: 123,
);