Troubleshooting the EDOT Android SDK

Stack Serverless Observability EDOT Android

Use the information in this section to troubleshoot common problems. As a first step, make sure your stack is compatible with the supported technologies for EDOT Android and the OpenTelemetry SDK.

If you have an Elastic support contract, create a ticket in the Elastic Support portal. If you don't, post in the APM discuss forum or open a GitHub issue.

The SDK creates logs that allow you to see what it's working on and what might have failed at some point. You can find the logs in logcat, filtered by the tag ELASTIC_AGENT.

For more information about the SDK's internal logs, as well as how to configure them, refer to the internal logging policy configuration.

If after following the getting started guide and configuring your Elastic Stack endpoint parameters, you can't see your application's data in Kibana, you can follow the following tips to try and figure out what could be wrong.

The SDK prints debug logs, which can be seen in logcat, using the tag ELASTIC_AGENT, where you can have a look at your endpoint configuration parameters with a log that reads: "Initializing connectivity with config [your endpoint configuration]". Take a look at those and make sure that the provided configuration matches your Elastic Stack endpoint parameters.

You can take a look at your app's outgoing network requests via Android Studio's network inspector tool. This tool can show you the SDK's export requests, where you can see if they were successful or not, as well as the request body and the Elastic Stack response body for when you need more details of the whole process.

Apart from that, this tool also provides a way to export a file with the information of all of your app's HTTP requests, which you could share with our support team if needed.

Sometimes the request to the Elastic Stack endpoint won't show up in the network inspector. A common issue when this happens is that there is an SSL/TLS error that occurs when the SDK tries to contact your Elastic Stack endpoint. This is often the case when you work with an on-prem Elastic Stack that doesn't have trusted CAs, for which you'd need to add custom security configurations to your app to make the export work. Take a look at how to configure SSL/TLS for more information.

Note that the Elastic Agent does not handle SSL/TLS configs internally. Therefore, you should manage these types of configurations as part of your app’s network security configurations, as explained in Android’s official security guidelines. Below we show a set of common use cases and quick tips on what could be done on each one. However, each case might be different, so please refer to Android’s official docs on this topic if you need more details.

If your Elastic Stack is hosted in Elastic Cloud, you shouldn’t need to add any SSL/TLS config changes in your app. It should work out of the box.

If your Elastic Stack is hosted on-prem, then it depends on the type of CA your host uses to sign its certificates. If it’s a commonly trusted CA, you shouldn’t have to worry about changing your app’s SSL/TLS configuration as it all should work well out of the box. However, if your CAs are unknown/private or your server uses a self-signed certificate, then you would need to configure your app to trust custom CAs by following Android’s guide.

If you’re running a local server and need to connect to it without using http in order to run a quick test, then you could temporarily enable cleartext traffic within your AndroidManifest.xml file, inside the <application> tag. As shown below:

<application
    ...
    android:usesCleartextTraffic="true">
    ...
</application>

If enabling cleartext traffic isn’t a valid option for your debugging use case, you should refer to Android’s guide on configuring CAs for debugging.

For more information on how Android handles network security, please refer to the official Android docs.

Android devices with an API level below 26 (older than Android 8.0) have limited support for Java 8 features and types, which can cause your app to crash when using those types while running on those older-than-8.0 devices.

For example, if one of your app's dependencies uses the Base64 type (added in API level 26), and your app is installed on an Android device with OS version 7.0 (API level 24), a crash will happen when the code that uses said type is executed due to a "class not found" error.

To prevent these kinds of issues on devices using Android OS older than 8.0, you must add Java 8 desugaring support to your app. This requirement is inherited from the OpenTelemetry Java SDK, which this project is built upon, where several of the unsupported types for Android versions older than 8.0 are used.

For historic reasons, service has been the default way of referring to "an entity that produces telemetry". This term made its way into OpenTelemetry to a point where it was marked as one of the first "stable" resource names, meaning that it was no longer possible/feasible to make a change to another name that would better represent any kind of telemetry source. This has been debated several times within the community. A recent discussion attempts to explain the service description and what it should represent in an effort to reduce confusion. However, there doesn't seem to be a consensus.

Your Application instance is needed to initialize the agent. There are a couple of ways you can get yours.

The agent should get initialized as soon as your application is launched to make sure that it can start collecting telemetry from the very beginning.

An ideal place to do so is from within your own custom Application.onCreate method implementation, as shown in the following snippet:

package my.app

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            //...
            .build()
    }
}

1. this is your application.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:name="my.app.MyApp"
        ...
    </application>
</manifest>

You can get your application from an Activity by calling its getApplication() method.

From a Fragment instance, you can get the Activity that it is associated to by calling its requireActivity() method. After you get the Activity object, you can get your application from it as explained above.

The export endpoint is where your app's telemetry is sent. The endpoint is required to initialize the agent. The way to find the endpoint in your Elastic Stack depends on the type of deployment you use.

On a Serverless deployment, follow these steps:

1. Open Kibana and find Add data in the main menu. Alternatively, you can use the global search field and search for Observability Onboarding.
2. Select Application, OpenTelemetry.
3. Select the OpenTelemetry tab, followed by Managed OTLP Endpoint under Configure the OpenTelemetry SDK.

Your export endpoint URL is the value for the OTEL_EXPORTER_OTLP_ENDPOINT configuration setting.

For Elastic Cloud Hosted (ECH) and self-managed deployments, the export endpoint, also known as EDOT Collector, is not available out of the box at the moment. You can still create your own service by downloading and configuring an EDOT Collector.

API keys are the recommended way of authenticating the agent with your Elastic Stack. There's a couple of ways you can create one.

Follow this quick guide and leave all the settings with their default values.

Follow this guide to create an API Key with a set of privileges that are scoped for the APM Agent use case only.