Monitoring mobile applications

Instana supports mobile app monitoring by analyzing actual URL request times, which provides detailed insights into the app experience of users, and deep visibility into application call paths. The Instana app monitoring solution works that uses an iOS/Android agent, which is installed as a dependency on mobile apps.

End-User Monitoring (EUM) or Real-User Monitoring (RUM), is a vital tool for understanding the digital user experience with mobile apps.



To install the iOS agent, use Swift Package Manager (through Xcode) or CocoaPods.


  • iOS 11 or later
  • swift 5.1 or later

Swift Package Manager

  1. Open Xcode.
  2. Select File -> Swift Packages -> Add Package Dependency -> Your Xcode project.
  3. Enter the repository.


  1. Within your Podfile specification, add the commands:

    pod 'InstanaAgent'
  2. To download the dependencies, run pod install.


For more information about the setup process, see the iOS agent API.


The Android agent is composed by a Gradle plug-in and an SDK library. Apply the plug-in to your application module and add the SDK as a dependency.


  • Android 4.1+ (API level 16+)
  • Java 8+
  • Gradle 7.3.3+
  • AndroidX
  • targetSdk 33+

Note: To use a Gradle version lower than 7.3.3 in your project, use an android-agent version lower than 6.0.0.

Instana Android plug-in

In your project-level build.gradle file, add the following code:

buildscript {
   repositories {
   dependencies {
      classpath "com.instana:android-agent-plugin:6.0.0"

In your module (app-level) Gradle file (usually app/build.gradle) after you apply the plug-in, add the following code:

apply plugin: ''
apply plugin: ''

Instana Android SDK

In your project-level build.gradle file, add the following code:

allprojects {
    repositories {

In your module (app-level) Gradle file (usually app/build.gradle), add the following code:

dependencies {
    implementation 'com.instana:android-agent-runtime:6.0.0'

Java 1.8 compatibility

Note: Complete this step if your minSdkVersion is lower than 24.

In your module (app-level) Gradle file (usually app/build.gradle), add the following code:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8

Request READ_PHONE_STATE permission (optional)

When a user accesses the internet through a cellular network, the Instana agent can report the specific type of cellular network.

To enable reporting of the cellular network type, your app needs to request the READ_PHONE_STATE permission. For more information about requesting permissions, see the Request App Permissions section in the official Android documentation.

If your app doesn't request the permission or if the user declines the permission, the Instana agent does not report the cellular network type.

Basic initialization

In your class, which extends Application, replace YOUR_REPORTING_URL and YOUR_APP_KEY with the configuration values you find in your Instana Dashboard:

class MyApplication : Application() {
    override fun onCreate() {
                key = "YOUR_APP_KEY",
                reportingURL = "YOUR_REPORTING_URL"

Advanced usage

For a complete list of initialization options, view tracking, and other options, see the Android agent API.

React Native

The React Native agent brings support for both Android and iOS platforms.


See Instana React Native Agent.

Add the dependency

Run the following command in your project's root:

npm install @instana/react-native-agent --save

Basic initialization

In your class App.js file, replace YOUR_INSTANA_APP_KEY and YOUR_INSTANA_REPORTING_URL with the configuration values you find in your Instana Dashboard:

export default class App extends Component {
  componentDidMount() {


To prevent the Instana agent tracing communication with the Metro bundler, add http://localhost:8081 to the ignored URLs list:



Your project should contain at least one Swift file (it can be empty).

If you don't have any Swift files, open your Xcode Project in <YourReactNativeProject>/ios then add an empty Swift file. Let Xcode create the Bridging Header for you.


Use the Instana Android plug-in version appropriate for your React Native version:

  • React Native 0.63.3 or earlier: Use Instana Android plug-in 1.5.3
  • React Native 0.63.4 or later: Use Instana Android plug-in 5.2.2

Follow these steps to enable automatic HTTP monitoring:

  1. In your /android/build.gradle file, add the following code:

    buildscript {
        dependencies {
            classpath "com.instana:android-agent-plugin:$INSTANA_ANDROID_PLUGIN_VERSION"
  2. In your /android/app/build.gradle file, add the following code:

    apply plugin: ''
    apply plugin: ''
Known issues

If your app uses fetch to complete network requests, you might find your app crashes on runtime whenever fetch is used: No virtual method toString(Z)Ljava/lang/String;

This problem should be fixed by the React Native issues (27250 and 28425). If you encounter this problem, you can apply the following workaround.

In your Android module-level Gradle file (usually app/, add the following code:

dependencies {
    implementation "com.squareup.okhttp3:okhttp:4.3.1"
    implementation "com.squareup.okhttp3:okhttp-urlconnection:4.3.1"
Execution failed for task ':app:transformClassesWithDexBuilderForDevDebug'

If you upgraded to React Native 0.63.4 from a previous version, check that you are using,

  • Instana Android plug-in 4.5.3
  • Gradle 6.5: distributionUrl=https\:// in android/gradle/wrapper/
  • Android Gradle plug-in 5.2.2: classpath("") in android/build.gradle

Advanced usage

For a complete list of initialization options, view tracking, and other options, see the React Native agent API.


The Flutter agent brings support for both Android and iOS platforms.

Note: The Flutter agent does not provide automatic HTTP tracing. HTTP tracing must be manually set up by the developer (an example is provided in this documentation).


  • Flutter version 1.20.0 or later
  • Dart version between 2.12.0 and 3.0.0

Adding the package to your app

The Instana agent Flutter package is available from

To add the package to your app, complete the following steps:

  1. Open the pubspec.yaml file located inside the app folder, and then add instana_agent: under dependencies.

  2. Install the package, by using one of the following methods:

    • From the console: Run flutter pub get
    • From Android Studio or IntelliJ: Click Packages get in the action ribbon of pubspec.yaml
    • From VS Code: Click Get Packages in the action ribbon ofpubspec.yaml


Import the package in your dart files:

import 'package:instana_agent/instana_agent.dart';

Stop and restart the app, if necessary.

Set up Instana as soon as possible. For example, in initState(), add the following code:

  void initState() {
    InstanaAgent.setup(key: 'YOUR-INSTANA-KEY', reportingUrl: 'YOUR-REPORTING_URL');

If you intend to build for iOS, set up a minimum platform version in ${appFolder}/ios/Podspec with a minimum value of 11.0.

Tracing View changes

At any point after initializing the Instana agent, add InstanaAgent.setView('Home');:

import 'package:instana_agent/instana_agent.dart';



Tracing HTTP requests

At any point after initializing Instana agent, start the capture of HTTP requests:

import 'package:instana_agent/instana_agent.dart';


InstanaAgent.startCapture(url: '', method: 'GET').then((marker) => marker
    ..responseStatusCode = 200
    ..responseSizeBody = 1000
    ..responseSizeBodyDecoded = 2400

Create your own InstrumentedHttpClient extending http.BaseClient as shown in the following example:

class _InstrumentedHttpClient extends BaseClient {

   final Client _inner;

   Future<StreamedResponse> send(BaseRequest request) async {
      final Marker marker = await InstanaAgent.startCapture(url: request.url.toString(), method: request.method);

      StreamedResponse response;
      try {
         response = await _inner.send(request);
            ..responseStatusCode = response.statusCode
            ..responseSizeBody = response.contentLength
            ..backendTracingID = BackendTracingIDParser.fromHeadersMap(response.headers);
      } finally {
         await marker.finish();

      return response;

class _MyAppState extends State<MyApp> {


   Future<void> httpRequest() async {
      final _InstrumentedHttpClient httpClient = _InstrumentedHttpClient(Client());
      final Request request = Request("GET", Uri.parse(""));




The main dashboard summarizes all the important data at a glance.

Dashboard Overview

HTTP requests

Learn which of your HTTP requests are slow or problematic. Selecting a specific origin provides an insight into throughput and latency, and error rates and latency breakdown.

HTTP Request Details


Often it's important to isolate specific views and analyze their performance, which is also a great way to find the view with the most traffic. Select a specific view to display all the metrics for the view.


Smart Alerts

View a list of all your configured Smart Alerts. Click an alert to view its configuration, modify it, or view its revision history. If required, you can also disable or remove the alert.

For more information about how to add an alert, see Smart Alerts.


Similar to analytics capabilities for traces and calls, the analytics view for mobile app monitoring data can be used to answer specific questions that aren't covered by any preconfigured dashboards. A single piece of app monitoring data is called a beacon. A few beacon types exist, that is, session start and HTTP requests. For convenience purposes, each beacon type has its main navigation item within the analytics view.

Beacon data can be used to filter and group. The default grouping depends on the selected beacon type. Grouping can be removed to inspect the individual beacon that match filters.


Geographic data

Instana maps user IP addresses to geographic details based on GeoLite2 database, which is provided by MaxMind. The IP addresses are collected by using the reverse proxy server. For self-hosted installation, configure the URL of the user monitoring endpoint as the reporting URL for the agent. Otherwise, the IP addresses are not collected, and the related geographic details information is not available.