How does the agent work?edit
The agent auto-instruments known frameworks and libraries and records interesting events, like HTTP requests and database queries. To do this, it leverages the capability of the JVM to instrument the bytecode of classes. This means that for the supported technologies, there are no code changes required.
The agent automatically safely injects small pieces of code before and after interesting events to measure their duration and metadata (like the DB statement) as well as HTTP related information (like the URL, parameters, and headers).
For example, if the agent detects that a class extending
javax.servlet.HttpServlet is loaded,
it injects monitoring code before and after the servlet invocation.
These events, called Transactions and 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.
Is the agent doing bytecode instrumentation?edit
How safe is bytecode instrumentation?edit
Elastic APM is using 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 agents attached to your application at the same time.
Do I need to re-compile my application?edit
What is the recommended sample rate?edit
There is no one-size-fits-all answer to an ideal sample rate. Sampling comes down to your preferences and your application. The more you want to sample, the more network bandwidth and disk space you’ll need.
It’s important to note that the latency of an application won’t be affected much by the agent (in the order of single-digit microseconds), even if you sample at 100%. However, the background reporter thread has some work to do for serializing and gzipping events. If your application is not CPU bound, this shouldn’t matter much. Note that if the APM Server can’t handle all the events, the agent will drop data to not crash your application. It will then also not serialize and gzip the events.
Sample rate can be changed by altering the
transaction_sample_rate (performance) configuration.
Is there recommended RAM when using APM?edit
No. The Java agent is designed to be very light on memory. It has a static overhead of only a couple MBs.
What if the agent doesn’t support the technologies I’m using?edit
You can use the public API to create custom spans and transactions, the plugin API to create custom instrumentation, participate in the survey to vote for prioritizing adding support for the technologies you are using, or get involved in the agent development and contribute to the auto-instrumentation capabilities of the agent.