iOS Monitoring FAQ

Data collection and reporting

Which app data is collected?

Along with the Instana monitoring, the mobile agent automatically collects the following app-specific information:

  • Bundle identifier.
  • App and build version.
  • Current app language.
  • iOS / Android version, device model, hardware, device, and manufacturer.
  • If a device is jailbroken/rooted.
  • Screen size and resolution.
  • Carrier name and connection type (3G or 4G).

How is beacon reporting handled?

We collect all incoming beacons in a queue, which are flushed one second (ten seconds if the battery is low) after the last beacon has arrived. All beacons are transmitted in one HTTP request and there is a limit of 100 beacons per request. When the queue exceeds the limit of 100 items, any beacons that arrive are discarded. A compact format is used to save data traffic for data transmission. Until the beacons are reported to Instana, the queue uses a protected persistence layer to store all beacons which ensures that no beacon is lost if the app crashes or suddenly closes. To avoid blocking the main thread (UI), reporting and queue handling is performed in a background thread.

What happens if reporting fails?

Due to network problems, beacon reporting may fail. The beacons are retained in the queue for the next transmission attempt.

Is there data collection when being offline?

Yes, however, consider the limit of 100 beacons described above. If the queue is full and cannot be flushed (due to network issues) all upcoming beacons are discarded.

Is it possible to proxy the HTTP endpoints (for SaaS)?

We recommend not to attempt the proxying of the HTTP endpoints. Instana does not provide any support for any proxy setups nor for any issues that may arise due to the usage of a proxy. Should you still want (or have) to do this, you may find these pointers helpful:

  • Set proper Host HTTP headers.
  • Respect the difference between the and eum-{region} servers.
  • Make sure that our servers are aware of the end-users IPs. Send an X-FORWARDED-FOR header to our servers with the end-user’s IP. Alternatively send a X-REALER-IP HTTP header (yes, deliberately not X-REAL-IP) to the Instana servers which contains the end-user’s IP.
  • Pass through all the HTTP headers that the Instana servers include in the response body.
  • Don’t do any caching in the proxy.

HTTP Monitoring

Which HTTP information is monitored?

  • The duration of the request.
  • HTTP method (POST, GET…).
  • Full URL and path.
  • Status code (e.g. 200).
  • Response sizes (header, body, decoded body).
  • Any underlying error.
  • Backend tracing ID for the backend correlation.

What is the difference between auto and manual HTTP monitoring?

The iOS agent offers automatic and manual monitoring of HTTP sessions.


To monitor HTTP requests and reponses going through the URLSession, the automatic HTTP monitoring uses the Foundation’s URLProtocol. All captured requests and responses are reported to Instana. While the default URLSession can be intercepted implicitly by URLProtocol, all custom sessions require an explicit URLProtocol registration for monitoring. Because many applications have a custom URLSession, the registration process for those sessions is not the ideal solution for the Instana iOS agent. To simplify the registration process, all sessions are registered implicitly by swizzling the initializer of all URLSessions. With the swizzling approach, no registration of the URLProtocol is required and it simplifies automatic HTTP monitoring.


By capturing the HTTP request & response manually, the client can opt-out from automatic monitoring and swizzling. No URLProtocol is installed to the URLSessions. Manual monitoring means that when capturing HTTP requests and responses, it requires more effort to use the monitoring by the client.

iOS: Can I use my own URLProtocol with automatic monitoring enabled?

Yes, you can create your own URLProtocol to proxy your requests and responses through a custom URLSession. Instana HTTP monitoring automatically ignores any URLSession that has an URLProtocol as delegate. But you can also explicitly ignore any custom URLSession from being monitored via Instana.ignore(yourURLSession). If you are using an URLSession inside your own URLProtocol without a delegate, you should ignore this session in the Instana iOS agent. Otherwise, the request and response is doubled monitored.

iOS: Isn’t swizzling dangerous?

Not always. Swizzling in the runtime is mostly done by adding a new method:

func swizzled_touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
  // looks weird, but it calls the original implementation
   swizzled_touchesBegan(touches, with: event)
   print("do some custom magic here")

And then the new and old methods will be exchanged via:

if let originalMethod = class_getInstanceMethod(UIResponder.self, #selector(touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?))),
   let swizzledMethod = class_getInstanceMethod(UIResponder.self, #selector(swizzled_touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?))) {
        method_exchangeImplementations(originalMethod, swizzledMethod)

However, this could lead to unexpected behavior when the runtime makes a forward invocation like in UIResponder. Sometimes the runtime sometimes performs message forwarding. This swizzling technique could cause a crash if a message (i.e. the new swizzled_touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?)) is forwarded to another receiver on which the new method does not exist. In the Instana iOS agent, we don’t add a second method to the class. We set our new implementation directly (via a block) to the original selector and therefore override the original implementation. The original implementation, temporarly stored, is then called inside the new function; so our swizzling leaves no traces.

iOS: Is monitoring for background sessions available?

No, because custom URLProtocol subclasses are not available to background sessions. (see URLSession doc.)

How does backend correlation work with HTTP requests?

All HTTP requests have backend correlation. You don’t need to track or set anything on the client side. The backend must have an running Instana Agent to map the HTTP requests.

Which HTTP headers are being used?

To achieve backend correlation, the agent makes use of the following HTTP headers:

  • Request Headers (to the backend):

  • Response Headers (to the frontend):

    • Server-Timing


Which iOS versions are supported?

iOS: Instana iOS agent is compatible from iOS 11.

Which Swift Version is minimal needed?

iOS: Instana iOS agent uses Swift 5, which is ABI stable.

How do I install the iOS agent?

iOS: Use the Swift Package Manager inside Xcode. Alternatively, you can use CocoaPods. To setup the Instana iOS agent, call one method in application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:.

Sensitive data

Are you collecting data which can uniquely identify users?

By default, the Instana iOS agent, does not include data which can unique identify users. Additionally, the agent also does not apply techniques such as device fingerprinting.

User specific data can be made available to Instana via the iOS user API.

What are you doing with the user data transmitted to Instana?

The iOS user API can be configured by customers to transmit user identifying information to Instana. This information is only used to provide the features visible within the product. Instana does not interpret this data in any other way, nor is it correlated across multiple customers.

Is it possible to delete user data after it has been transmitted to Instana?

Infrequent deletion requests, e.g. to comply with GDPR, are supported. If you expect frequent or periodic deletion requests, please instead transmit anonymized data to Instana (e.g. hashed user IDs).

Are you anonymizing IPs?

Yes, IPs are anonymized. Specifically, the last octet of IPv4 addresses, and the last 80 bits of IPv6 addresses are set to zeros.