Set up the Agent

edit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Follow these steps to start reporting your Android application’s performance to Elastic APM:

Set up Gradle

edit

Requirements

edit
Requirement Minimum version

Android Gradle plugin

7.4.0

Android API level

24

For projects using minSdkVersion < 26

edit

Due to Android’s limited support for Java 8 features on devices with an API level < 26, or in other words, older than Android 8.0, you must add Java 8+ desugaring support to apps with a minSdkVersion less than 26. If you don’t, your app can crash when running on devices using Android OS versions older than 8.0. This is because the OpenTelemetry Java SDK, which this SDK is built upon, uses Java 8 features.

You can skip this step if your minSdkVersion is 26 or higher.

Add the Elastic Agent Gradle plugin

edit

To automatically instrument Supported Technologies, add the Elastic APM agent plugin to your application’s build.gradle file as shown below:

// Android app's build.gradle file
plugins {
    id "com.android.application"
    id "co.elastic.apm.android" version "0.19.0"
}

After adding the agent plugin, configure it. A minimal configuration sets the Elastic APM Server endpoint as shown below:

// Android app's build.gradle file
plugins {
    //...
    id "co.elastic.apm.android" version "[latest_version]" 
}

elasticApm {
    // Minimal configuration
    serverUrl = "https://your.elastic.server"

    // Optional
    serviceName = "your app name" 
    serviceVersion = "0.0.0" 
    apiKey = "your server api key" 
    secretToken = "your server auth token" 
}

You can find the latest version in the Gradle plugin portal.

Defaults to your android.defaultConfig.applicationId value.

Defaults to your android.defaultConfig.versionName value.

Defaults to null. More info on API Keys here.

Defaults to null.

When both secretToken and apiKey are provided, apiKey has priority and secretToken is ignored.

Set up your application

edit

After syncing your project with the Gradle changes above, the Elastic APM agent needs to be initialized within your Application class. This example shows the simplest way to configure the agent:

// Your Application class

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ElasticApmAgent.initialize(this); 
    }
}

Initialize the Elastic APM agent once.

(Optional) Manual set up

edit

If you can’t add the Elastic Agent Gradle plugin to your application as shown above, complete the following steps to set up the Elastic SDK manually.

Add the SDK dependency

edit

Add the Elastic APM agent SDK to your application’s build.gradle file as shown below:

// Android app's build.gradle file
dependencies {
    implementation "co.elastic.apm:android-sdk:0.19.0"
}

Configure your app’s info and connectivity parameters

edit
  • Set your app name, version, and environment name, as explained here.
  • Set your server connectivity parameters, as explained here.

Without the Gradle plugin, the Elastic SDK won’t be able to provide automatic instrumentations for its Supported technologies.

Compile and run

edit

All that’s left is to compile and run your application. That’s it!

What’s next?

edit

After initializing the agent (by using the gradle plugin), your application will automatically create traces for all OkHttp network requests (including those created by tools that make use of OkHttp, like Retrofit) and all Activity and Fragment starting methods.

Apart from the automatic instrumentation helped by the Gradle plugin, you’ll get automatic crash reports when an unexpected error occurs in your app, regardless of whether the Gradle plugin is available or not.

All of these events will contain a Session ID that links related events together—allowing you to make sense of and diagnose any issues that arise. Head to the APM app in Kibana to start exploring your data.

If you need to customize the Elastic APM agent to your project’s needs, see configuration. If you need to create your own custom transactions, see manual instrumentation.