Supported Java versions
|Java versions||Support status|
|6 through 11||GA|
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
|Akka Http||>= 2.4, >= 10.0|
|Axis 2||>= 1.5|
|Apache HttpClient||>= 3.0, >= 4.3|
|Asynch HttpClient||>= 2.0.9, >= 2.1.0|
|Jersey||>= 1.17, >= 2.10|
|Servlet||>= 2.0, >= 3.0|
|Spring Rest||>= 4.2.0|
|Spring Web||>= 4.2.0|
|Spring Webflux||>= 5.0.1|
|WebMethods Glue||>= 5.2|
|Wicket||>= 6.0, >= 7.0|
|Amazon DynamoDB||>= 1.11|
|Amazon Elasticache||>= 1.11|
|Cassandra||>= 2.0, >= 3.0|
|ElasticSearch||>= 1.4, >= 2.0, >= 5.0, >= 6.0|
|Googe Cloud Bigtable HBase 1.x||>= 1.0.0|
|Googe Cloud Bigtable HBase 2.x||>= 1.1.0|
|Googe Cloud Store||>= 1.2|
|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|
|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|
|Fork Join Pool|
|IBM MQ||>= 8.0|
|Java Util Logging|
|Amazon DynamoDB||>= 1.11|
|Googe Cloud Store||>= 1.2|
|GWT User||>= 1.2|
|JBoss EJB||>= 5, >=7|
|Lift Actor||>= 2.11|
|Sun ON/RPC||>= 1.1.4|
|Spring Batch||>= 3.0|
Supported 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, SAP Java
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, SAP and OpenJDK). The
tools.jar is typically located at
$JAVA_HOME/lib/tools.jar of the monitored JVM. Missing the
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:
-Dcom.ibm.tools.attach.enable=yes(this switch should be default on, but there were instances where this was not the case)
-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:enableBCIto allow instrumentation despite class sharing.
This and more information is available at the GitHub instana-javaagent repository.
Java 9+ Custom Runtime Images
Instana requires the
java.instrumentation module to be present, when using a custom runtime image.
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:
- 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
- Code Cache
- GC Activity
- 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.
If not desired, this feature can be disabled with the following configuration:
com.instana.plugin.java: dropwizardMetricCollection: enabled: false
- Automatic tracing of all requests
- Cross host and cross language tracing
- Supports OpenTracing
The Instana Java sensor supports OpenTracing. See https://github.com/instana/instana-java-opentracing for details.
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.
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:
deltais used for values like counters that increase over time, where the relative change is interesting.
absoluteis 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.