Flutter Agent Configuration Options - Real User Monitoring

After completing the Flutter Monitoring Setup, use this guide to configure additional agent capabilities. Each section is independent and can be enabled as needed.

Control the Sampling Rate

To manage the volume of data sent to Atatus, set a session sampling rate. The value is a percentage between 0.0 and 100.0, and defaults to 100.0 (every session is kept). Values outside that range are clamped. For example, the following configuration retains 80% of sessions:

final configuration = AtatusConfiguration(
  licenseKey: '<LICENSE_KEY>',
  env: '<ENV_NAME>',
  appName: '<APP_NAME>',
  rumConfiguration: AtatusRumConfiguration(
    sessionSamplingRate: 80.0,
  ),
);

SDK Configuration Options

AtatusConfiguration holds the settings that apply to the whole SDK. licenseKey, env, and appName are required. Everything else has a default:

RUM Configuration Options

AtatusRumConfiguration accepts the following options. All of them are optional:

Manual Initialization and Error Tracking

By default, the SDK is initialized using the AtatusSdk.runApp wrapper which wraps the Flutter runApp execution. Alternatively, you can initialize the SDK manually. This is useful if you need to run custom asynchronous initialization logic before starting the SDK, or if you want to set up custom error boundaries.

To initialize Atatus manually:

1. Call WidgetsFlutterBinding.ensureInitialized() first.
2. Initialize the SDK using AtatusSdk.instance.initialize(...).
3. Capture unhandled Flutter framework errors using FlutterError.onError.
4. Capture asynchronous platform errors using PlatformDispatcher.instance.onError.

import 'dart:ui';
import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';
import 'package:flutter/material.dart';

void main() async {
  // 1. Ensure Flutter bindings are initialized
  WidgetsFlutterBinding.ensureInitialized();

  final configuration = AtatusConfiguration(
    licenseKey: '<LICENSE_KEY>',
    env: '<ENV_NAME>',
    appName: '<APP_NAME>',
    nativeCrashReportEnabled: true,
    rumConfiguration: AtatusRumConfiguration(),
  );

  // 2. Initialize the Atatus SDK manually
  await AtatusSdk.instance.initialize(configuration, TrackingConsent.granted);

  // 3. Capture Flutter framework errors
  FlutterError.onError = (FlutterErrorDetails details) {
    FlutterError.presentError(details);
    AtatusSdk.instance.rum?.handleFlutterError(details);
  };

  // 4. Capture asynchronous platform-level errors
  PlatformDispatcher.instance.onError = (Object error, StackTrace stackTrace) {
    AtatusSdk.instance.rum?.addErrorInfo(
      error.toString(),
      RumErrorSource.source,
      stackTrace: stackTrace,
    );
    return false; // Return false to allow the default platform handler to run
  };

  runApp(const MyApp());
}

Customizing Route and View Names

To customize screen names as they appear in the RUM dashboard, or to assign custom attributes to specific routes, use a custom ViewInfoExtractor callback. This is especially helpful if routes use obfuscated class names or dynamic parameters that you wish to standardize.

Using ViewInfoExtractor

Define a route extractor function that inspects the dynamic route and returns a customized RumViewInfo object. You can fall back to the default behavior using defaultViewInfoExtractor(route) for other routes:

import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';
import 'package:flutter/material.dart';

RumViewInfo? customViewInfoExtractor(Route<dynamic> route) {
  final name = route.settings.name;

  if (name == '/product_detail') {
    return RumViewInfo(
      name: 'Product Details Screen',
      attributes: {
        'page_type': 'e-commerce',
      },
    );
  }

  // Fall back to default name extraction for other routes
  return defaultViewInfoExtractor(route);
}

// Pass the extractor to AtatusNavigationObserver
final observer = AtatusNavigationObserver(
  atatusSdk: AtatusSdk.instance,
  viewInfoExtractor: customViewInfoExtractor,
);

Overriding View Info with RouteAware Mixins

For widgets that implement the standard Flutter RouteAware observer lifecycle, you can mix in the AtatusRouteAwareMixin on the widget's State to override the reported name directly inside the view code:

import 'package:atatus_flutter_plugin/atatus_flutter_plugin.dart';
import 'package:flutter/material.dart';

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> with RouteAware, AtatusRouteAwareMixin {
  // Override rumViewInfo to specify a custom name and extra attributes
  @override
  RumViewInfo get rumViewInfo => RumViewInfo(
        name: 'Home Dashboard Screen',
        attributes: {'source': 'main_nav'},
      );

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(child: Text('Home')),
    );
  }
}

Custom Action Labels

For custom widgets where the RumUserActionDetector cannot infer a meaningful label, annotate the widget with a description using RumUserActionAnnotation. This ensures the action appears with a human-readable name in the Atatus dashboard:

RumUserActionAnnotation(
  description: 'Favorite button',
  child: InkWell(
    onTap: onTap,
    child: const Icon(Icons.favorite),
  ),
);

Track User Sessions

Adding user information to your RUM sessions enables you to follow the journey of a specific user, identify which users are most affected by errors, and monitor performance for your most important users.

Use setUserInfo to associate an identity with all RUM events in the current session:

AtatusSdk.instance.setUserInfo(
  '1234',
  name: 'John Doe',
  email: 'john@doe.com',
);

The following attributes are available on all RUM events after this call:

To clear user information (for example, on sign-out), call clearUserInfo:

AtatusSdk.instance.clearUserInfo();

Add Custom User Attributes

You can attach additional custom attributes to the user session. These attributes are automatically applied to all subsequent RUM events, logs, and traces:

AtatusSdk.instance.addUserExtraInfo({
  'plan': 'premium',
  'company_id': 'acme-corp',
});

To remove an existing attribute, set its value to null:

AtatusSdk.instance.addUserExtraInfo({
  'company_id': null,
});

You can also pass these attributes when you set the user, using the extraInfo parameter of setUserInfo.

Track Accounts

For business-to-business applications, you can record the account a user belongs to, alongside the user identity:

AtatusSdk.instance.setAccountInfo(
  id: 'acme-corp',
  name: 'Acme Corporation',
  extraInfo: {'plan': 'enterprise'},
);

// Add more attributes later
AtatusSdk.instance.addAccountExtraInfo({'seats': 250});

// Clear on sign-out
AtatusSdk.instance.clearAccountInfo();

Set Custom Global Attributes

To attach contextual metadata to every RUM event emitted by the SDK, use global attributes. These are useful for filtering and grouping data in the Atatus dashboard, for example by feature flag, A/B test variant, or store identifier.

// Add a global attribute
AtatusSdk.instance.rum?.addAttribute('store_id', 'store-42');
AtatusSdk.instance.rum?.addAttribute('ab_test_group', 'variant_b');

// Remove an attribute when no longer needed
AtatusSdk.instance.rum?.removeAttribute('ab_test_group');

To scope attributes to the current view instead of the whole session, use addViewAttribute, addViewAttributes, removeViewAttribute, and removeViewAttributes:

AtatusSdk.instance.rum?.addViewAttribute('checkout_step', 'payment');
AtatusSdk.instance.rum?.removeViewAttribute('checkout_step');

Manually Track User Actions

The RumUserActionDetector widget captures common tap interactions automatically. For interactions it cannot detect, such as programmatic triggers, long presses, or scroll events, use manual action tracking.

Instantaneous Actions

For discrete actions (taps, clicks), use addAction:

void _onDownloadTapped(String resourceName) {
  AtatusSdk.instance.rum?.addAction(
    RumActionType.tap,
    resourceName,
  );
}

Continuous Actions

For time-bound actions (scrolls, swipes), use startAction and stopAction:

void _onScrollStart() {
  AtatusSdk.instance.rum?.startAction(
    RumActionType.scroll,
    'Product List Scroll',
  );
}

void _onScrollEnd() {
  AtatusSdk.instance.rum?.stopAction(
    RumActionType.scroll,
    'Product List Scroll',
  );
}

Manually Track Custom Resources

In addition to the automatic resource tracking provided by the Dio interceptor and the Atatus Tracking HTTP Client, you can manually track network requests or third-party API calls that are not covered by automatic instrumentation.

// Start tracking a resource
AtatusSdk.instance.rum?.startResource(
  'resource-key',
  RumHttpMethod.get,
  'https://api.example.com/data',
);

// On successful completion
AtatusSdk.instance.rum?.stopResource(
  'resource-key',
  200,
  RumResourceType.fetch,
);

If the resource request fails, report the error using stopResourceWithErrorInfo, which takes a message and an error type:

AtatusSdk.instance.rum?.stopResourceWithErrorInfo(
  'resource-key',
  'Connection timed out',
  'network',
);

If you are holding the caught Exception, pass it to stopResourceWithError instead:

try {
  // ...
} on Exception catch (e) {
  AtatusSdk.instance.rum?.stopResourceWithError('resource-key', e);
}

Custom Performance Timings

Measure custom performance milestones within a view using addTiming. The timing is recorded relative to the start of the current RUM view, making it ideal for tracking content render times, hero image loads, or any application-specific milestone.

void _onHeroImageLoaded() {
  AtatusSdk.instance.rum?.addTiming('hero_image');
}

void _onContentRendered() {
  AtatusSdk.instance.rum?.addTiming('content_rendered');
}

After the timing is set, it is accessible as @view.custom_timings.<timing_name> (for example, @view.custom_timings.hero_image). Use these values to create custom measures and visualizations in the Atatus dashboard.

Track Feature Flags

Record which variant of a feature flag a user saw, so you can compare errors and performance between variants:

AtatusSdk.instance.rum?.addFeatureFlagEvaluation('new_checkout', true);
AtatusSdk.instance.rum?.addFeatureFlagEvaluation('pricing_page', 'variant_b');

The evaluation is attached to the current view and to the events collected in it.

Track Feature Operations

Feature operations measure a business workflow that can succeed or fail, such as a checkout or an onboarding flow:

AtatusSdk.instance.rum?.startFeatureOperation('checkout');

// On success
AtatusSdk.instance.rum?.succeedFeatureOperation('checkout');

// On failure
AtatusSdk.instance.rum?.failFeatureOperation(
  'checkout',
  RumFeatureOperationFailureReason.error,
);

The failure reason is one of RumFeatureOperationFailureReason.error (an error during execution), .abandoned (the user or process gave up), or .other.

Pass operationKey when several instances of the same operation can run at once, and attributes to attach context to the operation.

Manual View Tracking

The AtatusNavigationObserver cannot see every kind of navigation, such as a custom navigator or a widget that swaps content in place. In those cases, start and stop views yourself:

AtatusSdk.instance.rum?.startView('checkout-screen', 'Checkout');

// When the user leaves
AtatusSdk.instance.rum?.stopView('checkout-screen');

The key must be the same in both calls. If you omit the name, the key is used as the view name.

Stop the Current Session

Use stopSession to end the active RUM session. The next user interaction starts a new one. This is useful at sign-out, when you want the next session to be attributed to a different user:

AtatusSdk.instance.rum?.stopSession();

Modify or Drop RUM Events

To modify the attributes of a RUM event before it is sent to Atatus, or to drop an event entirely, use Event Mappers during SDK configuration. Each mapper is a function with the signature (T) → T? where T is a concrete RUM event type. Returning null from a mapper drops the event.

final configuration = AtatusConfiguration(
  licenseKey: '<LICENSE_KEY>',
  env: '<ENV_NAME>',
  appName: '<APP_NAME>',
  rumConfiguration: AtatusRumConfiguration(
    viewEventMapper: (event) => event,
    actionEventMapper: (event) => event,
    resourceEventMapper: (event) {
      // Redact sensitive URL segments before sending
      event.resource.url = redactUrl(event.resource.url);
      return event;
    },
    errorEventMapper: (event) => event,
    longTaskEventMapper: (event) => event,
    vitalOperationStepEventMapper: (event) => event,
  ),
);

The following event properties can be modified:

Retrieve the RUM Session ID

Retrieving the current RUM session ID is helpful for troubleshooting. You can attach it to support tickets, bug reports, or internal logs to correlate user-reported issues with the corresponding session in the Atatus dashboard.

final sessionId = await AtatusSdk.instance.rum?.getCurrentSessionId();

Clear All Data

Use clearAllData to wipe all locally queued data that has not yet been transmitted to Atatus. This is useful for implementing user data deletion requests or clearing state after a user logs out.

AtatusSdk.instance.clearAllData();

Track Work in a Background Isolate

The SDK is initialized in your root isolate. Work running in a background isolate does not see it, so requests and errors from there are not reported until you attach:

await AtatusSdk.instance.attachToBackgroundIsolate();

Call this inside the background isolate, after the SDK has been initialized in your root isolate.

Attach to an Existing Native SDK

If your Flutter code runs inside an existing Android application that already initializes the native Atatus SDK, do not initialize the SDK again from Dart. Attach to the running instance instead:

await AtatusSdk.instance.attachToExisting(
  AtatusAttachConfiguration(
    detectLongTasks: true,
    longTaskThreshold: 0.1,
    traceSampleRate: 100.0,
    reportFlutterPerformance: false,
    firstPartyHosts: ['api.example.com'],
  ),
);

AtatusAttachConfiguration covers only the Dart side of the SDK. Settings that belong to the native SDK, such as the license key, the environment, and the sample rate, keep the values the host application set.

Logs and RUM are enabled on the Dart side only if the native SDK already has them enabled.

Extend the SDK with Plugins

Plugins let a package hook into the SDK lifecycle. The network integrations use this mechanism, which is why enableHttpTracking() is a call on the configuration rather than on the SDK.

Add a plugin when you build your configuration:

final configuration = AtatusConfiguration(
  licenseKey: '<LICENSE_KEY>',
  env: '<ENV_NAME>',
  appName: '<APP_NAME>',
)..addPlugin(MyPluginConfiguration());

Retrieve a plugin later by its type:

final plugin = AtatusSdk.instance.getPlugin<MyPlugin>();

To write one, implement AtatusPluginConfiguration with a create method that returns your AtatusPlugin. The plugin's initialize method runs once the SDK is ready, and shutdown runs when it stops.

Flutter-Specific Performance Metrics

To enable the collection of Flutter-specific rendering metrics, meaning widget build times and raster (frame render) times, set reportFlutterPerformance to true on AtatusRumConfiguration. These metrics are displayed in the Mobile Vitals section of the Atatus dashboard.

final configuration = AtatusConfiguration(
  licenseKey: '<LICENSE_KEY>',
  env: '<ENV_NAME>',
  appName: '<APP_NAME>',
  rumConfiguration: AtatusRumConfiguration(
    reportFlutterPerformance: true,
  ),
);

Session Replay

Session Replay records what the user saw and did, and links the recording to its RUM session. It ships as a separate package, atatus_session_replay, and is enabled with enableSessionReplay on your AtatusConfiguration:

final configuration = AtatusConfiguration(
  licenseKey: '<LICENSE_KEY>',
  env: '<ENV_NAME>',
  appName: '<APP_NAME>',
  rumConfiguration: AtatusRumConfiguration(),
)..enableSessionReplay(
    AtatusSessionReplayConfiguration(replaySampleRate: 30.0),
  );

Replay also needs a SessionReplayCapture widget at the root of your widget tree. For the full setup, the privacy levels, and per-widget masking, see Flutter Session Replay.

Log Correlation

The Atatus SDK supports sending structured log messages from your Flutter application and correlating them with RUM sessions. When log correlation is enabled, each log entry is automatically linked to the active RUM view and session, providing full context during incident investigation.

For detailed setup instructions, see Flutter Log Collection.

Set Tracking Consent (GDPR)

To comply with GDPR and similar data protection regulations, the SDK requires a tracking consent value at initialization. Three values are available:

• TrackingConsent.pending: the SDK collects and batches data locally but does not transmit it until consent is updated.
• TrackingConsent.granted: the SDK collects data and transmits it to Atatus.
• TrackingConsent.notGranted: the SDK does not collect any data.

Update the consent value at any time after initialization:

AtatusSdk.instance.setTrackingConsent(TrackingConsent.granted);

Sending Data When the Device Is Offline

RUM data is batched and stored locally on the device when no network connection is available. The SDK uploads all stored data automatically once connectivity is restored. No additional configuration is required. This ensures complete data capture regardless of network conditions.