Supported technologies
editSupported technologies
editThe Elastic APM Java Agent automatically instruments various APIs, frameworks and application servers. This section lists all supported technologies.
If your favorite technology is not supported yet, you can vote for it by participating in our survey. We will use the results to add support for the most requested technologies.
Other options are to add a dependency to the agent’s public API in order to programmatically create custom transactions and spans, or to create your own plugin that will instrument the technology you want instrumented.
If you want to extend the auto-instrumentation capabilities of the agent, the contributing guide should get you started.
If, for example, the HTTP client library of your choice is not listed, it means that there won’t be spans for those outgoing HTTP requests. If the web framework you are using is not supported, the agent does not capture transactions.
Java versions
editAs of version 1.33.0, Java 7 support is deprecated and will be removed in a future release
Vendor | Supported versions | Notes |
---|---|---|
Oracle JDK |
7u60+*, 8u40+, 9, 10, 11, 17, 21 |
|
OpenJDK |
7u60+*, 8u40+, 9, 10, 11, 17, 21 |
|
IBM J9 VM |
8 service refresh 5+ (build 2.9 or 8.0.5.0) |
Sampling profiler is not supported |
HP-UX JVM |
7.0.10+*, 8.0.02+ |
|
SAP JVM |
8.1.065+ |
* Java 7 support is deprecated and will be removed in a future release
Early Java 8 and Java 7
Early Java 8 versions before update 40 are not supported because they have several bugs that might result in JVM crashes when a java agent is active, thus agent will not start on those versions. Similarly, Java 7 versions before update 60 are not supported as they are buggy in regard to invokedynamic.
Here is an example of the message displayed when this happens.
Failed to start agent - JVM version not supported: 1.8.0_31 Java HotSpot(TM) 64-Bit Server VM 25.31-b07. To override Java version verification, set the 'elastic.apm.disable_bootstrap_checks' System property, or the `ELASTIC_APM_DISABLE_BOOTSTRAP_CHECKS` environment variable, to 'true'.
As this message states, you can disable this check if required by adding -Delastic.apm.disable_bootstrap_checks=true
to
the JVM arguments, or setting ELASTIC_APM_DISABLE_BOOTSTRAP_CHECKS=true
for the JVM environment variables.
Web Frameworks
editFramework | Supported versions | Description | Since |
---|---|---|---|
Servlet API |
3+ |
A transaction will be created for all incoming HTTP requests to your Servlet API-based application.
Starting in version 1.18.0, additional spans are created if the servlet dispatches execution to another servlet through the |
1.0.0, 4.0+ ( |
Spring Web MVC |
4.x, 5.x, 6.x |
If you are using Spring MVC (for example with Spring Boot),
the transactions are named based on your controllers ( |
1.0.0, 6.x since 1.38.0 |
Spring Webflux |
5.2.3+ |
Creates transactions for incoming HTTP requests, supports annotated and functional endpoints. |
1.24.0 (experimental), 1.34.0 (GA), 6.1+ since 1.45.0 |
JavaServer Faces |
2.2.x, 2.3.x, 3.0.x |
If you are using JSF, transactions are named based on the requested Facelets and spans are captured for visibility into execution and rendering |
1.0.0, |
Spring Boot |
1.5+, 2.x, 3.x |
Supports embedded Tomcat, Jetty and Undertow |
1.0.0, 3.x since 1.38.0 |
JAX-RS |
2.x, 3.x |
The transactions are named based on your resources ( Note: JAX-RS is only supported when running on a supported Application Server/Servlet Container. |
1.0.0, |
JAX-WS |
The transactions are named based on your Note: JAX-WS is only supported when running on a supported Application Server/Servlet Container and when using the HTTP binding. |
1.4.0, |
|
Grails |
3+ |
1.17.0 |
|
Apache Struts |
2.x |
The transactions are named based on your action ( |
1.24.0 |
Vert.x Web |
3.6+ |
Captures incoming HTTP requests as transactions |
1.24.0 (experimental) |
Sparkjava (not Apache Spark) |
2.x |
The transactions are named based on your route ( |
1.25.0 |
com.sun.net.httpserver.HttpServer |
1.7+ |
Captures incoming HTTP requests as transactions |
1.25.0 |
Javalin |
3.13.8+ |
1.25.0 |
|
Java API for WebSocket |
1.0 |
Captures methods annotated with |
1.29.0 |
Application Servers/Servlet Containers
editThe Elastic APM Java agent has generic support for the Servlet API 3+. However, some servers require special handling. The servers listed here are tested by an integration test suite to make sure Elastic APM is compatible with them. Other Servlet 3+ compliant servers will most likely work as well.
Server | Supported versions |
---|---|
7.x, 8.5.x, 9.x, 10.x |
|
8+ |
|
6.4, 7.x |
|
Jetty (only the |
9.2, 9.3, 9.4 |
8.5.5, 18.0.x |
|
1.4 |
|
4.x, 5.x |
|
12.2 |
Data Stores
editDatabase | Supported versions | Description | Since |
---|---|---|---|
JDBC |
4.1+ |
The agent automatically creates DB spans for all your JDBC queries. This includes JDBC queries executed by O/R mappers like Hibernate. Note: Make sure that your JDBC driver is at least compiled for Java 1.4. Drivers compiled with a lower version are not supported. IBM DB2 db2jcc drivers are also not supported. Please update to db2jcc4. |
1.0.0 |
Elasticsearch Java REST and API clients |
5.0.2+ |
The agent automatically creates Elasticsearch spans for queries done through the official REST client. |
1.0.0, async since 1.5.0, API Client since 1.32.0 |
Hibernate Search |
5.x (on by default), 6.x (off by default) |
The agent automatically creates Hibernate Search spans for queries done through the Hibernate Search API. Note: this feature is marked as experimental for version 6.x, which means it is off by default. In order to enable,
set the |
1.9.0 |
Redis Jedis |
1.4.0-5.x |
The agent creates spans for interactions with the Jedis client. |
1.10.0, 4+ since 1.31.0 |
Redis Lettuce |
3.4+ |
The agent creates spans for interactions with the Lettuce client. |
1.13.0 |
Redis Redisson |
2.1.5+ |
The agent creates spans for interactions with the Redisson client. |
1.15.0 |
MongoDB driver |
3.x |
The agent creates spans for interactions with the MongoDB driver. At the moment, only the synchronous driver (mongo-java-driver) is supported. The asynchronous and reactive drivers are currently not supported. The name of the span is |
1.12.0 |
MongoDB Sync Driver |
4.x |
The agent creates spans for interactions with the MongoDB 4.x sync driver.
This provides support for |
1.34.0 |
Cassandra |
2.x+ |
The agent creates spans for interactions with the Cassandra Datastax drivers.
This provides support for |
1.23.0 |
AWS DynamoDB |
1.x, 2.x |
The agent creates spans for interactions with the AWS DynamoDb service through the AWS Java SDK. |
1.31.0, 2.21+ since 1.44.0 |
AWS S3 |
1.x, 2.x |
The agent creates spans for interactions with the AWS S3 service through the AWS Java SDK. |
1.31.0, 2.21+ since 1.44.0 |
Networking frameworks
editDistributed tracing will only work if you are using one of the supported networking frameworks.
For the supported HTTP libraries, the agent automatically creates spans for outgoing HTTP requests and propagates tracing headers.
The spans are named after the schema <method> <host>
, for example GET elastic.co
.
Framework | Supported versions | Note | Since |
---|---|---|---|
Apache HttpClient |
4.3+ |
0.7.0 (4.3+) 1.8.0 (4.0+) 1.45.0 (5.0+) |
|
Apache HttpClient (Legacy) |
3.0+ |
Requires setting |
1.35.0 |
Apache HttpAsyncClient |
4.0+ |
1.6.0 |
|
Spring RestTemplate |
3.1.1+ |
0.7.0 |
|
OkHttp |
2, 3, 4 (4.4+ since 1.22.0) |
1.4.0 (synchronous calls via |
|
HttpUrlConnection |
1.4.0 |
||
JAX-WS client |
JAX-WS clients created via |
1.4.0 |
|
AsyncHttpClient |
2.x |
1.7.0 |
|
Apache Dubbo |
2.x, except for 2.7.0, 2.7.1, 2.7.2 and versions older than 2.5.0 |
1.17.0 |
|
JDK 11 HttpClient |
1.18.0 |
||
Vert.x WebClient |
3.6+ |
1.25.0 |
|
Spring Webclient |
5.2.3+ |
1.33.0 (experimental), 1.34.0 (GA) |
|
Finagle Http Client |
22+ |
1.35.0 |
|
LdapClient |
1.36.0 |
||
Spring RestClient |
6.1.0+ |
1.45.0 |
Asynchronous frameworks
editWhen a Span is created in a different Thread than its parent, the trace context has to be propagated onto this thread.
This section lists all supported asynchronous frameworks.
Framework | Supported versions | Description | Since |
---|---|---|---|
|
The agent propagates the context for |
1.4.0 |
|
|
The agent propagates the context for |
1.17.0 |
|
|
The agent propagates the context for |
1.17.0 |
|
Scala Future |
2.13.x |
The agent propagates the context when using the |
1.18.0 |
Reactor |
3.2.x+ |
The agent propagates the context for |
1.24.0 (experimental), 1.34.0 (GA) |
Messaging frameworks
editWhen using a messaging framework, sender context is propagated so that receiver events are correlated to the same trace.
Framework | Supported versions | Description | Since |
---|---|---|---|
JMS |
1.1, 2.0 |
The agent captures JMS sends and receives as spans/transactions |
|
Kafka |
<0.11.0 - without distributed tracing; 0.11.0+ - full support |
The agent captures Kafka record sends and polls. Kafka streams are not traced. |
1.13.0 |
RabbitMQ |
3.x - 5.x |
The agent captures RabbitMQ Message sends, consumption and polling |
1.20.0 |
AWS SQS |
1.x, 2.x |
The agent captures SQS Message sends and polling as well as SQS message sends and consumption through JMS. |
1.34.0, 2.21+ since 1.44.0 |
Distributed Tracing
editThe Java agent instrumentation for messaging system clients includes both senders and receivers.
When an instrumented client sends a message within a traced transaction, a send
span is created. In addition, if the messaging system
supports message/record headers/annotations, the agent would add the tracecontext
headers to enable distributed tracing.
On the receiver side, instrumented clients will attempt to create the proper distributed trace linkage in one of several ways, depending on how messages are received:
-
Passive message handling: when the message handling logic is applied by implementing a passive message listener API (like
javax.jms.MessageListener#onMessage
for example), creating the receiver transaction is mostly straightforward as the instrumented API method invocation encapsulates message handling. Still, there are two use cases to consider:-
Single message handling: when the message listener API accepts a single message, the agent would create a
messaging
typed transaction per each received message, as a child transaction of thesend
span that corresponds the received message and with the same trace ID -
Batch message handling: when the message listener API accepts a batch of messages (like
org.springframework.amqp.core.MessageListener.onMessageBatch
for example), the agent will create a single root transaction (i.e. different trace ID from any of thesend
spans) by default to encapsulate the entire batch handling. The batch processing transaction would be ofmessaging
type, containing links* to allsend
spans that correspond the messages in the batch. This can be changed through the (non-documented)message_batch_strategy
config option, which accepts eitherBATCH_HANDLING
(default) orSINGLE_HANDLING
to enable the creation of a single child transaction per message.
-
Single message handling: when the message listener API accepts a single message, the agent would create a
-
Active message polling: in some cases, message are consumed from the broker through active polling. Whenever the polling action occurs while there is already an active span, the agent will create a
poll
span and add span links* to it for each message returned by the poll action that containstracecontext
headers. Since such polling APIs don’t provide any indication as to when message handling actually occurs, the agent needs to apply some heuristics in order to trace message handling. There are two use cases to consider in this type of message receiving as well:-
Polling returns a single message: in such cases, the agent may apply assumptions with regard to the threads that execute the message
handling logic in order to determine when handling starts and ends. Based on that, it would create a transaction per consumed message. If
the consumed message contains the
tracecontext
headers, thereceive
transaction will be a child of the correspondingsend
span. -
Polling returns a message batch: typically, in such cases the agent will wrap the message collection and rely on the actual
iteration to create a transaction per message as the child of the corresponding
send
span and as part of the same trace. If iteration occurs while there is already an active span, then the agent will add a link* for each messagesend
span to the active (parent) span instead of creating transaction/span per message.
-
Polling returns a single message: in such cases, the agent may apply assumptions with regard to the threads that execute the message
handling logic in order to determine when handling starts and ends. Based on that, it would create a transaction per consumed message. If
the consumed message contains the
* Span links are supported by APM Server and Kibana since version 8.3 and by the Java agent since version 1.32.0
RabbitMQ Specifics
edit-
context.message.queue.name
field will contain queue name when using polling, exchange name otherwise. -
context.message.destination.resource
field will containrabbitmq/XXX
whereXXX
is exchange name.
Some exchange/queue names are normalized in order to keep low cardinality and user-friendlyness
- default exchange is indicated with <default>
.
- null
exchange is normalized to <unknown>
, for example when polling without a message.
- generated queues whose name start with amq.gen-
are normalized to amq.gen-*
.
Scheduling frameworks
editWhen using a scheduling framework a transaction for every execution will be created.
Framework | Supported versions | Description | Since |
---|---|---|---|
Scheduling Annotation |
The agent instruments any method defined in a package configured in |
1.6.0, |
|
Quartz |
1.0+ |
The agent instruments the NOTE: only classes from the quartz-jobs dependency will be instrumented automatically. For the instrumentation of other jobs the package must be added to the |
1.8.0 - 2.0+ 1.26.0 - 1.0+ |
TimerTask |
The agent instruments the |
1.18.0 |
Logging frameworks
editThere are multiple log-related features in the agent and their support depend on the logging framework:
-
Correlation:
The agent automatically injects
trace.id
,transaction.id
anderror.id
into the MDC implementation (see below for framework specific MDC implementations used. MDC = Mapped Diagnostic Context, a standard way to enrich log messages with additional information). For service correlation, the agent sets values forservice.name
,service.version
andservice.environment
, using ECS log format is required (ecs-logging-java
or reformatting). -
Error capturing:
Automatically captures exceptions for calls like
logger.error("message", exception)
. -
Reformatting:
When
log_ecs_reformatting
is enabled, logs will be automatically reformatted into ECS-compatible format.
Framework | Supported versions | Description | Since |
---|---|---|---|
slf4j |
1.4.1+ |
Error capturing - 1.10.0 |
|
log4j2 |
Correlation - 2.0+ Reformatting - 2.6+ |
|
Correlation (traces) - 1.13.0 Correlation (service) - 1.29.0 Error capturing - 1.10.0 Reformatting - 1.22.0 |
log4j1 |
Correlation & error capture - 1.x Reformatting - 1.2.17 |
|
Correlation (traces) - 1.13.0 Correlation (service) - 1.38.0 Reformatting - 1.22.0 Error capturing - 1.30.0 |
Logback |
1.1.0+ |
|
Correlation (traces) - 1.0.0 Correlation (service) - 1.38.0 ECS Reformatting - 1.22.0 |
JBoss Logging |
3.0.0+ |
|
Correlation (traces) - 1.23.0 (LogManager 1.30.0) Correlation (service) - 1.38.0 Reformatting - 1.31.0 |
JUL - |
All supported Java versions |
Correlation is only supported with ECS logging (library or reformatting) as JUL does not provide any MDC implementation. |
Correlation (traces) - 1.35.0 (requires ECS logging) Correlation (service) - 1.38.0 (requires ECS logging) Reformatting - 1.31.0 Error capturing - 1.31.0 |
Tomcat JULI |
7.0.0+ |
Trace correlation is only supported with ECS logging (library or reformatting) as JUL does not provide any MDC implementation. Tomcat access logs are not supported. |
Correlation (traces) - 1.35.0 (requires ECS logging) Correlation (service) - 1.38.0 (requires ECS logging) Reformatting - 1.35.0 Error capturing - 1.35.0 |
Process frameworks
editFramework | Supported versions | Description | Since |
---|---|---|---|
|
Instruments |
1.13.0 |
|
Apache commons-exec |
1.3 |
Async process support through |
1.13.0 |
RPC frameworks
editFramework | Supported versions | Description | Since |
---|---|---|---|
gRPC |
1.6.1+ |
Client (synchronous & asynchronous) & Server instrumentation. Streaming calls are currently not instrumented. |
1.16.0 |
AWS Lambda runtimes
editAWS Lambda provides multiple JVM base images. Only those that support the AWS_LAMBDA_EXEC_WRAPPER
environment variables are supported out of the box.
Running with unsupported images is still possible but requires providing agent configuration through environment variables explicitly.
Tags | Java Runtime | Operating System | Supported |
---|---|---|---|
11 |
Java 11 (Corretto) |
Amazon Linux 2 |
yes |
8.al2 |
Java 8 (Corretto) |
Amazon Linux 2 |
yes |
8 |
Java 8 (OpenJDK) |
Amazon Linux 2018.03 |
no |
Java method monitoring
editIf you are seeing gaps in the span timeline and want to include additional methods, there are several options. See How to find slow methods for more information.
Metrics
editFramework | Description | Since |
---|---|---|
Built-in metrics |
The agent sends various system, JVM, and application metrics. See the metrics documentation. |
1.3.0 |
JMX |
Set the configuration option |
1.11.0 |
Micrometer |
Automatically detects and reports the metrics of each |
1.18.0 |
Caveats
edit- Other JVM languages, like Scala, Kotlin and Groovy have not been tested yet.