Monitoring mobile applications

Make sure that the following prerequisites are met before you install the iOS agent:

• iOS 12 or later
• Swift 5.4 or later

To add Swift Package Manager, complete the following steps:

1. Open Xcode.
2. Open your Xcode project.
3. Select menu File > Add Package Dependencies....
4. In the window that pops up, enter the repository https://github.com/instana/iOSAgent in the Search or Enter Package URL field. Then, select iosagent from the search result, and click Add Package .

To add CocoaPods, complete the following steps:

1. Within your Podfile specification, add the commands:

   pod 'InstanaAgent', '~> 1.8.9'
   

2. Download the dependencies, run pod install.

In the command, replace 1.8.9 with the latest iOS agent version that is listed in https://cocoapods.org/pods/InstanaAgent.

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

To add the Instana Android plug-in, complete the following steps:

1. In your project-level build.gradle file, add the following code:
   Note: Version 6.1.2 is used as an example in the following snippet. To find the latest Instana agent version, refer to https://mvnrepository.com/artifact/com.instana/android-agent-runtime.

   buildscript {
      ext {
           instanaAgentVersion = "6.1.2"
       }
      repositories {
           google()
           mavenCentral()
       }
      dependencies {
         classpath "com.instana:android-agent-plugin:$instanaAgentVersion"
       }
   }
   

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

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

To add the Instana Android SDK, complete the following steps:

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

   allprojects {
       repositories {
           google()
           mavenCentral()
       }
   }
   

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

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

3. If your minSdkVersion is earlier 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
       }
   }
   

4. Optional: Request READ_PHONE_STATE permission. 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. 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"
            )
        )
    }
}

Basic initialization is completed in this step. For a complete list of initialization options, view tracking, and other options, see the Android agent API.

To configure the Instana React Native agent, complete the following steps:

1. Add dependence, run the following command in your project's root:

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

2. 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, null);
  }
}

Basic initialization is completed in this step. For a complete list of initialization options, view tracking, and other options, see the React Native agent API.

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

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

• To support iOS apps, your project must 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. Xcode creates the Bridging Header for you.

• To support Android apps, use the Instana Android plug-in version appropriate for your React Native version:

  • For React Native 0.63.3 or earlier, use Instana Android plug-in 1.5.3
  • For React Native 0.63.4 or later, use Instana Android plug-in 5.2.2

Enable automatic HTTP monitoring:

Your project must contain at least one Swift file. The Swift file can be empty.

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

Follow these steps to enable automatic HTTP monitoring:

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

   buildscript {
       ext {
           INSTANA_ANDROID_PLUGIN_VERSION = "6.1.2"
       }
       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: 'com.android.application'
   apply plugin: 'com.instana.android-agent-plugin'
   

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

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: in 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:

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

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

After the Instana agent is initialized, add InstanaAgent.setView('Home');:

import 'package:instana_agent/instana_agent.dart';

[...]

InstanaAgent.setView('Home');

After the Instana agent is initialized, start capturing HTTP requests:

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

Create your own InstrumentedHttpClient extending http.BaseClient as shown in the following 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.ibm.com/products/instana"));
      httpClient.send(request);
   }

   [...]
}

A session start event occurs when a user launches the application. The Session start tile displays the total number of the session start beacons that are sent by the Instana agent within your selected time range.

The Unique users tile shows the total number of users with a unique user ID. If a unique user ID is not set, the userSessionIdentifier (usi) is considered instead. In this case, all subsequent sessions have the same usi until the application is uninstalled or the storage is cleared.

The usi field was introduced in Android agent version 6.0.6 and iOS agent version 1.6.5. If you use an older agent version, the usi field would be empty and each session accounts for a new user.

View transition beacons are sent when a user switches between different views in the application. For example, when you switch from a Home screen to a Products screen, the View transitions tile displays the total number of View transition beacons in your selected time range.

The Crash affected session rate tile shows the percentage of sessions in which users experienced crashes based within the selected time range. You can calculate the crash-affected sessions by dividing the number of sessions in which crashes occurred by the total number of unique sessions, as shown in the following formula:

Crash affected session rate = (Number of sessions with crashes / Total number of unique sessions) * 100

The Crash affected user rate tile shows the percentage of unique users who experienced crashes during their sessions within the selected time range. You can calculate the crash-affected users rate by dividing the number of users who experienced session crashes by the total number of unique users, as shown in the following formula:

Crash affected user rate = (Number of users with crashes / Total number of unique users) * 100

The Crashes chart displays the number of mobile app crashes over a selected time. The x-axis represents the time range, while the y-axis indicates the total number of crashes during that interval. This helps identify trends, peak times, or specific time frames with increased crash frequency. To view more details about the crash, click the crash occurrence on the chart.

The number of crashes displayed changes based on the selected time. For example, if 'Last Minute' is selected, each bar represents crashes per second, with the x-axis showing individual seconds. When 'Last Hour' is selected, each bar represents the number of crashes per minute, and the x-axis displays the time in minutes.

The Top Crash Groups card shows the most frequently occurring crash groups by default. A crash group consists of the error type and the error message of the crash. To view the most frequent crash groups based on the number of affected users, switch the tab from Occurrences to Affected Users in the card.

The Top views card displays the customer's occurrences of the top view transitions.

The Top HTTP request origins card displays the top endpoints to which calls are made. If you switch to the Errors tab, you can see the percentage of calls that had errors.