Manually instrument iOS applications π
You can manually instrument iOS applications for Splunk RUM using the iOS RUM agent 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" {
return nil // Spans with the name "DropThis" are not be sent
}
var atts = spanData.attributes
atts["http.url"] = .string("redacted") // Change values for all URLs
return spanData.settingAttributes(atts)
}
Note
Span filtering is supported only in Swift.
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:
// You can set the globalAttributes option to the map at initialization
import SplunkOtel
//..
SplunkRum.initialize(beaconUrl: "https://rum-ingest.<realm>.signalfx.com/v1/rum",
rumAuth: "<rum-token>",
options: SplunkRumOptions(environment:"<environment-name>"))
options.globalAttributes = ["key1": "value1", "key2": 7]
// You can also call the ``setGlobalAttributes`` function
// anywhere in your code using the same map
SplunkRum.setGlobalAttributes(["key1": "value1", "key2": 7])
// To remove a global attribute, pass the key name to removeGlobalAttribute
SplunkRum.removeGlobalAttribute("key2")
Manually change screen names π
By default, the iOS RUM agent 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 agent 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
//..
SplunkRum.initialize(beaconUrl: "https://rum-ingest.<realm>.signalfx.com/v1/rum",
rumAuth: "<rum-token>",
options.globalAttributes = ["enduser.id": "user-id-123456"]
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
}
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 agent 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.