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 π
To add custom attributes, adapt the instrumentation to your environment and application, customize sampling, and more, see Configure the Splunk iOS RUM instrumentation.
To check that your data is in your Splunk RUM for Mobile instance, see Check that your data is coming in.
To troubleshoot, see Troubleshoot iOS instrumentation for Splunk Observability Cloud.