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,
          ],
        ),
      ],
    ),
  ],
);

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.

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

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 navigation module records a navigation event when the screen changes and adds screen.name to subsequent telemetry.
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.

Automatically track Flutter screen navigation

The Splunk RUM Flutter agent can automatically report route changes and associate subsequent RUM telemetry with the current screen.

Add a SplunkNavigatorObserver to your app's navigator. The observer tracks named route pushes, pops, and replacements.

Flutter Navigator

Create the observer outside build() and add it to MaterialApp:

DART 
final splunkNavigatorObserver = SplunkNavigatorObserver();

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

The observer uses RouteSettings.name as screen.name. Use named routes or provide a custom name resolver for unnamed routes.

This works with both the Navigator API (Navigator 1.0) and the Router and Pages API (Navigator 2.0). For the Router API, add the observer to the Navigator that your RouterDelegate builds.

go_router

If your application uses go_router, pass the observer to GoRouter:
DART 
final splunkNavigatorObserver = SplunkNavigatorObserver();

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

MaterialApp.router(
  routerConfig: router,
);

auto_route

If your application uses auto_route, return a new observer from its observer factory:

DART 
final appRouter = AppRouter();

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

Customize screen names and attributes

Pass predicates to rename screens, filter which screens are tracked, or attach attributes.

The following example renames the checkout route and adds a custom attribute to its navigation event:

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

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

    return MutableAttributes(
      attributes: {
        'checkout.flow': MutableAttributeString(value: 'standard'),
      },
    );
  },
);
To exclude a route:
CODE 
final splunkNavigatorObserver = SplunkNavigatorObserver(
  shouldTrackView: (route) => route.settings.name != '/debug',
);
Keep these callbacks lightweight because Flutter invokes them during navigation. The following table describes common SplunkNavigatorObserver configuration.

The following table describes common SplunkNavigatorObserver configuration:

Option Description Default
viewNamePredicate Renames a screen. Return null or an empty string to skip it. Route name
shouldTrackView Returns whether a route should be tracked. true
attributesFromRoute Adds custom attributes to the navigation event. No attributes
trackInitialRoute Reports the first route displayed by the app. true
trackPopupRoutes Reports named dialogs, sheets, and other popup routes. false
Supported navigation behavior

  • The screen name comes from the route's settings.name, or from viewNamePredicate when provided. Unnamed routes are skipped, so prefer named routes or set RouteSettings(name: ...).

  • The observer tracks the navigator it is attached to, which is the app's root navigator. Nested navigators such as per-tab stacks or shell routes need the observer added to each of them.

  • Popup routes such as dialogs, bottom sheets, and menus are not reported by default. Set trackPopupRoutes to true and provide a name to include them.

  • Tab switches that do not push a route, for example IndexedStack or BottomNavigationBar, are not reported.

  • Create the observer once, for example as a field on your widget or on the router that holds it, rather than inside build(). With go_router, create the GoRouter once. With auto_route, the navigatorObservers builder returns a fresh instance per router.

Manually track navigation

Use manual tracking for custom navigation, tab changes, unnamed routes, or flows that do not produce a Flutter route event.

Track a screen name:
CODE 
await SplunkRum.instance.navigation.track(
  screenName: 'Checkout',
);
Track a screen with attributes:
JSON 
await SplunkRum.instance.navigation.track(
  screenName: 'Checkout',
  attributes: MutableAttributes(
    attributes: {
      'checkout.flow': MutableAttributeString(value: 'express'),
    },
  ),
);
Manual tracking emits a navigation event and updates screen.name so subsequent RUM telemetry is associated with that screen.
(Optional) Native navigation tracking

Native navigation tracking monitors Android Activity and Fragment transitions and iOS UIViewController transitions. It does not detect routes inside Flutter's Navigator.

For most Flutter applications, use SplunkNavigatorObserver and leave native automatic tracking disabled. Enable native tracking only if the application also presents meaningful native screens outside Flutter.

CODE 
await SplunkRum.instance.install(
  agentConfiguration: agentConfiguration,
  moduleConfigurations: [
    NavigationModuleConfiguration(
      isAutomatedTrackingEnabled: true,
    ),
  ],
);
Note: This setting controls native detection only. On a Flutter app the native layer sees the host FlutterActivity or FlutterViewController, not your Dart routes. To also track Flutter route navigation, add a SplunkNavigatorObserver as described in Track Flutter screen navigation above. The observer works independently of this setting.

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.

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),
  ],
);