Setup

Overview

Use the Datadog Flutter Plugin to set up Log Management or Real User Monitoring (RUM). The setup instructions may vary based on your decision to use Logs, RUM, or both, but most of the setup steps are consistent.

Prerequisites

First, ensure that you have your environment set up properly for each platform.

Datadog supports Flutter Monitoring for iOS and Android for Flutter 2.8+. Support for Flutter Web is in alpha.

iOS

Your iOS Podfile, located in ios/Podfile, must have use_frameworks! set to true (which is the default in Flutter) and must set its target iOS version >= 11.0.

This constraint is usually commented out on the top line of the Podfile, and should read:

platform :ios, '11.0'

You can replace 11.0 with any minimum version of iOS you want to support that is 11.0 or higher.

Android

For Android, your minSdkVersion version must be >= 19, and if you are using Kotlin, it should be a version >= 1.6.21. These constraints are usually held in your android/app/build.gradle file.

Web

For Web, add the following to your index.html under the head tag:

<script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-logs-v4.js"></script>
<script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-rum-slim-v4.js"></script>

This loads the CDN-delivered Datadog Browser SDKs for Logs and RUM. The synchronous CDN-delivered version of the Browser SDK is the only version supported by the Datadog Flutter Plugin.

Setup

  1. Add the following to your pubspec.yaml file:

    dependencies:
  datadog_flutter_plugin: ^1.3.0

  2. Create a configuration object for each Datadog feature (such as Logs or RUM) with the following snippet. If you do not pass a configuration for a given feature, that feature is disabled.

    // Determine the user's consent to be tracked
final trackingConsent = ...
final configuration = DdSdkConfiguration(
  clientToken: '<CLIENT_TOKEN>',
  env: '<ENV_NAME>',
  site: DatadogSite.us1,
  trackingConsent: trackingConsent,
  nativeCrashReportEnabled: true,
  loggingConfiguration: LoggingConfiguration(
    sendNetworkInfo: true,
    printLogsToConsole: true,
  ),
  rumConfiguration: RumConfiguration(
    applicationId: '<RUM_APPLICATION_ID>',
  )
);

For more information on available configuration options, see the DdSdkConfiguration object documentation.

To ensure the safety of your data, you must use a client token. You cannot use Datadog API keys to configure the Datadog Flutter Plugin.

  • If you are using RUM, set up a Client Token and Application ID.
  • If you are only using Logs, initialize the library with a client token.

For more information about setting up a client token, see the Client Token documentation.

Initialize the library

You can initialize RUM using one of two methods in your main.dart file.

  1. Use DatadogSdk.runApp which automatically sets up Error Tracking.

    await DatadogSdk.runApp(configuration, () async {
  runApp(const MyApp());
})

  2. Alternatively, manually set up Error Tracking and resource tracking. DatadogSdk.runApp calls WidgetsFlutterBinding.ensureInitialized, so if you are not using DatadogSdk.runApp, you need to call this method prior to calling DatadogSdk.instance.initialize.

    runZonedGuarded(() async {
  WidgetsFlutterBinding.ensureInitialized();
  final originalOnError = FlutterError.onError;
  FlutterError.onError = (details) {
    FlutterError.presentError(details);
    DatadogSdk.instance.rum?.handleFlutterError(details);
    originalOnError?.call(details);
  };

  await DatadogSdk.instance.initialize(configuration);

  runApp(const MyApp());
}, (e, s) {
  DatadogSdk.instance.rum?.addErrorInfo(
    e.toString(),
    RumErrorSource.source,
    stackTrace: s,
  );
});

Sample RUM sessions

To control the data your application sends to Datadog RUM, you can specify a sampling rate for RUM sessions while initializing the Flutter RUM SDK as a percentage between 0 and 100. By default, sessionSamplingRate is set to 100 (keep all sessions).

For example, to keep only 50% of sessions, use:

final config = DdSdkConfiguration(
    // other configuration...
    rumConfiguration: RumConfiguration(
        applicationId: '<YOUR_APPLICATION_ID>',
        sessionSamplingRate: 50.0,
    ),
);

To be compliant with the GDPR regulation, the Datadog Flutter SDK requires the trackingConsent value at initialization.

Set trackingConsent to one of the following values:

  • TrackingConsent.pending: The Datadog Flutter SDK starts collecting and batching the data but does not send it to Datadog. It waits for the new tracking consent value to decide what to do with the batched data.
  • TrackingConsent.granted: The Datadog Flutter SDK starts collecting the data and sends it to Datadog.
  • TrackingConsent.notGranted: The Datadog Flutter SDK does not collect any data, which means no logs, traces, or RUM events are sent to Datadog.

To change the tracking consent value after the SDK is initialized, use the DatadogSdk.setTrackingConsent API call.

The SDK changes its behavior according to the new value. For example, if the current tracking consent is TrackingConsent.pending:

  • You change it to TrackingConsent.granted, the SDK sends all current and future data to Datadog;
  • You change it to TrackingConsent.notGranted, the SDK wipes all current data and does not collect any future data.

Further Reading

Additional helpful documentation, links, and articles:

Monitor Flutter application performance with Datadog Mobile RUMBLOG more more Source code for dd-sdk-flutterGITHUB more more Learn how to explore your RUM dataDOCUMENTATION more more