Frequently asked questionsedit

How does the agent work?edit

The agent auto-instruments known frameworks and libraries and records interesting events, like HTTP requests. To do this, it leverages the capability of the JVM to instrument the bytecode of classes. This means that no code changes are required for supported technologies.

The agent automatically and safely injects small pieces of code before and after interesting events to measure their duration and metadata, like HTTP-related information, including the URL, parameters, and headers.

These events, called Spans, are sent to the APM Server which converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application.

The instrumentation happens at compile time, using the Android Gradle plugin Instrumentation API.

Is the agent doing bytecode instrumentation?edit

Yes

How safe is bytecode instrumentation?edit

Elastic APM uses the popular bytecode instrumentation library Byte Buddy, which takes care of the heavy lifting of dealing with actual bytecode and lets us write the instrumentation in pure Java.

Byte Buddy is widely used in popular Open Source projects, for example, Hibernate, Jackson, Mockito and is also commonly used by APM vendors. It is created by a Java Champion, awarded with the Dukes Choice award and currently downloaded over 75 million times a year.

Unlike other bytecode instrumentation libraries, Byte Buddy is designed so that it is impossible to corrupt the bytecode of instrumented classes. It also respects other transformations applied to your application at the same time.

How can I configure SSL/TLS?edit

Please note that the Elastic Agent does not handle SSL/TLS configs internally, therefore, the recommended way to manage these types of configurations is by doing so 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 in case you need more details.

Connecting to Elastic Cloudedit

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.

Connecting to an on-prem serveredit

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, then 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 on it.

Debugging purposesedit

If you’re running a local server and need to connect to it without using https 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 on it.

What if the agent doesn’t support the technologies I’m using?edit

The agent is built on top of OpenTelemetry You can use its public API to create custom spans and transactions.