Java Virtual Machine

Supported Java versions

Java versions Support status
6 through 12 GA
13 Experimental
JVM Distribution Support status
Amazon Corretto
Azul Zulu
IBM J9 8 (limitations apply)
OpenJDK
Oracle Hotspot
SAP JVM
Sun Hotspot
BEA JRockit

For supported JVMs, additional requirements may apply.

Supported Libraries & Versions

HTTP Versions
Akka HTTP >= 2.4, >= 10.0
Axis >= 1.3
Axis 2 >= 1.5
Apache HttpClient >= 3.0, >= 4.3
Apache Async HttpClient >= 4.0
AsyncHttpClient (AHC) >= 2.0.9, >= 2.1.0
Apache CXF >= 3.0
HttpUrlConnection
Feign >= 9.0.0
Finagle >= 6.45.0
Grizzly >= 2.1
HTTP Kit >= 2.2.0
Jersey >= 1.17, >= 2.10
JSF
NanoHTTPD >= 2.2
OkHttpd >= 3.0
Play2 >= 2.3
Ratpack >= 1.5
RESTEasy >= 3.0
Servlet >= 2.0, >= 3.0
Spray >= 1.3
Spring Cloud Gateway >= 2.0.2
Spring REST >= 4.2.0
Spring Web >= 3.2.0
Spring Webflux >= 5.0.1
Vaadin >= 7.0
Vert.x-Web >= 3.3
WebMethods Glue >= 5.0
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
Google Cloud Bigtable HBase 1.x >= 1.0.0
Google Cloud Bigtable HBase 2.x >= 1.1.0
Google Cloud Store >= 1.2
Hazelcast Java Client >= 3.9
JDBC >= 4
Lettuce >= 3.0, >= 4.0
MongoDB >= 2.13, >= 3.0
MongoDB Reactive >= 0.12.0
Neo4j Java Driver >= 1.5.0
Redis Jedis >= 2.8.0
Redis Lettuce >= 3.4.2, >= 4.1.2
SpyMemcached >= 2.10
Shade >= 1.8
Vert.x Redis >= 3.1.0
Messaging & Async Versions
ActiveMQ
Aerospike >= 3.3, >= 4.0
Amazon Kinesis >= 1.11
Amazon SNS >= 1.11
Amazon SQS >= 1.11
Akka >= 2.3
Camel >= 2.17
Executor Pools
Fork Join Pool
gRPC >= 1.2
HornetQ >= 2.2
Hystrix
IBM MQ >= 8.0
JMS
Kafka >= 0.8
Mule >= 3.8
RabbitMQ >= 3.6
Tibco ESB
Logging Versions
Java Util Logging
JBoss Log Manager >= 1.0
Log4j >= 1.2
Log4j 2 >= 2.4
SLF4J >= 1.7
Other Versions
Corba (Sun)
FTP Commons >= 3.5
FTP JSCH => 0.1.54
Glassfish EJB
Google Cloud Store >= 1.2
GWT User >= 1.2
Java Mail
JBoss EJB >= 5, >=7
Lift Actor >= 2.6.3, >= 3.3.0
LDAP
Sun ON/RPC >= 1.1.4
OpenEJB >= 4.7
Quartz
Spring Batch >= 3.0
Tabex

Supported Web & Application Servers

  • IBM Websphere
  • Oracle/BEA Weblogic
  • Apache Tomcat
  • Eclipse Jetty
  • Glassfish / Payara
  • JBoss AS / Wildfly
  • Sun ONE Server
  • Pega Systems AS

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).

Java 8 and older

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.

Java 9 and newer

Java 9 introduces modularized builds based on the Jigsaw framework. Therefore, although the tools.jar file is no longer required to be present, Instana requires the following modules to be present in the instrumented JVM:

  • java.instrument
  • jdk.attach

Therefore, if you use a custom runtime image, such as those created with jmod or jlink, make sure to include the two modules above.

NOTICE: You can check if your Java 9 (and above) runtime contains the required java.instrument and jdk.attach modules by finding them in the output of the following command:

java --list-modules

(If you try to run that command on a JVM version 8 and below, you will likely be answered with a Unrecognized option: --list-modules error message.)

Java 9 and newer on Windows

On Windows, a popular choice for running services, like Apache Tomcat, is to use the in-process Server JVM. In those cases the monitored processes are not run as C:\java12\bin\java.exe but for example as C:\Program Files\Apache Software Foundation\Tomcat 8.5\bin\Tomcat8.exe. This setup is also supported, but it is required that the bin directory from the JVM that is running the service is on the PATH before starting the service like this set PATH=%PATH%;C:\java12\bin. This is required, because the server jvm.dll needs to load the C:\java12\bin\instrument.dll. If it is not on the path, it will not find it, resulting in an error like this:

com.sun.tools.attach.AgentLoadException: Failed to load agent library: instrument was not loaded.Can't find dependent libraries

IBM J9

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:

  • -Dcom.ibm.tools.attach.enable=yes (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.

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:

com.instana.plugin.javatrace:
  trace-jvms-with-problematic-agents: true

Sensor Data Collection

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

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:

com.instana.plugin.java:
  dropwizardMetricCollection:
    enabled: false
    limit: 200

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:

com.instana.plugin.java:
  micrometerMetricCollection:
    enabled: false
    limit: 200

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

import io.micrometer.core.instrument.Metrics;

Metrics.globalRegistry.add(meterRegistry)

More info about micrometer data collection here

Tracing

Mode

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

OpenTracing

The Instana Java sensor supports OpenTracing. See https://github.com/instana/instana-java-opentracing 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 (https://github.com/instana/instana-java-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 instana.trace.id - Please refer to the documentation of your logger on how to use it in format strings.

Installation

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

Configuration

Custom JMX

You can configure what JMX to monitor in the Agent (configuration.yaml):

com.instana.plugin.java:
  jmx:
    # 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'
      metrics:
        - attributes: 'TotalCompilationTime'
          type: 'delta' # delta will report the change to the previous second
    - object_name: 'java.lang:type=ClassLoading'
      metrics:
        - 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
    Implementation-Version=1.0.0

Those can usually be set using build tools when building the application. For more information see: https://docs.oracle.com/javase/tutorial/deployment/jar/packageman.html

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 -Dcom.instana.agent.jvm.name="My Custom Name" when starting the JVM. This option takes precedence over everything else.