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 a key-value pair as global attributes:

To add metadata during agent initialization:

SplunkOtelFlutter.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:

 SplunkOtelFlutter.instance.globalAttributes.globalAttributesSetInt(
      key: "user_id",
      value: 123,
    );

 SplunkOtelFlutter.instance.globalAttributes.globalAttributesSetString(
      key: "user_name",
      value: "John",
    );

Report custom events and workflows

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

    SplunkOtelFlutter.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:

   SplunkOtelFlutter.instance.customTracking.trackWorkflow(
      workflowName: "Workflow test",
    );

Automatic navigation detection

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

Manually track navigation events

By default, the Splunk RUM Flutter agent does not track navigation events automatically. If you enable automatic tracking, the agent tracks the following:

• Android: Lifecycle of Activity and Fragment instances. However, this approach does not work for certain UI frameworks, such as Jetpack Compose, which do not follow the same lifecycle patterns.

• iOS: UIKit view-controller lifecycle callbacks. It observes show/transition notifications to open and close spans and derives screen names from the controller type. Because this depends on UIKit-driven controller transitions, it does not work for UI stacks like pure SwiftUI.

Due to the limitations mentioned above, manual tracking can be the best practice:

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

This sends a navigation span to Splunk RUM and remembers the screen name for 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.