Java Virtual Machine

Installation

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

Supported Versions

HTTP Versions
Akka Http >= 2.4, >= 10.0
Axis >= 1.3
Axis 2 >= 1.5
Apache HttpClient >= 3.0, >= 4.3
CXF >= 3.1
HttpUrlConnection
Feign >= 9.0.0
Finagle >= 6.45.0
Grizzly >= 2.3
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 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
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
Neo4j Java Driver >= 1.5.0
SpyMemcached >= 2.12
Shade >= 1.8
Vert.x Redis >= 3.1.0
Messaging & Async Versions
ActiveMQ
Aerospike >= 3.3, >= 4.0
Amazon SQS >= 1.11
Akka >= 2.4
Camel >= 2.17
Executor Pools
Fork Join Pool
GRPC >= 1.4
HornetQ >= 2.2
Hystrix
IBM MQ >= 8.0
JMS
Kafka >= 0.8
Mule >= 3.8
RabbitMQ >= 3.6
Logging Versions
Java Util Logging
log4j >= 1.2
log4j2 >= 2.6
Slf4j >= 1.7
Other Versions
Amazon DynamoDB >= 1.11
Corba (Sun)
FTP
Glassfish EJB
Googe Cloud Store >= 1.2
Java Mail
JBoss EJB >= 5, >=7
LDAP
OpenEJB
Quartz
Spring Batch >= 3.0
Tabex

Supported JVM Vendors and Versions

Instana supports JVMs Java 6 - 11. Support for Java 12 is experimental and subject to change until GA of Java 12. 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

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.

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:

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

If not desired, this feature can be disabled with the following configuration:

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

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.

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.