Docs » Supported integrations in Splunk Observability Cloud » Instrument mobile and web applications for Splunk RUM » Instrument iOS applications for Splunk RUM » Manually instrument iOS applications

Manually instrument iOS applications 🔗

You can manually instrument iOS applications for Splunk RUM using the iOS RUM library to collect additional telemetry, sanitize Personal Identifiable Information (PII), add global attributes, and more.

Filter spans 🔗

You can modify or drop spans using the spanFilter function. For example, you can drop or redact spans that contain personally identifiable information (PII).

The following example shows how to remove a span:

options.spanFilter = { spanData in
   var spanData = spanData
   if spanData.name == "DropThis" {
      // Spans with the name "DropThis" aren't sent
      return nil
   }
   var atts = spanData.attributes
   // Change values for all URLs
   atts["http.url"] = .string("redacted")
   return spanData.settingAttributes(atts)
}

Note

Span filtering doesn’t work in Objective-C.

Manage global attributes 🔗

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

The following example shows how to define global attributes in your code:

import SplunkOtel
//..
SplunkRumBuilder(realm: "<realm>", rumAuth: "<rum-token>")
// You can set the globalAttributes option to the map at initialization
   .deploymentEnvironment(environment: "<environment>")
   .setApplicationName("<your_app_name>")
   .build()

// You can also call the ``setGlobalAttributes`` function
// anywhere in your code using the same map
SplunkRum.setGlobalAttributes([])

// To remove a global attribute, pass the key name to removeGlobalAttribute
SplunkRum.removeGlobalAttribute("key2")

Manually change screen names 🔗

By default, the iOS RUM library collects the name set in the ViewController. You can customize the screen names for your application by using the setScreenName function. The custom name persists until your next call to setScreenName.

The following example shows how to customize the name of an account settings screen:

SplunkRum.setScreenName("AccountSettingsTab")

When calling the setScreenName function, automatic screen name instrumentation is deactivated to avoid overwriting custom names.

Note

Use setScreenName in all the views of your application to avoid inconsistent names in your data.

Add user metadata using global attributes 🔗

By default, the iOS RUM library doesn’t automatically link traces to users of your site. However, you might need to collect user metadata to filter or debug traces.

You can identify users by adding global attributes from the OpenTelemetry specification, such as enduser.id and enduser.role, to your spans.

The following examples show how to add identification metadata as global attributes when initializing the agent or after you’ve initialized it, depending on whether user data is accessible at initialization:

Add identification metadata during initialization 🔗

import SplunkOtel
//..
SplunkRumBuilder(realm: "<realm>", rumAuth: "<rum-token>")
   .globalAttributes(globalAttributes: ["enduser.id": "user-id-123456"])
   .build()

Add identification metadata after initialization 🔗

SplunkRum.setGlobalAttributes(["enduser.id": "user-id-123456"])
SplunkRum.setGlobalAttributes(["enduser.id": "128762"]);
SplunkRum.setGlobalAttributes(["enduser.role': "premium"]);

Report custom events 🔗

You can use the OpenTelemetry Swift APIs to report custom events happening in your iOS application.

The following example shows how to use the OTel Swift API to report on a function you want to time:

func calculateTax() {
   let tracer = OpenTelemetrySDK.instance.tracerProvider.get(instrumentationName: "MyApp")
   let span = tracer.spanBuilder(spanName: "calculateTax").startSpan()
   span.setAttribute(key: "numClaims", value: claims.count)
   span.setAttribute(key: "workflow.name", value: "<your_workflow>") // This allows the event to appear in the UI
 //...
 //...
   span.end() // You can also use defer for this
}

Alternatively, you can also use the following snippet:

func calculateTax() {
   let tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "MyApp", instrumentationVersion: nil)
   let span = tracer.spanBuilder(spanName: "calculateTax").startSpan()
   span.setAttribute(key: "numClaims", value: claims.count)
 //...
 //...
   span.end() // You can also use defer for this
}

This other example shows how to record an event with no duration, that is, which happens in an instant:

let dictionary: NSDictionary = [
                  "attribute1": "hello",
                  "attribute2": "world!",
                  "attribute3": 3
]
SplunkRum.reportEvent(name: "testEvent", attributes: dictionary)

Configure error reporting 🔗

You can report handled errors, exceptions, and messages using the reportError function.

The following example shows how to report the example_error:

SplunkRum.reportError(example_error)

reportError overloads are available for String, Error, and NSException.

Add server trace context from Splunk APM 🔗

The iOS RUM library collects server trace context using back-end data provided by 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=4bf92f3577b34da6a3ce929d0e0e4736
parent-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.

Next steps 🔗

This page was last updated on Jul 09, 2024.