---
title: Flutter Advanced Configuration
description: Learn how to configure Flutter Monitoring.
breadcrumbs: >-
  Docs > RUM & Session Replay > Application Monitoring > Flutter Monitoring >
  Flutter Advanced Configuration
---

# Flutter Advanced Configuration

If you have not set up the Datadog Flutter SDK for RUM yet, follow the [in-app setup instructions](https://app.datadoghq.com/rum/application/create) or see the [RUM Flutter setup documentation](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/flutter/setup.md). Learn how to set up OpenTelemetry with RUM Flutter. For additional manual instrumentation functions, such as automatic view tracking, see [Flutter Libraries for RUM](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/flutter/integrated_libraries.md).

## Initialization parameters{% #initialization-parameters %}

You can specify the following parameters in your configuration when initializing the SDK.

{% dl %}

{% dt %}
`clientToken`
{% /dt %}

{% dd %}
Required**Type**: StringA client token for RUM or logging/APM. You can obtain this token in Datadog.
{% /dd %}

{% dt %}
`env`
{% /dt %}

{% dd %}
Required**Type**: StringThe environment name sent to Datadog. You can use `env` to filter events by environment (for example, `staging` or `production`).
{% /dd %}

{% dt %}
`site`
{% /dt %}

{% dd %}
Required**Type**: EnumThe Datadog site that data is sent to. Enum values: `us1`, `us3`, `us5`, `eu1`, `us1Fed`, `ap1`, and `ap2`.
{% /dd %}

{% dt %}
`nativeCrashReportEnabled`
{% /dt %}

{% dd %}
Optional**Type**: Boolean**Default**: `false`Enables native crash reporting.
{% /dd %}

{% dt %}
`service`
{% /dt %}

{% dd %}
Optional**Type**: StringThe service name for the application.
{% /dd %}

{% dt %}
`uploadFrequency`
{% /dt %}

{% dd %}
Optional**Type**: Enum**Default**: `average`The frequency at which the Datadog SDK tries to upload data batches. Enum values: `frequent`, `average`, and `rare`.
{% /dd %}

{% dt %}
`batchSize`
{% /dt %}

{% dd %}
Optional**Type**: Enum**Default**: `medium`Defines the Datadog SDK policy for batching data before uploading it to Datadog servers. Larger batches result in larger (but fewer) network requests. Smaller batches result in smaller (but more) network requests. Enum values: `small`, `medium`, and `large`.
{% /dd %}

{% dt %}
`batchProcessingLevel`
{% /dt %}

{% dd %}
Optional**Type**: Enum**Default**: `medium`Defines the maximum number of batches processed sequentially without a delay, within one reading and uploading cycle. With higher levels, more data is sent in a single upload cycle, and more CPU and memory are used to process the data. With lower levels, less data is sent in a single upload cycle, and less CPU and memory are used to process the data. Enum values: `low`, `medium`, and `high`.
{% /dd %}

{% dt %}
`version`
{% /dt %}

{% dd %}
Optional**Type**: StringThe application's version number. Because `version` is a Datadog tag, it must comply with the rules in [Defining Tags](https://docs.datadoghq.com/getting_started/tagging.md#defining-tags).
{% /dd %}

{% dt %}
`flavor`
{% /dt %}

{% dd %}
Optional**Type**: StringThe flavor (variant) of the application. For stack trace deobfuscation, this must match the flavor set during symbol upload.
{% /dd %}

{% dt %}
`firstPartyHosts`
{% /dt %}

{% dd %}
Optional**Type**: List<String>A list of first party hosts, used in conjunction with Datadog network tracking packages. Overrides any values set in `firstPartyHostsWithTracinHeaders`. To specify different headers per host, use `firstPartyHostsWithTracingHeaders` instead.
{% /dd %}

{% dt %}
`firstPartyHostsWithTracingHeaders`
{% /dt %}

{% dd %}
Optional**Type**: Map<String, Set<TracingHeaderType>>A map of first party hosts and the types of tracing headers Datadog automatically injects on resource calls, used in conjunction with Datadog network tracking packages. For example:
```
final configuration = DatadogConfiguration(
 clientToken: <CLIENT_TOKEN>,
 env: `prod`,
 site: DatadogSite.us1,
 firstPartyHostsWithTracingHeaders: {
  'example.com': {TracingHeaderType.b3},
 },
);
```
The `TracingHeaderType` enum has the following values:
- `datadog`: Datadog's [`x-datadog-*` header](https://docs.datadoghq.com/real_user_monitoring/connect_rum_and_traces.md?tab=browserrum#how-are-rum-resources-linked-to-traces)
- `b3`: OpenTelemetry B3 [single header](https://github.com/openzipkin/b3-propagation#single-headers)
- `b3multi`: OpenTelemetry B3 [multiple headers](https://github.com/openzipkin/b3-propagation#multiple-headers)
- `tracecontext`: W3C [trace context header](https://www.w3.org/TR/trace-context/#tracestate-header)

{% /dd %}

{% dt %}
`rumConfiguration`
{% /dt %}

{% dd %}
Optional**Type**: ObjectSee RUM configuration.
{% /dd %}

{% /dl %}

### RUM configuration{% #rum-configuration %}

Use the following parameters for the `DatadogRumConfiguration` class.

{% dl %}

{% dt %}
`applicationId`
{% /dt %}

{% dd %}
Required**Type**: StringThe RUM application ID.
{% /dd %}

{% dt %}
`sessionSamplingRate`
{% /dt %}

{% dd %}
Optional**Type**: Double**Default**: `100.0`The sampling rate for RUM sessions. Must be between `0.0` (no RUM events are sent) and `100.0` (all RUM events are sent).
{% /dd %}

{% dt %}
`traceSampleRate`
{% /dt %}

{% dd %}
Optional**Type**: Double**Default**: `20.0`The sampling rate for resource tracing. Must be between `0.0` (no resources include APM tracing) and `100.0` (all resources include APM tracing).
{% /dd %}

{% dt %}
`traceContextInjection`
{% /dt %}

{% dd %}
Optional**Type**: Enum**Default**: `all`The strategy for injecting trace context into requests. Enum values can be `all` (inject trace context into all requests) or `sampled` (inject trace context into only sampled requests).
{% /dd %}

{% dt %}
`detectLongTasks`
{% /dt %}

{% dd %}
Optional**Type**: Boolean**Default**: `true`Enable or disable long task detection. This capability attempts to detect when an application is doing too much work on the main isolate or native thread, which could prevent your app from rendering at a smooth framerate.
{% /dd %}

{% dt %}
`longTaskThreshold`
{% /dt %}

{% dd %}
Optional**Type**: Double**Default**: `0.1`The amount of elapsed time that distinguishes a *long task*, in seconds. If the main isolate takes more than this amount of time to process a microtask, it appears as a long task in Datadog RUM Explorer. Minimum value: `0.02`. On Flutter Web, which always uses a value of `0.05` seconds, this argument is ignored.
{% /dd %}

{% dt %}
`trackFrustrations`
{% /dt %}

{% dd %}
Optional**Type**: Boolean**Default**: `true`Enables [automatic collection of user frustrations](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/frustration_signals.md).
{% /dd %}

{% dt %}
`vitalUpdateFrequency`
{% /dt %}

{% dd %}
Optional**Type**: Enum**Default**: `average`The preferred frequency for collecting mobile vitals. Enum values: `frequent` (100ms),`average` (500ms), and `rare` (1000ms). To disable mobile vitals collection, set this parameter to `null`.
{% /dd %}

{% dt %}
`reportFlutterPerformance`
{% /dt %}

{% dd %}
Optional**Type**: Boolean**Default**: `false`Enables reporting Flutter-specific performance metrics, including build and raster times.
{% /dd %}

{% dt %}
`customEndpoint`
{% /dt %}

{% dd %}
Optional**Type**: StringA custom endpoint for sending RUM data.
{% /dd %}

{% dt %}
`telemetrySampleRate`
{% /dt %}

{% dd %}
Optional**Type**: Double**Default**: `20.0`The sampling rate for telemetry data, such as errors and debug logs.
{% /dd %}

{% /dl %}

## Tracking from background isolates{% #tracking-from-background-isolates %}

Starting with v3, Datadog Flutter SDK is capable of monitoring from multiple isolates, but monitoring must be initialized from the background isolate:

When initializing your background isolate, call `DatadogSdk.instance.attachToBackgroundIsolate`. For example:

```
Future<void> _spawnIsolate() async {
    final receivePort = ReceivePort();
    receivePort.listen((message) {
      //
    });
    await Isolate.spawn(_backgroundWork, receivePort.sendPort);
  }

void _backgroundWork(SendPort port) async {
  await DatadogSdk.instance.attachToBackgroundIsolate();

  // Your background work
}
```

`attachToBackgroundIsolate` must be called **after** Datadog is initialized in your main isolate, otherwise the call silently fails and tracking is not available.

If you are using [Datadog Tracking HTTP Client](https://pub.dev/packages/datadog_tracking_http_client) to automatically track resources, `attachToBackgroundIsolate` automatically starts tracking resources from the calling isolate. However, using `Client` from the `http` package or `Dio` requires you to re-initialize HTTP tracking for those packages from the background isolate.

## Automatically track resources{% #automatically-track-resources %}

Use the [Datadog Tracking HTTP Client](https://pub.dev/packages/datadog_tracking_http_client) package to enable automatic tracking of resources and HTTP calls from your views.

Add the package to your `pubspec.yaml` and add the following to your initialization file:

```
final configuration = DatadogConfiguration(
  // configuration
  firstPartyHosts: ['example.com'],
)..enableHttpTracking()
```

**Note**: The Datadog Tracking HTTP Client modifies [`HttpOverrides.global`](https://api.flutter.dev/flutter/dart-io/HttpOverrides/current.html). If you are using your own custom `HttpOverrides`, you may need to inherit from [`DatadogHttpOverrides`](https://pub.dev/documentation/datadog_tracking_http_client/latest/datadog_tracking_http_client/DatadogTrackingHttpOverrides-class.html). In this case, you do not need to call `enableHttpTracking`. Versions of `datadog_tracking_http_client` >= 1.3 check the value of `HttpOverrides.current` and use this for client creation, so you only need to make sure to initialize `HttpOverrides.global` prior to initializing Datadog.

To enable Datadog [distributed tracing](https://docs.datadoghq.com/serverless/aws_lambda/distributed_tracing.md), you must set the `DatadogConfiguration.firstPartyHosts` property in your configuration object to a domain that supports distributed tracing. You can also modify the sampling rate for distributed tracing by setting the `traceSampleRate` on your `DatadogRumConfiguration`.

- `firstPartyHosts` does not allow wildcards, but matches any subdomains for a given domain. For example, `api.example.com` matches `staging.api.example.com` and `prod.api.example.com`, not `news.example.com`.

- `DatadogRumConfiguration.traceSampleRate` sets a default sampling rate of 20%. If you want all resources requests to generate a full distributed trace, set this value to `100.0`.

### Track resources from other packages{% #track-resources-from-other-packages %}

While `Datadog Tracking HTTP Client` can track most common network calls in Flutter, Datadog supplies packages for integration into specific networking libraries, including gRPC, GraphQL and Dio. For more information about these libraries, see [Integrated Libraries](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/flutter/integrated_libraries.md).

## Enrich user sessions{% #enrich-user-sessions %}

Flutter RUM automatically tracks attributes such as user activity, views (using the `DatadogNavigationObserver`), errors, native crashes, and network requests (using the Datadog Tracking HTTP Client). See the [RUM Data Collection documentation](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/flutter/data_collected.md) to learn about the RUM events and default attributes. You can further enrich user session information and gain finer control over the attributes collected by tracking custom events.

### Notify the SDK that your view finished loading{% #notify-the-sdk-that-your-view-finished-loading %}

iOS RUM tracks the time it takes for your view to load. To notify the SDK that your view has finished loading, call the `addViewLoadingTime` method on `DatadogRum`. Call this method when your view is fully loaded and ready to be displayed to the user:

```
  DatadogSdk.instance.rum?.addViewLoadingTime(override);
```

Use the `override` option to replace the previously calculated loading time for the current view.

After the loading time is sent, it is accessible as `@view.loading_time` and is visible in the RUM UI.

**Note**: This API is still experimental and might change in the future.

### Add your own performance timing{% #add-your-own-performance-timing %}

In addition to RUM's default attributes, you can measure where your application is spending its time by using `DdRum.addTiming`. The timing measure is relative to the start of the current RUM view.

For example, you can time how long it takes for your hero image to appear:

```
void _onHeroImageLoaded() {
    DatadogSdk.instance.rum?.addTiming("hero_image");
}
```

After you set the timing, it is accessible as `@view.custom_timings.<timing_name>`. For example, `@view.custom_timings.hero_image`.

To create visualizations in your dashboards, [create a measure](https://docs.datadoghq.com/real_user_monitoring/explorer.md?tab=measures#setup-facets-and-measures) first.

### Track user actions{% #track-user-actions %}

You can track specific user actions such as taps, clicks, and scrolls using `DdRum.addAction`.

To manually register instantaneous RUM actions such as `RumActionType.tap`, use `DdRum.addAction()`. For continuous RUM actions such as `RumActionType.scroll`, use `DdRum.startAction()` or `DdRum.stopAction()`.

For example:

```
void _downloadResourceTapped(String resourceName) {
    DatadogSdk.instance.rum?.addAction(
        RumActionType.tap,
        resourceName,
    );
}
```

When using `DdRum.startAction` and `DdRum.stopAction`, the `type` action must be the same for the Datadog Flutter SDK to match an action's start with its completion.

### Track custom resources{% #track-custom-resources %}

In addition to tracking resources automatically using the [Datadog Tracking HTTP Client](https://github.com/DataDog/dd-sdk-flutter/tree/main/packages/datadog_tracking_http_client), you can track specific custom resources such as network requests or third-party provider APIs using the [following methods](https://pub.dev/documentation/datadog_flutter_plugin/latest/datadog_flutter_plugin/):

- `DdRum.startResource`
- `DdRum.stopResource`
- `DdRum.stopResourceWithError`
- `DdRum.stopResourceWithErrorInfo`

For example:

```
// in your network client:

DatadogSdk.instance.rum?.startResource(
    "resource-key",
    RumHttpMethod.get,
    url,
);

// Later

DatadogSdk.instance.rum?.stopResource(
    "resource-key",
    200,
    RumResourceType.image
);
```

The `String` used for `resourceKey` in both calls must be unique for the resource you are calling in order for the Flutter Datadog SDK to match a resource's start with its completion.

### Track custom errors{% #track-custom-errors %}

To track specific errors, notify `DdRum` when an error occurs with the message, source, exception, and additional attributes.

```
DatadogSdk.instance.rum?.addError("This is an error message.");
```

## Track custom global attributes{% #track-custom-global-attributes %}

In addition to the [default RUM attributes](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/flutter/data_collected.md) captured by the Datadog Flutter SDK automatically, you can choose to add additional contextual information (such as custom attributes) to your RUM events to enrich your observability within Datadog.

Custom attributes allow you to filter and group information about observed user behavior (such as the cart value, merchant tier, or ad campaign) with code-level information (such as backend services, session timeline, error logs, and network health).

### Set a custom global attribute{% #set-a-custom-global-attribute %}

To set a custom global attribute, use `DdRum.addAttribute`.

- To add or update an attribute, use `DdRum.addAttribute`.
- To remove the key, use `DdRum.removeAttribute`.

### Track user sessions{% #track-user-sessions %}

Adding user information to your RUM sessions makes it possible to:

- Follow the journey of a given user
- Know which users are the most impacted by errors
- Monitor performance for your most important users

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/browser/advanced_configuration/user-api.73b0cac9af174bfd4322133367d6e968.png?auto=format"
   alt="User API in the RUM UI" /%}

| Attribute   | Type   | Description                                                                     |
| ----------- | ------ | ------------------------------------------------------------------------------- |
| `usr.id`    | String | (Required) Unique user identifier.                                              |
| `usr.name`  | String | (Optional) User friendly name, displayed by default in the RUM UI.              |
| `usr.email` | String | (Optional) User email, displayed in the RUM UI if the user name is not present. |

To identify user sessions, use `DatadogSdk.setUserInfo`.

For example:

```
DatadogSdk.instance.setUserInfo("1234", "John Doe", "john@doe.com");
```

### Add custom user attributes{% #add-custom-user-attributes %}

You can add custom attributes to your user session. This additional information is automatically applied to logs, traces, and RUM events.

To remove an existing attribute, set it to `null`.

For example:

```
DatadogSdk.instance.addUserExtraInfo({
 'attribute_1': 'foo',
 'attribute_2': null,
});
```

## Clear all data{% #clear-all-data %}

Use `clearAllData` to clear all data that has not been sent to Datadog.

```
DatadogSdk.instance.clearAllData();
```

## Modify or drop RUM events{% #modify-or-drop-rum-events %}

**Note**: This feature is not yet available for Flutter web applications.

To modify attributes of a RUM event before it is sent to Datadog or to drop an event entirely, use the Event Mappers API when configuring the Flutter RUM SDK:

```
final config = DatadogConfiguration(
    // other configuration...
    rumConfiguration: DatadogRumConfiguration(
        applicationId: '<YOUR_APPLICATION_ID>',
        rumViewEventMapper = (event) => event,
        rumActionEventMapper = (event) => event,
        rumResourceEventMapper = (event) => event,
        rumErrorEventMapper = (event) => event,
        rumLongTaskEventMapper = (event) => event,
    ),
);
```

Each mapper is a function with a signature of `(T) -> T?`, where `T` is a concrete RUM event type. This allows changing portions of the event before it is sent, or dropping the event entirely.

For example, to redact sensitive information in a RUM Resource's `url`, implement a custom `redacted` function and use it in `rumResourceEventMapper`:

```
    rumResourceEventMapper = (event) {
        var resourceEvent = resourceEvent
        resourceEvent.resource.url = redacted(resourceEvent.resource.url)
        return resourceEvent
    }
```

Returning `null` from the error, resource, or action mapper drops the event entirely; the event is not sent to Datadog. The value returned from the view event mapper must not be `null`.

Depending on the event's type, only some specific properties can be modified:

| Event Type                       | Attribute key                               | Description          |
| -------------------------------- | ------------------------------------------- | -------------------- |
| RumViewEvent                     | `viewEvent.view.url`                        | URL of the view.     |
| `viewEvent.view.referrer`        | Referrer of the view.                       |
| RumActionEvent                   | `actionEvent.action.target?.name`           | Name of the action.  |
| `actionEvent.view.referrer`      | Referrer of the view linked to this action. |
| `actionEvent.view.url`           | URL of the view linked to this action.      |
| RumErrorEvent                    | `errorEvent.error.message`                  | Error message.       |
| `errorEvent.error.stack`         | Stacktrace of the error.                    |
| `errorEvent.error.resource?.url` | URL of the resource the error refers to.    |
| `errorEvent.view.referrer`       | Referrer of the view linked to this action. |
| `errorEvent.view.url`            | URL of the view linked to this error.       |
| RumResourceEvent                 | `resourceEvent.resource.url`                | URL of the resource. |
| `resourceEvent.view.referrer`    | Referrer of the view linked to this action. |
| `resourceEvent.view.url`         | URL of the view linked to this resource.    |

## Retrieve the RUM session ID{% #retrieve-the-rum-session-id %}

Retrieving the RUM session ID can be helpful for troubleshooting. For example, you can attach the session ID to support requests, emails, or bug reports so that your support team can later find the user session in Datadog.

You can access the RUM session ID at runtime without waiting for the `sessionStarted` event:

```
final sessionId = await DatadogSdk.instance.rum?.getCurrentSessionId()
```

## Flutter-specific performance metrics{% #flutter-specific-performance-metrics %}

To enable the collection of Flutter-specific performance metrics, set `reportFlutterPerformance: true` in `DatadogRumConfiguration`. Widget build and raster times are displayed in [Mobile Vitals](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/mobile_vitals.md?tab=flutter).

## OpenTelemetry setup{% #opentelemetry-setup %}

All of Datadog's automatic network tracking packages ([Datadog Tracking HTTP Client](https://pub.dev/packages/datadog_tracking_http_client), [gRPC Interceptor](https://pub.dev/packages/datadog_grpc_interceptor), [GQL Link](https://pub.dev/packages/datadog_gql_link), and [Dio Interceptor](https://pub.dev/packages/datadog_dio)) support distributed traces through both automatic header generation and header ingestion. This section describes how to use OpenTelemetry with RUM Flutter.

### Datadog header generation{% #datadog-header-generation %}

When configuring your tracking client or gRPC Interceptor, you can specify the types of tracing headers you want Datadog to generate. For example, if you want to send `b3` headers to `example.com` and `tracecontext` headers for `myapi.names`, you can do so with the following code:

```
final hostHeaders = {
    'example.com': { TracingHeaderType.b3 },
    'myapi.names': { TracingHeaderType.tracecontext}
};
```

You can use this object during initial configuration:

```
// For default Datadog HTTP tracing:
final configuration = DatadogConfiguration(
    // configuration
    firstPartyHostsWithTracingHeaders: hostHeaders,
);
```

You can then enable tracing as usual.

This information is merged with any hosts set on `DatadogConfiguration.firstPartyHosts`. Hosts specified in `firstPartyHosts` generate Datadog Tracing Headers by default.

## Check first party hosts{% #check-first-party-hosts %}

To determine if a specific URI is a first party host, use `isFirstPartyHost`.

For example:

```
var host = 'example.com'
if (DatadogSdk.instance.isFirstPartyHost(host)){
 print('$host is a first party host.');
}
```

## Further reading{% #further-reading %}

- [Source code for dd-sdk-flutter](https://github.com/DataDog/dd-sdk-flutter)
- [Learn how to explore your RUM data](https://docs.datadoghq.com/real_user_monitoring/explorer.md)
- [Monitor Flutter application performance with Datadog Mobile RUM](https://www.datadoghq.com/blog/monitor-flutter-application-performance-with-mobile-rum/)

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/browser/advanced_configuration/user-api.73b0cac9af174bfd4322133367d6e968.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/browser/advanced_configuration/user-api.73b0cac9af174bfd4322133367d6e968.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="" /%}