Java Virtual Machine

Supported Java versions

Java versions Support status
6 through 11 GA
12 Experimental

Some JVMs by different vendors have occasional quirks. For more information, have a look at the Supported JVM Vendors and Versions section.


The installation is performed automatically by the agent through Java runtime attach.

Supported Libraries & Versions

HTTP Versions
Akka Http >= 2.4, >= 10.0
Axis >= 1.3
Axis 2 >= 1.5
Apache HttpClient >= 3.0, >= 4.3
Asynch HttpClient >= 2.0.9, >= 2.1.0
CXF >= 3.1
Feign >= 9.0.0
Finagle >= 6.45.0
Grizzly >= 2.3
HttpKit >= 2.2.0
Jersey >= 1.17, >= 2.10
NanoHttpd >= 2.2
OkHttpd >= 3.0
Play2 >= 2.3
Ratpack >= 1.5
Resteasy >= 3.0
Servlet >= 2.0, >= 3.0
Spray >= 1.3
Spring Rest >= 4.2.0
Spring Web >= 4.2.0
Spring Webflux >= 5.0.1
Vaadin >= 7.0
Vert.x >= 3.3
WebMethods Glue >= 5.2
Wicket >= 6.0, >= 7.0
Databases Versions
Amazon DynamoDB >= 1.11
Amazon Elasticache >= 1.11
Cassandra >= 2.0, >= 3.0
Couchbase >= 2.5.5
Ehcache >= 2.0
ElasticSearch >= 1.4, >= 2.0, >= 5.0, >= 6.0
FaunaDB >= 1.2
Googe Cloud Bigtable HBase 1.x >= 1.0.0
Googe Cloud Bigtable HBase 2.x >= 1.1.0
Googe Cloud Store >= 1.2
JDBC >= 4
Jedis >= 2.8
Lettuce >= 3.0, >= 4.0
MongoDB >= 2.13, >= 3.0
MongoDB Reactive >= 0.14.0
Neo4j Java Driver >= 1.5.0
Redis Jedis >= 2.8.0
Redis Lettuce >= 3.4.2
SpyMemcached >= 2.12
Shade >= 1.8
Vert.x Redis >= 3.1.0
Messaging & Async Versions
Aerospike >= 3.3, >= 4.0
Amazon Kinesis >= 0.8
Amazon SNS >= 1.11
Amazon SQS >= 1.11
Akka >= 2.4
Camel >= 2.17
Executor Pools
Fork Join Pool
GRPC >= 1.4
HornetQ >= 2.2
IBM MQ >= 8.0
Kafka >= 0.8
Mule >= 3.8
RabbitMQ >= 3.6
Tibco ESB
Logging Versions
Java Util Logging
log4j >= 1.2
log4j2 >= 2.6
Slf4j >= 1.7
Other Versions
Amazon DynamoDB >= 1.11
Corba (Sun)
FTP Commons
Glassfish EJB
Googe Cloud Store >= 1.2
GWT User >= 1.2
Java Mail
JBoss EJB >= 5, >=7
Lift Actor >= 2.11
Sun ON/RPC >= 1.1.4
Spring Batch >= 3.0

Notes for specific JVM Vendors and Versions

We recommend to use the most up to date JVM versions due to JVM bugs you might encounter: APM agents perform low-level, refined operations and it is good to use the most bug-free runtimes one has access to.

To underline the importance of updated runtimes, there are several known issues in Java 8 builds up to 1.8.0_40, mostly related to how lambdas were first implemented. These issues are so severe that the Instana agent will not monitor by default Java 8 versions 1.8.0_40 and older.

If you are using the G1 garbage collector, we recommend that you update to 1.8.0_181 or later: 1.8.0_40 finally fixes JVM crashes that you might experience when your application has really high load and runs any agent (not only Instana’s).

Oracle & Sun Hotspot, OpenJDK, Azul Zulu, Amazon Corretto, SAP Java up to Java 8

The agent will “attach” to the JVM, meaning it will load additional logic that constitues the automatic instrumentation. We recommend the tools.jar to be made available in the runtime of the monitored JVM on HotSpot derivatives (Oracle, Azul, Amazon, SAP and OpenJDK). The tools.jar is typically located at $JAVA_HOME/lib/tools.jar of the monitored JVM. A missing tools.jar could result in failed attach attempts.


IBM J9 version 1.6 is not supported, and no attempt is performed to trace through applications running on it.

For IBM J9, it might be necessary to add command line switches to enable tracing:

  • (this switch should be default on, but there were instances where this was not the case)
  • -javaagent:instana-javaagent-1.0.0.jar or -XX:+EnableHCR (only available as of “Java 8 - Service refresh 3 fix pack 22 (Dec 2016)“)
  • -Xshareclasses:none (class sharing interferes with bytecode instrumentation); alternatively you may use -Xshareclasses:enableBCI to allow instrumentation despite class sharing.

This and more information is available at the GitHub instana-javaagent repository.

Java 9 and newer

Instana requires the java.instrumentation module to be present, when using a custom runtime image (created with jmod / jlink).

Other monitoring agents

Instana plays by the rules defined by the Instrumentation API. We pride ourselves in the quality and correctness of our bytecode modifications. This means that, in theory, we can run in combination with other monitoring agents that implement equally correct bytecode modifications. The reality of things is, however, that we received crash reports from users trying to mix Instana’s with other APM agents. As a result, the Instana agent does not automatically monitor JVMs that run any of the following agents:

  • AppDynamics
  • New Relic
  • Wily Introscope
  • Spring Loaded
  • Glow Root
  • Java Flight Recorder

It is possible to configure Instana to monitor JVMs running these agents using the following configuration; notice, however, that no support is provided in case of issues:

  trace-jvms-with-problematic-agents: true

Sensor Data Collection

Tracked Configuration Metrics
Version GC Activity
Runtime Memory Usage
Heap Memory Pools
Classpath Threads

Health Signatures

  • Code Cache
  • PermGen
  • GC Activity
  • Heap

Other Features

  • Live Thread Dump

Dropwizard Metrics Library

If the JVM has the Dropwizard metrics library loaded, custom metrics will be collected and displayed at the end of the JVM’s dashboard. Default limit of 200 metrics is used to prevent the backend from overloading.

The following configuration can be used to disable or change the limit of metrics being gathered:
    enabled: false
    limit: 300

Should the metrics not be visible even though the library is loaded, please consider registering your MetricRegistry instance as the default one like the following code snippet shows.

import com.codahale.metrics.SharedMetricRegistries;
import com.codahale.metrics.MetricRegistry;

MetricRegistry metricRegistry = new MetricRegistry();
SharedMetricRegistries.setDefault("default", metricRegistry);

Micrometer Metrics Library

If the JVM has the Micrometer metrics library loaded, custom metrics will be collected and displayed at the end of the JVM’s dashboard. Default limit of 200 metrics is used to prevent the backend from overloading.

The following configuration can be used to disable or change the limit of metrics being gathered:
    enabled: false
    limit: 300

Should the metrics not be visible even though the library is loaded, please consider adding your io.micrometer.core.instrument.MeterRegistry instances to the global registry as the following code snippet shows.

import io.micrometer.core.instrument.Metrics;


More info about micrometer data collection here



  • Automatic tracing of all requests
  • Cross host and cross language tracing
  • Supports OpenTracing


The Instana Java sensor supports OpenTracing. See for details.

Trace SDK

For the case where Instana does not (yet) know how to instrument a framework, or for monitoring the requests of a very custom application, the Java Trace SDK ( can be used.

Trace ID in Logging MDC

For log4j 1&2 as well as logback, Instana will automatically populate the MDC with the trace ID to enable easy correlation of logging and tracing. The name of the MDC variable is - Please refer to the documentation of your logger on how to use it in format strings.


Custom JMX

You can configure what JMX to monitor in the Agent (configuration.yaml):
    # JMX is NOT hot-reloaded and needs to be set before a JVM is discovered.
    # Supported attribute types are Number and Boolean
    # delta calculation is only supported for Number
    - object_name: 'java.lang:type=Compilation'
        - attributes: 'TotalCompilationTime'
          type: 'delta' # delta will report the change to the previous second
    - object_name: 'java.lang:type=ClassLoading'
        - attributes: 'LoadedClassCount'
          type: 'absolute' # absolute will report the value as-is

In the example above, there are two different types of metric specified:

  • delta is used for values like counters that increase over time, where the relative change is interesting.
  • absolute is used for values that show the actual value each time the metric is accessed.

Metrics will appear in the JVM Dashboard under ”Custom JMX“.

Configuring the Display Name

Instana automatically picks up the name from the jar file that is launched if present. Otherwise it will use the command line, similar to how the basic Java tools display the JVMs.

There are two standard attributes inside the jar, in META-INF/Manifest.MF:

    Implementation-Title=Demo App

Those can usually be set using build tools when building the application. For more information see:

If no name can be obtained by the procedure outlined above, Instana will try to figure out a name heuristically by inspecting various environment variables, for example -Dcatalina.home for Tomcat containers.

The display name can also be set explicitly by providing"My Custom Name" when starting the JVM. This option takes precedence over everything else.