Mobile App Monitoring

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 v4.x.x is compatible with:

  • Android Gradle Plugin 4.1.x
  • Gradle 6.5+

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.1.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()
        mavenCentral()
        maven {
            url "https://dl.bintray.com/instana/public-maven"
        }
    }
   dependencies {
      classpath "com.instana:android-agent-plugin:4.5.4"
    }
}

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()
        mavenCentral()
    }
}

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

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

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 use the Instana Android Plugin version appropriate for your React Native version:

  • React Native 0.63.3 or earlier: Please use Instana Android Plugin 1.5.3
  • React Native 0.63.4 or later: Please use Instana Android Plugin 4.5.3

Please follow these steps to enable automatic HTTP monitoring:

  1. In your /android/build.gradle file:
buildscript {
    dependencies {
        classpath "com.instana:android-agent-plugin:$INSTANA_ANDROID_PLUGIN_VERSION"
    }
}
  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"
}
Execution failed for task ':app:transformClassesWithDexBuilderForDevDebug'

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

  • Instana Android Plugin 4.5.3
  • Gradle 6.5: distributionUrl=https\://services.gradle.org/distributions/gradle-6.5-bin.zip in android/gradle/wrapper/gradle-wrapper.properties
  • Android Gradle Plugin 4.1.0: classpath("com.android.tools.build:gradle:4.1.0") in android/build.gradle

Advanced usage

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

Flutter

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

Please note that 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)

Adding the package to your app

The Instana agent Flutter package is available via pub.dev.

You can add it to your app the same way as usual:

  1. Open the pubspec.yaml file located inside the app folder, and add instana_agent: under dependencies.
  2. Install it From the terminal: Run flutter pub get Or

    • From Android Studio/IntelliJ: Click Packages get in the action ribbon at the top of pubspec.yaml.
    • From VS Code: Click Get Packages located in right side of the action ribbon at the top of pubspec.yaml.

Initialization

Import package in your dart file(s):

import 'package:instana_agent/instana_agent.dart';

Stop and restart the app, if necessary

Setup Instana once as soon as possible. For example, in initState()


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

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

Tracing View changes

At any point after initialing Instana agent:

import 'package:instana_agent/instana_agent.dart';

[...]

InstanaAgent.setView('Home');

Tracing Http requests

At any point after initialing Instana agent:

import 'package:instana_agent/instana_agent.dart';

[...]

InstanaAgent.startCapture(url: 'https://example.com/success', method: 'GET').then((marker) => marker
    ..responseStatusCode = 200
    ..responseSizeBody = 1000
    ..responseSizeBodyDecoded = 2400
    ..finish());

We recommend creating your own InstrumentedHttpClient extending http.BaseClient as shown in this snippet, for example:

class _InstrumentedHttpClient extends BaseClient {
   _InstrumentedHttpClient(this._inner);

   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);
         marker
            ..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("https://www.instana.com"));
      httpClient.send(request);
   }

   [...]
}

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. The default grouping depends on the selected beacon type. Grouping can be removed to inspect the individual beacon that match filters.

Details