SplunkOtel

main

Star
iOS RUM library and instrumentation
signalfx/splunk-otel-ios

ℹ️  SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.

Splunk OpenTelemetry iOS agent

The Splunk RUM iOS agent provides a swift package that can be added to an app that captures:

  • HTTP requests, via URLSession instrumentation
  • Application startup information
  • UI activity - screen name (typically ViewController name), actions, and PresentationTransitions
  • Crashes/unhandled exceptions via SplunkRumCrashReporting

🚧 This project is currently in BETA. It is officially supported by Splunk. However, breaking changes MAY be introduced.

Getting Started

To get started, import the package into your app, either through the Xcode menu (File -> Swift Packages -> Add Package Dependency or File -> Add Packages) or through your Package.swift:

.package(url: "https://github.com/signalfx/splunk-otel-ios/", from: "0.4.0");
...
.target(name: "MyAwesomeApp", dependencies: ["SplunkOtel"]),

You'll then need to initialize the library with the appropriate configuration parameters. The best place to do this is probably your AppDelegate's ...didFinishLaunchingWithOptions: method:

// Swift example
import SplunkOtel
...
// Your beaconUrl and rumAuth will be provided by your friendly Splunk representative
SplunkRum.initialize(beaconUrl: "https://rum-ingest.us0.signalfx.com/v1/rum", rumAuth: "ABCD...")

or

// Objective-C example
@import SplunkOtel;
...
// Your beaconUrl and rumAuth will be provided by your friendly Splunk representative
[SplunkRum initializeWithBeaconUrl: @"https://rum-ingest.us0.signalfx.com/v1/rum" rumAuth: @"ABCD..." options: nil];

Installation options

Option Type Notes Default
beaconUrl String (required) Destination for captured data (No default)
rumAuth String (required) Publicly-visible rumAuth value. Please do not paste any other access token or auth value into here, as this will be visible to every user of your app (No default)
debug Bool Turns on/off internal debug logging false
allowInsecureBeacon Bool Allows http beacon urls false
globalAttributes [String: Any] Extra attributes to add to each reported span. See also setGlobalAttributes [:]
environment String? Value for environment global attribute nil
ignoreURLs NSRegularExpression? Regex of URLs to ignore when reporting HTTP activity nil
spanFilter ((SpanData) -> SpanData?)? Closure to modify or reject/ignore spans. See example below. nil
showVCInstrumentation Bool Enable span creation for ViewController Show events (not applicable to all UI frameworks/apps) true
screenNameSpans Bool Enable span creation for changes to the screen name true
networkInstrumentation Bool Enable span creation for network activities true
enableDiskCache Bool Enable disk caching of exported spans. All spans will be written to disk and deleted on a successful export. The storage is capped at 64 MB. false

Crash Reporting

Crash reporting is provided via an optional package called SplunkRumCrashReporting. Follow the instructions at that link to enable this feature.

Manual OpenTelemetry instrumentation

Tracing API

You can use the OpenTelemetry Swift APIs to report interesting things in your app. For example, if you had a calculateTax function you wanted 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.end() // or use defer for this
}

Manual Error Reporting

You can report handled errors/exceptions/messages with a convenience API:

SplunkRum.reportError(oops)

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

Managing Global Attributes

Global attributes are key/value pairs added to all reported data. This is useful for reporting app- or user-specfic values as tags. For example, you might add accountType={gold,silver,bronze} to every span (piece of data) reported by the Splunk RUM library. You can specify global attributes in the during SplunkRum.initialize() as options.globalAttributes or use SplunkRum.setGlobalAttributes / SplunkRum.removeGlobalAttribute at any point during your app's execution.

Manually changing screen names

You can set screen.name manually with a simple line of code:

SplunkRum.setScreenName("AccountSettingsTab")

This name will hold until your next call to setScreenName. NOTE: using setScreenName once disables automatic screen name instrumentation, to avoid overwriting your chosen name(s). If you instrument your application to setScreenName, please do it everywhere.

Span Filtering

You can modify or reject spans with a spanFilter function (only supported in Swift, not Objective-C):

options.spanFilter = { spanData in
  var spanData = spanData
  if spanData.name == "DropThis" {
    return nil // spans with this name will not be sent
  }
  var atts = spanData.attributes
  atts["http.url"] = .string("redacted") // change values for all urls
  return spanData.settingAttributes(atts)
}

Integrate with Splunk Browser RUM

Mobile RUM instrumentation and Browser RUM instrumentation can be used simultaneously by sharing the splunk.rumSessionId between the native/iOS instrumentation and the browser/web instrumentation. This allows you to see data from both your native app and your web app combined in one stream.

Requirements

Example

See the following Swift snippet for an example of how to integrate with Splunk Browser RUM:

import WebKit
import SplunkOtel

...
  /* 
Make sure that the WebView instance only loads pages under 
your control and instrumented with Splunk Browser RUM. The 
integrateWithBrowserRum() method can expose the splunk.rumSessionId
of your user to every site/page loaded in the WebView instance.
*/
  let webview: WKWebView = ...
  SplunkRum.integrateWithBrowserRum(webview)

⚠️ Warning: Make sure that the WebView instance only loads pages under your control and instrumented with Splunk Browser RUM. Calling SplunkRum.integrateWithBrowserRum() exposes your user's splunk.rumSessionId to every site/page loaded in the WebView instance.

Version information

  • This library is compatible with iOS 11 and up (and iPadOS 13 and up)
  • This library incorporates opentelemetry-swift v1.0.2

Building and contributing

Please read CONTRIBUTING.md for instructions on building, running tests, and so forth.

License

This library is released under the terms of the Apache Softare License version 2.0. See the license file for more details.

Description

  • Swift Tools 5.3.0
View More Packages from this Author

Dependencies

Last updated: Fri Dec 20 2024 03:52:22 GMT-1000 (Hawaii-Aleutian Standard Time)