Monitoring mobile applications

Configuring the Instana iOS agent

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

• iOS 11 or later
• Swift 5.1 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.6.8'
   

2. Download the dependencies, run pod install.

In the command, replace 1.6.8 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.

Adding the Instana Android plug-in

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

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

Version 6.0.13 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.0.13"
    }
   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'

Adding Instana Android SDK

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.

Adding the dependency

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.

Considerations for using Read Native agent

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

Android

Every version of the Instana React Native agent is compatible with a specific version of the Instana Android plug-in. Version 6.0.13 is used as an example in the following snippet. Use the latest Instana Android plug-in version that is compatible with your React Native version. To find the latest version, see Supported React Native versions

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.0.12"
       }
       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'
   

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

Adding the package to your app

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

Initializing the Instana agent

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.

Tracing View changes

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

import 'package:instana_agent/instana_agent.dart';

[...]

InstanaAgent.setView('Home');

Tracing HTTP requests

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

   [...]
}