Configure the Splunk RUM Flutter agent

Configure Splunk RUM instrumentation for your Flutter applications.

AgentConfiguration

You can configure the Splunk RUM Flutter agent to add custom attributes, adapt the instrumentation to your environment and application, customize sampling, and more.

To configure the Splunk RUM Flutter agent, pass the settings to the agent in an AgentConfiguration object. The following example shows how to configure this object with your Splunk RUM token, Splunk realm, application name, and deployment environment

DART 
SplunkRum.instance.install(
  agentConfiguration: AgentConfiguration(
    endpointConfiguration: EndpointConfiguration.forRum(
      realm: 'your-splunk-realm',
      rumAccessToken: 'your-splunk-rum-access-token',
    ),
    appName: 'your-app-name',
    deploymentEnvironment: 'your-environment-name',
  ),
);

General settings

Use the following settings to configure the AgentConfiguration object:

Option Description
appName (required) Sets the application name.
appVersion Sets the application version.
deferredUntilForeground

Defer telemetry until the app is brought to the foreground. Default: false

Android only.
deploymentEnvironment (required) Environment for all the spans produced by the application. For example, dev, test, or prod.
enableDebugLogging Activates debug logging. Default: false
endpointConfiguration

Sets the configuration needed to export data to an endpoint. There are two required inputs:

You don't have to configure endpoints at installation time; you can configure them later using SplunkRum.instance.preferences. See examples.
globalAttributes Attributes to append to every span collected. For an example, see Manage global attributes.
instrumentedProcessName

Compares application ID and process name. If they are the same, the application is visible to user. If not, it is the background process.

Android only.
session

Configured by SessionConfiguration for configuring sessions. It has following properties:

  • samplingRate Activates session ID based sampling and sets a sampling ratio. The sampling ratio is the probability of a session being included. Valid values: 0.0 (all dropped) to 1.0 (all included).
user

Configured by UserConfiguration for end user tracking. It has following properties:

  • trackingMode with a default of NO TRACKING.

AgentPreferences

You can set up endpoint configuration for the agent after installation through SplunkRum.instance.preferences, and read the current endpoint configuration using SplunkRum.instance.state , as in the following examples.

Access:
CODE 
final preferences = SplunkRum.instance.preferences;
Usage:
CODE 
// Using realm and token (recommended for Splunk Observability Cloud)
await SplunkRum.instance.preferences.setEndpointConfiguration(
  endpointConfiguration: EndpointConfiguration.forRum(
    realm: 'your-splunk-realm',
    rumAccessToken: 'your-splunk-rum-access-token',
  ),
);

// Using custom trace endpoint only
await SplunkRum.instance.preferences.setEndpointConfiguration(
  endpointConfiguration: EndpointConfiguration.forTraces(
    tracesEndpoint: Uri.parse('https://custom-endpoint.example.com/v1/traces'),
  ),
);

// Using custom endpoints for both traces and session replay
await SplunkRum.instance.preferences.setEndpointConfiguration(
  endpointConfiguration: EndpointConfiguration.forTracesAndSessionReplay(
    traceEndpoint: Uri.parse('https://custom-endpoint.example.com/v1/traces'),
    sessionReplayEndpoint: Uri.parse('https://custom-endpoint.example.com/v1/logs'),
  ),
);
Read endpoint configuration:
JSON 
final currentEndpoint = await SplunkRum.instance.state.getEndpointConfiguration();
print('Trace endpoint: ${currentEndpoint?.traceEndpoint}');
print('Session replay endpoint: ${currentEndpoint?.sessionReplayEndpoint}');

Instrumentation module settings

You can configure the following modules in the Splunk RUM Flutter agent:

Note: A module's settings only take effect if you activate that module (set its isEnabled attribute to true). All modules except navigation detection are activated by default.

HTTP instrumentation module

The Splunk RUM Flutter agent monitors HTTP requests at the native platform level. This captures requests made through native HTTP clients.

Tip: See what attributes are included when this module is activated.
Okhttp3 (Android only)

This instrumentation automatically modifies the code at build time and adds the necessary hooks for tracing network requests made through the OkHttp3 APIs. To activate this, add the following plugin to your android/build.gradle and android/app/build.gradle files:

GROOVY 
// android/build.gradle
buildscript {
  repositories {
    google()
    mavenCentral()
    
  }
  dependencies {
    classpath("com.splunk:rum-okhttp3-auto-plugin:splunk-rum-version")
  }
}
GROOVY 
// android/app/build.gradle
apply plugin: "com.splunk.rum-okhttp3-auto-plugin"
Note: Build-time instrumentation required. If you don't add the plugin to the application at build time, the runtime OkHttp3AutoModuleConfiguration will have no effect.
Note: There is currently an open issue with Google that may result in a build failure when an application is built with these plugins. It's related to the Jetifier. The issue is tracked in the Google Issue Tracker and can be resolved by setting the enableJetifier flag to false in your gradle.properties file. For example, android.enableJetifier=false

You can opt-in to capture certain request and response headers using the HTTP instrumentation modules. If those headers are available, the resulting span will contain http.request.header.key and http.response.header.key attributes with the header value(s):

DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    HttpUrlModuleConfiguration(
      isEnabled: true,
      capturedRequestHeaders: [
        'authorization',
        'content-type',
        'user-agent',
      ],
      capturedResponseHeaders: [
        'content-type',
        'cache-control',
      ],
    ),
    OkHttp3AutoModuleConfiguration(
      isEnabled: true,
      capturedRequestHeaders: [
        'authorization',
        'accept',
      ],
      capturedResponseHeaders: [
        'content-type',
        'content-length',
      ],
    ),
  ],
);

If you see ByteBuddy resolution errors, enforce the ByteBuddy version:

DART 
configurations.matching { it.name.toLowerCase().contains("bytebuddyclasspath") }.all {
  resolutionStrategy {
    force("net.bytebuddy:byte-buddy:1.14.12")
  }
}
HttpUrlConnection (Android only)

This instrumentation automatically modifies the code at build time and adds the necessary hooks for tracing network requests made via the URLConnection , HttpURLConnection, or HttpsURLConnection APIs. To enable this, add the following plugin to android/build.gradle and android/app/build.gradle.

GROOVY 
// android/build.gradle
buildscript {
  repositories {
    google()
    mavenCentral()
}
  dependencies {
    classpath("com.splunk:rum-httpurlconnection-auto-plugin:splunk-rum-version")
  }
}
GROOVY 
// android/app/build.gradle
apply plugin: "com.splunk.rum-httpurlconnection-auto-plugin"
Note: Build-time instrumentation required. If you don't add the plugin to the application at build time, the runtime configuration will have no effect.
Note: There is currently an open issue with Google that may result in a build failure when an application is built with these plugins. It's related to the Jetifier. The issue is tracked in the Google Issue Tracker and can be resolved by setting the enableJetifier flag to false in your gradle.properties file. For example, android.enableJetifier=false

You can opt-in to capture certain request and response headers using the HTTP instrumentation modules. If those headers are available, the resulting span will contain http.request.header.key and http.response.header.key attributes with the header value(s).

DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    HttpUrlModuleConfiguration(
      isEnabled: true,
      capturedRequestHeaders: [
        'authorization',
        'content-type',
        'user-agent',
      ],
      capturedResponseHeaders: [
        'content-type',
        'cache-control',
      ],
    ),
  ],
);

If you see ByteBuddy resolution errors, enforce the ByteBuddy version:

DART 
configurations.matching { it.name.toLowerCase().contains("bytebuddyclasspath") }.all {
  resolutionStrategy {
    force("net.bytebuddy:byte-buddy:1.14.12")
  }
}
Automatic URLSession instrumentation (iOS only)

Automatically instruments URLSession network requests at the native platform level.

Specify NSRegularExpression patterns to exclude specific URLs from instrumentation.

Tip: See what attributes are included when this module is activated.
DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    NetworkInstrumentationModuleConfiguration(
      isEnabled: true,
      ignoreURLs: [
        RegularExpression(
          pattern: "123",
          options: [
            RegexOption.allowCommentsAndWhitespace,
            RegexOption.anchorsMatchLines,
          ],
        ),
      ],
    ),
  ],
);

Automatic Navigation Instrumentation

Splunk Real User Monitoring can automatically detect route changes in supported Flutter applications. The agent reports an app.ui.navigation event when the active route changes and adds screen.name to subsequent telemetry. This behavior helps you analyze application activity by framework route instead of the native host container.

The framework integration detects the active route and sends its name to the existing native navigation module. The native module creates the navigation signal and maintains the current screen name. You can use automatic tracking with manual navigation calls for custom flows.

Supported Frameworks and Libraries

Flutter automatic navigation instrumentation supports these libraries on the root navigator:

  • Navigator 1.0.
  • Navigator 2.0.
  • go_router.
  • auto_route.

The integrations provide these behaviors:

  • They report the initial route by default.
  • They suppress repeated events when the active route has not changed.
  • They let you rename screens, exclude routes, and add custom attributes.
  • They update screen.name so subsequent spans, logs, crashes, and session-replay frames include the current screen.
  • They remove reserved navigation keys from custom attributes before sending data to the native agent.
Important: Keep native automatic navigation tracking disabled when you use framework route detection. Native tracking sees framework host containers and can produce duplicate events or replace the route name with a native implementation name.

Limitations

Flutter automatic detection has these limitations:

  • It tracks the root navigator only.
  • It skips unnamed routes unless a callback provides a screen name.
  • It does not report tab switches that do not push a route.
  • It does not report popup routes by default.
  • It does not officially support routing libraries other than Navigator 1.0, Navigator 2.0, go_router, and auto_route.

Use manual navigation tracking for unsupported or custom flows.

The agent provides two automatic navigation tracking methods:

  • Native-layer tracking detects Android Activity and Fragment transitions and iOS UIViewController transitions.

  • Framework-layer tracking detects routes managed by Flutter. Register SplunkNavigatorObserver to enable this tracking.

Use SplunkNavigatorObserver for the Flutter agent. Both methods report navigation events and update screen.name.

Note: Do not enable native automatic tracking when you use framework-layer tracking. Enabling both methods can produce duplicate events or report native container names instead of framework route names.

Automatic Navigation Tracking

Track native navigation automatically

Automatic detection monitors native navigation components. Deactivated by default. To activate this module, set isAutomatedTrackingEnabled to true:

DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    NavigationModuleConfiguration(
      isEnabled: true,
      isAutomatedTrackingEnabled: true,
    ),
  ],
);
Note:
  • The isAutomatedTrackingEnabled setting controls native navigation detection only. It monitors Android Activity and Fragment transitions and iOS UIViewController transitions. It does not detect Dart routes in Flutter's Navigator. To track Flutter route changes automatically, add a SplunkNavigatorObserver to your application's root navigator. Keep native automatic navigation tracking disabled when you use the observer. See Track Flutter Screen Navigation.
    Tracking method Native automatic tracking Framework integration
    Native-layer tracking Enabled Not configured
    Flutter route tracking Disabled SplunkNavigatorObserver registered
  • To track navigation events manually, see Track Navigation Manually.

Track Flutter Routes Automatically

Before you start, confirm these conditions:

  • Your installed Splunk RUM Flutter agent provides SplunkNavigatorObserver.
  • The routes that you want to track have names, or you provide a name callback.
  • Native automatic navigation tracking is disabled.

Create the observer once, outside build(), and add it to the root navigator:

DART 
final splunkNavigatorObserver = SplunkNavigatorObserver();

MaterialApp(
  navigatorObservers: [splunkNavigatorObserver],
  home: const HomeScreen(),
);

For Navigator 2.0, add the observer to the Navigator built by the RouterDelegate.

Track go_router Routes Automatically

Add the observer to GoRouter:

DART 
final splunkNavigatorObserver = SplunkNavigatorObserver();

final router = GoRouter(
  observers: [splunkNavigatorObserver],
  routes: [
    // Your routes
  ],
);

MaterialApp.router(
  routerConfig: router,
);

Track auto_route Routes Automatically

Return a new observer from the auto_route observer factory:

DART 
final appRouter = AppRouter();

MaterialApp.router(
  routerConfig: appRouter.config(
    navigatorObservers: () => [
      SplunkNavigatorObserver(),
    ],
  ),
);

Customize Flutter Screen Tracking

Pass callbacks to the observer to rename screens, exclude routes, or add event attributes:

DART 
final splunkNavigatorObserver = SplunkNavigatorObserver(
  viewNamePredicate: (route, defaultName) {
    if (defaultName == '/checkout') {
      return 'Checkout';
    }

    return defaultName;
  },
  shouldTrackView: (route) => route.settings.name != '/debug',
  attributesFromRoute: (route) {
    if (route.settings.name != '/checkout') {
      return null;
    }

    return MutableAttributes(
      attributes: {
        'checkout.flow': MutableAttributeString(value: 'standard'),
      },
    );
  },
);

This table describes the Flutter options:

Option Description Default
viewNamePredicate Changes the reported screen name. Return null or an empty string to skip the screen. Route name
shouldTrackView Returns whether to track the route. true
attributesFromRoute Adds custom route attributes to the navigation event. No attributes
trackInitialRoute Reports the first route displayed by the application. true
trackPopupRoutes Reports named dialogs, sheets, and other popup routes. false

Track Navigation Manually

If automatic tracking does not cover a navigation event, report the event manually. See Manually track navigation events.

Disable Automatic Framework Navigation Tracking

To disable Flutter route tracking, remove SplunkNavigatorObserver from the navigator configuration. You can continue to report navigation manually.

Crash reporting module

Automatically captures crashes on the native platform. Activated by default. To deactivate, see the codeblock below.

Tip: See what attributes are included when this module is activated: Android, iOS.
DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    CrashReportsModuleConfiguration(isEnabled: false),
  ],
);
Note: Dart thread crashes are not tracked by this module.

Application not responding module (Android only)

Monitors the native Android main thread. Detects when the thread is blocked for more than five seconds. Activated by default. To deactivate, see the codeblock below.

Tip: See what attributes are included when this module is activated.
DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    AnrModuleConfiguration(isEnabled: false),
  ],
);

Slow rendering module

Monitors rendering performance at the native platform level. Activated by default. Configure as follows:

Tip: See what attributes are included when this module is activated: Android, iOS.
DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    SlowRenderingModuleConfiguration(
      isEnabled: false,
      interval: const Duration(seconds: 1),
    ),
  ],
);

Interaction detection module

Captures user interaction coordinates and timing at the native platform level. Activated by default. To deactivate, see the codeblock below.

Tip: See what attributes are included when this module is activated: Android, iOS.
DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    InteractionsModuleConfiguration(isEnabled: false),
  ],
);

Network monitoring module

The network monitoring module is included in the new Splunk RUM agent and is activated by default. This module monitors network connectivity and quality at the native platform level. To deactivate, see the codeblock below.

Tip: See what attributes are included when this module is activated: Android, iOS.
DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    NetworkMonitorModuleConfiguration(isEnabled: false),
  ],
);

Application lifecycle monitoring module

The application lifecycle monitoring module is included in the new Splunk RUM agent and is activated by default. This module monitors application lifecycle events (foreground, background, termination) at the native platform level.To deactivate, see the codeblock below.

Note: Info: This module currently cannot be deactivated on iOS.
Tip: See what attributes are included when this module is activated: Android, iOS.
DART 
SplunkRum.instance.install(
  moduleConfigurations: [
    ApplicationLifecycleModuleConfiguration(isEnabled: false),
  ],
);