[Alpha] Manually instrument Flutter applications

Manually instrument Flutter applications to collect additional telemetry, add global attributes, and more.

Attention:

Alpha features described in this document are provided by Splunk to you "as is" without any warranties, maintenance and support, or service-level commitments. Splunk makes this alpha feature available in its sole discretion and may discontinue it at any time. These documents are not yet publicly available and we ask that you keep such information confidential. Use of alpha features is subject to the Splunk Pre-Release Agreement for Hosted Services.

Alpha documentation links

Tip:

Use these links to navigate through the documentation for this alpha release. These links aren't visible in the left nav.

You can manually instrument Flutter applications using the Splunk RUM Flutter agent to collect additional telemetry, add global attributes, and more.

Manage global attributes

Global attributes are key-value pairs added to all reported data. Global attributes are useful for reporting application- or user-specific values as tags.

The following examples show how to define global attributes:

To add metadata during agent initialization:

SplunkRum.instance.install(
  agentConfiguration: AgentConfiguration(
    globalAttributes: MutableAttributes(
      attributes: {
        "boolKey": MutableAttributeBool(value: true),
        "stringKey": MutableAttributeString(value: "testVal"),
        "intKey": MutableAttributeInt(value: 1),
        "doubleKey": MutableAttributeDouble(value: 1.3),
      },
    ),
  ),
);

To add metadata after agent initialization:

 SplunkRum.instance.globalAttributes.setInt(
  key: "user_id",
  value: 123,
);

SplunkRum.instance.globalAttributes.setString(
  key: "user_name",
  value: "John",
);

Get agent and session state

You can inspect the current SDK state and the active session:

// Get session ID
final sessionId = await SplunkRum.instance.session.state.getId();

// Get session sampling rate
final samplingRate = await SplunkRum.instance.session.state.getSamplingRate();

Track users

By default, the Splunk RUM Flutter agent uses NO_TRACKING. To activate anonymous user tracking, see the codeblock below:

await SplunkRum.instance.user.preferences.setTrackingMode(
  userTrackingMode: UserTrackingMode.anonymousTracking,
);

You can also get the current tracking mode:

final trackingMode = await SplunkRum.instance.user.state.getTrackingMode();

Report custom events and workflows

You can report custom events and workflows happening in your Flutter application using the trackCustomEvent and startWorkflow APIs. Additionally, you have the option to set custom attributes. See example below:

SplunkRum.instance.customTracking.trackCustomEvent(
  name: "Test event",
  attributes: MutableAttributes(
    attributes: {
      "intKeyTrackEvent": MutableAttributeInt(value: 5),
      "stringKeyTrackEvent": MutableAttributeString(value: "val"),
    },
  ),
);

The following example shows how to start a workflow for which metrics are recorded by Splunk RUM:

// Start the workflow and get a handle
final workflow = await SplunkRum.instance.customTracking.startWorkflow(
  name: 'user_login',
);

// ... perform workflow operations ...

// End the workflow to record its duration
await workflow.end();

Automatic navigation detection is deactivated by default. You can activate it by configuring the Navigation detection module (detection of screen names) module.

When automatic tracking is enabled, the agent monitors native navigation components:

Android: Lifecycle of Activity and Fragment instances
iOS: UIKit view-controller lifecycle callbacks

For Flutter route navigation, use manual tracking:

SplunkRum.instance.navigation.track(screenName: "Screen name");

This sends a navigation span to Splunk RUM and associates the screen name with subsequent spans.

Add server trace context from Splunk APM

The Splunk RUM Flutter agent collects server trace context using back-end data provided by Splunk APM instrumentation through the Server-Timing header. In some cases, you might want to generate the header manually.

To create the Server-Timing header manually, provide a Server-Timing header with the name traceparent, where the desc field holds the version, the trace ID, the parent ID, and the trace flag.

Consider the following HTTP header:

Server-Timing: traceparent;desc="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"

The example resolves to a context containing the following data:

version=00 trace-id=4bf92f3577b34da6a3ce929d0e0e4736parent-id=00f067aa0ba902b7 trace-flags=01

When generating a value for the traceparent header, make sure that it matches the following regular expression:

00-([0-9a-f]{32})-([0-9a-f]{16})-01

Server timing headers with values that don't match the pattern are automatically discarded. For more information, see the Server-Timing and traceparent documentation on the W3C website.

If multiple valid Server-Timing headers are found, the last valid one is used.