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 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.

Installation

iOS

To install the iOS agent, use Swift Package Manager (through 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 commands:

    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 plug-in and an SDK library. Apply the plug-in to your application module and add the SDK as a dependency.

Android Gradle plug-in and Gradle version

Instana Android Agent v4.x.x is compatible with,

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

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

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

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

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

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

You can 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 plug-in

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 you apply the com.android.application plug-in:

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 needed 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 READ_PHONE_STATE permission (optional)

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

To enable the reporting of the cellular network type, your app needs to request the READ_PHONE_STATE permission. 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 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() {
        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, and 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 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 should contain at least one Swift file (it can be empty).

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

Android

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

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"
       }
    }
    
  2. In your /android/app/build.gradle file:

    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), 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, check that you are using,

Advanced usage

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

Flutter

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

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

Initialization

Import package in your dart files:

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

@override
  void initState() {
    super.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 Instana agent:

import 'package:instana_agent/instana_agent.dart';

[...]

InstanaAgent.setView('Home');

Tracing Http requests

At any point after initializing 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;

   @override
   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, and 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 that relates to it.

Details

Analytics

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.

Details

Geographic Data

This product includes GeoLite2 data that is created by MaxMind, available from https://www.maxmind.com.