iOS API

Setup

Initialize the Instana iOS agent early in didFinishLaunchingWithOptions by calling the setup function. Do not start Instana delayed. Make sure to call the setup right after the app launch. You can enable or disable Instana delayed by using the Instana.collectionEnabled flag.

static func setup(key: String, reportingURL: URL, httpCaptureConfig: HTTPCaptureConfig = .automatic)

import InstanaAgent

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    Instana.setup(key: "<Your Instana Key>", reportingURL: URL(string: "<Your Instana instance URL>")!)
    ....
    return true
}

Instana.setup(key: <Your Key>, reportingURL: <Your Instana URL>, httpCaptureConfig: .manual)

Current configuration

The Instana class object has some properties to retrieve the current configuration setup:

let key = Instana.key
let url = Instana.reportingURL

Session identifier

Each Instana agent instance has an unique session identifier you could use for other purposes in your app.

let sessionID = Instana.sessionID

Automatic HTTP monitoring

By default HTTP sessions are captured automatically. The Instana iOS agent uses Foundation's NSURLProtocol to monitor HTTP requests and responses. To observe all NSURLSession automatically with NSURLProtocol some method swizzling in the NSURLSession is necessary. To opt out automatic HTTP session monitoring, you must capture every request and response manually.

Manual HTTP monitoring

To capture HTTP sessions manually, you must set up Instana by using the httpCaptureConfig: .manual and use the corresponding functions that are described. You can capture HTTP requests and responses manually by using the URLRequest or URL.

Automatic and manual HTTP monitoring

To capture HTTP sessions automatically and manually you must set up Instana by using the httpCaptureConfig: .automaticAndManual. You can use the automatic instrumentation or optionally capture HTTP requests or responses manually.

static func startCapture(_ request: URLRequest?, viewName: String? = nil) -> HTTPMarker

static func startCapture(url: URL, method: String, viewName: String? = nil) -> HTTPMarker

func set(responseSize: Instana.Types.HTTPSize)

init(response: URLResponse, transactionMetrics: [URLSessionTaskTransactionMetrics]?)

HTTPMarker.Size(header: Instana.Types.Bytes, body: Instana.Types.Bytes, bodyAfterDecoding: Instana.Types.Bytes)

func finish(response: URLResponse?, error: Error?)

let size = HTTPMarker.Size(header: 123, body: 1024, bodyAfterDecoding: 2048)
let result = HTTPCaptureResult(statusCode: statusCode, backendTracingID: "Instana-backend-tracing-id", responseSize: size, error: error)
marker.finish(result: result)

func cancel()

let marker = Instana.startCapture(request, viewName: "User: Details")
URLSession.shared.dataTask(with: request) { data, response, error in
    marker.finish(response: response, error: error)
}.resume()

func urlSession(_ session: URLSession, task: URLSessionTask, didFinishCollecting metrics: URLSessionTaskMetrics) {
    guard let response = task.response else { return }
    marker.set(responseSize: HTTPMarker.Size(response: response, transactionMetrics: metrics.transactionMetrics))
}

let url = URL(string: "https://www.example.com/user/123/details")!
let marker = Instana.startCapture(url: url, method: "GET", viewName: "Home")
YourNetworkManager(url: url, method: "GET") { (statusCode, error) in
    let size = HTTPMarker.Size(header: 123, body: 1024, bodyAfterDecoding: 2048) // optionally
    let backendTracingID = "Instana-backend-tracing-id" // optionally
    let result = HTTPCaptureResult(statusCode: statusCode, backendTracingID: backendTracingID, responseSize: size, error: error)
    marker.finish(result: result)
}.resume()

Views

Instana can segment app metrics by logical views. To do so, it needs a hint what view the user is currently looking at. This view name can be set via the setView(name: String). The view name will be attached to all monitored beacons until you call setView again with another name. Generally speaking, we recommend not to use technical or generic names like the Class (i.e. WebViewController) to define views. We recommend the usage of readable names for views. For example product detail page or payment selection. This will result in fewer pages which will have a direct relation to actually existing code. We recommend to set the view name in viewDidAppear. Setting the view name will also enable Instana to track page transitions in addition to page loads.

The view name gets updated automatically when your app changes the state (e.g. from active to inactive or background). The view name will be Inactive when your app is in the inactive state (when receiving a SMS) and will be set to Background once your app leaves the foreground.

static func setView(name: String)

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    Instana.setView(name: "User: Details")
}

let viewName = Instana.viewName

Identifying Users

User-specific information can optionally be sent with data transmitted to Instana. This information can then be used to unlock additional capabilities such as:

• calculate the number of users affected by errors,
• to filter data for specific users and
• to see which user initiated a view change or HTTP request.

By default, Instana will not associate any user-identifiable information to beacons. Please be aware of the respective data protection laws when choosing to do so. We generally recommend identification of users via a user ID. For Instana this is a completely transparent String that is only used to calculate certain metrics. userName and userEmail can also be used to have access to more filters and a more pleasant presentation of user information.

In cases in which you are handling anonymous users and thus don't have access to user IDs you could alternatively use session IDs. Session IDs are not as helpful as user IDs when filtering data but they are a good indicator to calculate affected/unique user metrics. We recommend setting a user name such as Anonymous to have a clear differentiation between authenticated and unauthenticated users. Session IDs can be sensitive data (depending on the framework/platform used). Please consider hashing session IDs to avoid transmitting data to Instana that can grant access.

It is important to note that data already transmitted to Instana's server cannot be retroactively updated. For this reason it is important to call this API as soon as possible in the app launch process.

static func setUser(id: String, email: String?, name: String?)

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
     Instana.setUser(id: someID, email: "email@example.com", name: "John")
     return true
}

static func setUser(id: String)

static func setUser(email: String)

static func setUser(name: String)

Metadata

Metadata information that is attached to the transmitted data. Consider using to track UI configuration values, settings, feature flags… any additional context that might be useful for analysis. You should set the metadata in the app launch process to assign the key or values to all transmitted data.

static func setMeta(value: String, key: String)

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
    Instana.setMeta(value: "ReactNative", key: "Platform")
    Instana.setMeta(value: "DEBUG", key: "Environment")
    return true
}

Excluding URLSession from monitoring

You can ignore a custom URLSession from being monitored by the Instana iOS agent.

static func ignore(_ session: URLSession)

let session = URLSession(configuration: .default)
Instana.ignore(session)

Excluding URLs from monitoring

You can ignore URLs to reject that match with the given regular expressions to prevent transmission to Instana. A good example for usage of this function would be to ignore all HTTP requests that contain any sensitive data like a password.

static func setIgnoreURLs(matching regex: [NSRegularExpression])

let regex = try! NSRegularExpression(pattern: "/.*(&|\?)password=.*/i")
Instana.setIgnoreURLs(matching: [regex])

Instana.setIgnore(urls: [URL(string: "https://www.example.com")!])

Report custom events

Custom events enable reporting about nonstandard activities, important interactions, and custom timings to Instana. It can be especially helpful when analyzing uncaught errors (breadcrumbs) and to track more performance metrics.

static func reportEvent(name: String, timestamp: Instana.Types.Milliseconds? = nil, duration: Instana.Types.Milliseconds? = nil, backendTracingID: String? = nil, error: Error? = nil, meta: [String: String]? = nil, viewName: String? = Instana.viewName)

Instana.reportEvent(name: "Event-Name")
Instana.reportEvent(name: "Event-Name", viewName: "User: Details")
Instana.reportEvent(name: "Event-Name", timestamp: 1590149955086, duration: 124842, backendTracingID: "some-id", error: NSError(domain: "Some", code: -1, userInfo: nil), meta: ["Key": "Value"], viewName: "User: Details")

Enabled or disable collection

You can enable or disable the data collection at any time during the runtime. It enables the delayed start of the data collection (for example after user consent).

Instana.collectionEnabled = true

Enable logging

The Instana iOS agent has a logging capability for debugging purposes. Just add the environment variable INSTANA_DEBUG_LOGLEVEL in Xcode. As value you must pass the number for the log level: 0 = Debug information, warnings and error, 1 = Warnings and errors, 2 => Errors only

Redact URL Query parameters

Query parameters in collected URLs may contain sensitive data. Therefore, the Instana iOS agent supports the specification of regex patterns for query parameter keys whose values should be redacted. Any redacted value will be replaced with <redacted>. Redaction happens within the Instana agent, before reporting to the Instana server. Consequently, secrets will not reach the Instana servers for processing and will not be available for analysis in the UI or retrieval by using Instana API.

By default, the Instana iOS agent is configured with a list of three regex patterns to automatically redact query parameter values for the keys: "password", "key" and "secret". Redaction will only be applied to automatically monitored requests and their associated logs. Manually monitored requests are not redacted.

static func redactHTTPQuery(matching regex: [NSRegularExpression])

let regex = try! NSRegularExpression(pattern: #"pass(word|wort)"#)
Instana.redactHTTPQuery(matching: [regex])

Capture HTTP header fields

HTTP request and response headers can be captured by the iOS agent. You can use regular expressions to define the keys of the HTTP header fields that the iOS agent needs to capture.

public static func setCaptureHeaders(matching regex: [NSRegularExpression])

let regex = try! NSRegularExpression(pattern: #"X-Key"#, options: [.caseInsensitive])
Instana.setCaptureHeaders(matching: [regex])