iOS API

Setting up the Instana iOS agent

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

static func setup(key: String, reportingURL: URL)

import InstanaAgent

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

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

Current configuration

The Instana class object contains the following properties to retrieve the current configuration:

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

Session identifier

Each Instana agent instance has a unique session identifier that you can 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 of 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. You can manually capture HTTP requests and responses by using URLRequest or URL.

Automatic and manual HTTP monitoring

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

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, you need to add a hint on what view the user is looking at currently. This view name can be set by usingsetView(name: String). The view name is attached to all monitored beacons until you call setView again with another name. Do not use technical or generic names like the Class (that is, WebViewController) to define views. Use readable names for views. For example, product detail page or payment selection. It results in fewer pages with a direct relation to the existing code. Consider setting the view name in viewDidAppear. Setting the view name enables Instana to track page transitions in addition to page loads.

The view name is updated automatically when your app changes the state (for example, from active to inactive or background). The view name is Inactive when your app is in inactive state (when it receives an SMS). It is set to Background after 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 be optionally sent with data that is transmitted to Instana. This information can then be used to unlock more capabilities such as:

• Calculate the number of users affected by errors
• Filter data for specific users
• Find the user that initiated a view change or HTTP request

By default, Instana does not associate any user-identifiable information to beacons. You must check the respective data protection laws before you associate any user-identifiable information to beacons. Identify users with a user ID. For Instana, it is a transparent String that is used only to calculate certain metrics. You can also use userName and userEmail to access more filters to present user information.

If you handle anonymous users and thus don't have access to user IDs you can alternatively use session IDs. Session IDs are not as helpful as user IDs to filter data, but they are good indicators to calculate affected or unique user metrics. Consider setting a username such as Anonymous to clearly distinguish between the authenticated and unauthenticated users. Session IDs can be sensitive data depending on the framework or platform used. Consider hashing session IDs to avoid transmitting data to Instana that can grant access.

Data that is already transmitted to Instana cannot be retroactively updated. Call this API immediately 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 is attached to the transmitted data. Consider using metadata to track UI configuration values, settings, feature flag, or 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 exclude 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 exclude URLs that match with the regular expressions to prevent transmission to Instana. A good example for usage of this function would be to exclude 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 to analyze errors that are not detected (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")
Instana.reportEvent(name: "Event-Name", customMetric: 1234.567)

Enabled or disable collection

You can enable 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 a value, you must pass one of the following values as the log level:

• 0 = Debug information, warnings and error,
• 1 = Warnings and errors,
• 2 => Errors only

Redact URL Query parameters

Query parameters in the collected URLs might contain sensitive data. Therefore, the Instana iOS agent supports the specification of regex patterns for query parameter keys whose values must be redacted. Any redacted value is replaced with <redacted>. Redaction occurs within the Instana agent before it is reported to Instana. Consequently, secrets do not reach Instana for processing. Secrets are not available to analyze in the UI or retrieve 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 is applied only 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])

Slow Sending Mode

Optional: You can turn on the slow sending mode feature.

By default, if a beacon sending fails, the Instana agent tries to resend the beacon until the sending is successful. It doesn't work well with some cellular networks. By enabling the slow sending mode feature, the beacon sending interval is changed to the time value that is assigned to the slowSendInterval parameter. Each sending attempt consists of only one beacon instead of a batch (a maximum 100 beacons in a batch). Instana agent stays in slow sending mode until one beacon is sent successfully.

The valid time range for slowSendInterval is 2-3600 in seconds.

import InstanaAgent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let options = InstanaSetupOptions(slowSendInterval: 60.0)
    if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
        // Error handling here
    }
    ....
    return true
}

User session ID

By default, the user session is tracked. The ID is a randomly generated Universally Unique Identifier (UUID). This ID remains unchanged while the app is installed. You can configure the expiration time of the user session ID by using the usiRefreshTimeIntervalInHrs parameter.

The following parameter values indicate the status of the user session ID:

• Negative number: The user session ID never expires. This is the default setting. The default value is -1.
• Positive number: The user session ID is refreshed after the set time, that is, a new UUID is generated and used.
• Zero: The user session ID is disabled. This value is denoted by 0.0.

import InstanaAgent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let options = InstanaSetupOptions(usiRefreshTimeIntervalInHrs: 24.0)
    if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
        // Error handling here
    }
    ....
    return true
}