Mobile App Monitoring

Open Beta

Our mobile app monitoring feature is currently in technical beta. Please share your feedback with us.

Concepts

End-User Monitoring (EUM) or Real-User Monitoring (RUM), is a vital tool to understand digital user experience.

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

Installation

iOS

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

Swift Package Manager

  1. Open Xcode.
  2. Select File -> Swift Packages -> Add Package Dependency -> Your Xcode project.
  3. Enter the https://github.com/instana/iOSAgent repository.

CocoaPods

  1. Within your Podfile specification, add the following:

    pod 'InstanaAgent'

  2. To download the dependencies, run pod install.

Setup

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

Android

The Android agent is composed by a Gradle plugin and a SDK library. Please apply the plugin to your application module and add the SDK as a dependency.

Android Gradle Plugin and Gradle version

Instana Android Agent v3.x.x is compatible with:

  • Android Gradle Plugin 4.0.x
  • Gradle 6.1.1+

Instana Android Agent v2.x.x is compatible with:

  • Android Gradle Plugin 3.6.x
  • Gradle 6.x

Instana Android Agent v1.x.x is compatible with:

  • Android Gradle Plugin 3.5.x
  • Gradle 5.4.x

Warning: failing to use a compatible version of Instana Android Agent will prevent your project from synchronizing Gradle

You can find find your Android Gradle Plugin version in your project-level build.gradle file:

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:4.0.1'
    }
}

You can find find your Gradle version in your Gradle Wrapper configuration file (usually gradle/wrapper/gradle-wrapper.properties):

distributionUrl=https\://services.gradle.org/distributions/gradle-6.1.1-all.zip

Instana Android Plugin

In your project-level build.gradle file:

buildscript {
   repositories {
        google()
        jcenter()
        maven {
            url "https://dl.bintray.com/instana/public-maven"
        }
    }
   dependencies {
      classpath "com.instana:android-agent-plugin:3.4.0"
    }
}

In your module (app-level) Gradle file (usually app/build.gradle), after applying the com.android.application plugin:

apply plugin: 'com.android.application'
apply plugin: 'com.instana.android-agent-plugin'

Instana Android SDK

In your project-level build.gradle file:

allprojects {
    repositories {
        google()
        jcenter()
    }
}

In your module (app-level) Gradle file (usually app/build.gradle):

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

Java 1.8 compatibility

Note: this step is not required if your minSdkVersion is 24 or higher

In your module (app-level) Gradle file (usually app/build.gradle):

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

Request READPHONESTATE permission (optional)

When a user accesses the Internet through a cellular network, Instana Agent has the ability to report the specific type of cellular network.

In order to enable the reporting of the cellular network type, your app needs to request the READ_PHONE_STATE permission. Please refer to the Request App Permissions section in the official Android documentation.

If your app doesn't request the permission or if the user declines it, Instana Agent will simply not report the cellular network type.

Basic initialization

In your class extending Application, replace YOUR_REPORTING_URL and YOUR_APP_KEY with the configuration values you'll find in your Instana Dashboard:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = "YOUR_APP_KEY",
                reportingURL = "YOUR_REPORTING_URL"
            )
        )
    }
}

Advanced usage

For a complete list of initialization options, view tracking, manual request-tracking, etc please see the Android agent API.

React Native

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

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'll find in your Instana Dashboard:

export default class App extends Component {
  componentDidMount() {
    Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL);
  }
}

Recommendation

We recommend adding http://localhost:8081 to the ignored URLs list to prevent the Agent from tracing communication with the Metro bundler:

Instana.setIgnoreURLsByRegex(["http:\/\/localhost:8081.*"]);

iOS

Your project needs to contains at least one Swift file (it can be empty).

If you don't have any, please open your Xcode Project in <YourReactNativeProject>/ios and add an empty Swift file. Please also let Xcode create the Bridging Header for you.

Android

Please follow these steps to enable automatic HTTP monitoring:

  1. In your /android/build.gradle file:
buildscript {
    dependencies {
        classpath 'com.instana:android-agent-plugin:1.4.0'
    }
}
  1. In your /android/app/build.gradle file (at the top):
apply plugin: 'com.android.application'
apply plugin: 'com.instana.android-agent-plugin'
Known issues
fetch(url)

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

If you encounter this issue, and until the upstream issue is solved (here and here), please apply the following workaround.

In your Android module-level gradle file (usually app/gradle.build):

dependencies {
    implementation "com.squareup.okhttp3:okhttp:4.3.1"
    implementation "com.squareup.okhttp3:okhttp-urlconnection:4.3.1"
}

Advanced usage

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

Dashboards

Summary

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, as well as error rates and latency breakdown.

HTTP Request Details

Views

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 of the metrics relating to it.

Details

Analytics

Similar to our analytics capabilities for traces and calls, the analytics view for mobile app monitoring data can be used to answer very 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, i.e. 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. Filters are connected with AND logic operator so a beacon needs to match all the filters. The default grouping depends on the selected beacon type. Grouping can be removed to inspect the individual beacon that match filters.

Details