Overview

Enable Crash Reporting and Error Tracking to get comprehensive crash reports and error trends with Real User Monitoring.

Your crash reports appear in Error Tracking.

Setup

If you have not set up the Datadog Flutter SDK for RUM yet, follow the in-app setup instructions or see the Flutter setup documentation.

Add native crash reporting

Update your initialization snippet to enable native crash reporting for iOS and Android by setting nativeCrashReportEnabled to true.

For example:

final configuration = DatadogConfiguration(
  clientToken: '<DD_CLIENT_TOKEN>'
  env: '<DD_ENV>'
  site: DatadogSite.us1,
  nativeCrashReportEnabled: true, // Set this flag
  loggingConfiguration: DatadogLoggingConfiguration(),
  rumConfiguration: DatadogRumConfiguration(
    applicationId: '<DD_APP_ID>',
  ),
);
DatadogSdk.instance.initialize(configuration);

If your application suffers a fatal crash, after your application restarts, the Datadog Flutter SDK uploads a crash report to Datadog. For non-fatal errors, the Datadog Flutter SDK uploads these errors with other RUM data.

Upload symbol files to Datadog

Native iOS crash reports are collected in a raw format and mostly contain memory addresses. To map these addresses into legible symbol information, Datadog requires that you upload .dSYM files, which are generated in your application’s build process.

For all crash reports that are built with the --split-debug-info option set and/or with the --obfuscate option set, you need to upload their Android Proguard mapping file and Dart symbol files generated by the Flutter build process.

The @datadog/datadog-ci command line tool supports uploading all of the necessary files (dSYMs, Android Proguard Mapping, and Dart Symbol Files) in one command.

First, install the datadog-ci tool from the instructions above and create a datadog-ci.json file at the root of your project, containing your API key and (optionally) your Datadog site:

{
  "apiKey": "<YOUR_DATADOG_API_KEY>",
  "datadogSite": "datadoghq.eu"  // Optional if you are using datadoghq.com
}

Because this file contains your API key, it should not be checked in to version control.

Alternately, you can set the DATADOG_API_KEY and DATADOG_SITE environment variables.

Then, you can use the following command to upload all the necessary files for symbolication and deobfuscation of your crash reports:

datadog-ci flutter-symbols upload --service-name <your_service_name> --dart-symbols-location <location_of_dart_symbols> --android-mapping --ios-dsyms

Note: Re-uploading a source map does not override the existing one if the version has not changed.

For a full list of options, see the datadog-ci Flutter Symbols documentation.

Limitations

Advanced Configuration - Flavors and Build Numbers

Datadog uses the combination of the service-name, version, and flavor to locate the correct symbols for deobfuscation. For your crash reports to have complete information, the parameters sent to the datadog-ci command and the parameters set in DatadogConfiguration must match exactly.

If you are using app flavors in Flutter, you will need to set the name of the flavor in DatadogConfiguration.flavor since we cannot detect the flavor automatically. You can then pass this to the --flavor parameter of the datadog-ci command:

datadog-ci flutter-symbols upload --service-name <your_service_name> --dart-symbols-location <location_of_dart_symbols> --android-mapping --ios-dsyms --flavor my_flavor

The Datadog SDK will automatically detect the version number of your application specified in your pubspec.yaml up to but not including the build number. If you are using build numbers as part of the version in your application and need to upload symbols for each build, you will need to add the version to DatadogConfiguration.version. You can then pass this to the --version parameter of the datadog-ci command:

datadog-ci flutter-symbols upload --service-name <your_service_name> --dart-symbols-location <location_of_dart_symbols> --android-mapping --ios-dsyms --version 1.2.3+22

Note that Datadog uses tags for versions which do not allow +. All tooling automatically replaces + with - so that the version tags are searchable in Datadog.

Further reading

Additional helpful documentation, links, and articles:

dd-sdk-flutter Source codeGITHUB Learn about Error TrackingDOCUMENTATION