Java Virtual Machine

Introduction

The Java sensor provides automated code instrumentation for supported technologies, zero configuration health monitoring of JVM instances, and end-to-end traces of requests across all systems.

System requirements

Instana officially supports Java 6 or higher. Java 13 is considered experimental.

Due to potential JVM bugs, we recommend using the most up to date JVM versions to make use of bug-free runtimes.

Note: Do not attempt to use agents from multiple vendors at the same time; this leads to unpredictable results and might crash your application. The Instana agent does not automatically monitor JVMs that also have the following agents running:

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

This is not supported. If you decide to monitor JVMs running any of the above agents, set the following value:

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

JVM support

The following JVM distributions are supported.

Name Limitations
Amazon Corretto -
Azul Zulu -
IBM J9 See IBM J9 limitations.
IBM OpenJ9 -
OpenJDK -
Oracle Hotspot -
SAP JVM -
Sun Hotspot -
BEA JRockit -

Java 8 or lower

Java 8 builds up to 1.8.0_40 have several known issues relating to the implementation of lambdas. Due to these issues, the Instana agent does not monitor Java 8 builds 1.8.0_40 or lower.

If using the G1 garbage collector, please update to 1.8.0_181 or later. 1.8.0_40 fixes JVM crashes that may happen when your application has a high load and runs any other agent.

If using Java 8 or lower on Amazon Corretto, Azul Zulu, OpenJDK, Oracle Hotspot, or SAP JVM, make the tools.jar file available in the runtime of each monitored JVM. The file is located here $JAVA_HOME/lib/tools.jar.

Java 9 or higher

Java 9 introduces modularized builds based on the Jigsaw framework. If you use a custom runtime image, such as those created with jmod or jlink, make sure to include the following two modules in the instrumented JVM:

  • java.instrument
  • jdk.attach

TIP: To check if your Java 9 or higher runtime contains the required java.instrument and jdk.attach modules, run the following command:

java --list-modules

If you try running the command on a JVM version 8 or lower, the Unrecognized option: --list-modules error message is displayed.

Running on Windows

A popular choice for running services, such as Apache Tomcat, is to use the in-process Server JVM.

In those cases the monitored processes do not run as C:\java12\bin\java.exe but as C:\Program Files\Apache Software Foundation\Tomcat 8.5\bin\Tomcat8.exe. This setup is supported, but before starting the service like this set PATH=%PATH%;C:\java12\bin, the bin directory on the JVM running the service must be on the PATH.

This is because the server jvm.dll needs to load the C:\java12\bin\instrument.dll. If it is specified on the path, it will not find it, and this results in an error:

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

IBM J9 limitations

If -javaagent is not set as a command line argument, certain versions of J9 will not support all the required features. We recommend starting the JVM with the javaagent by running this command:

java -javaagent:instana-javaagent-1.0.0.jar -jar app.jar server

The jar is available in maven central and for more information about the JVM agent, see the GitHub repository.

If using Java 8 - Service refresh 3 fix pack 22 (Dec 2016), the -XX:+EnableHCR option performs the same operation. This temporary option enables late attached agents to redefine or retransform classes, it might incur a performance penalty, however, it will be removed in a future update.

To enable tracing, additional command line switches may be required:

  • -Dcom.ibm.tools.attach.enable=yes should be the default setting.
  • -Xshareclasses:none (class sharing can interfere with bytecode instrumentation) or if available -Xshareclasses:enableBCI to enable instrumentation despite class sharing.

Instrumented frameworks and libraries

HTTP libraries

Name 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 >= 2.0
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

Name 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
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, >= 4.1, >= 5.0
SpyMemcached >= 2.10
Shade >= 1.8
Vert.x Redis >= 3.1.0

Messaging services

Name Versions
ActiveMQ >= 5.13
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 frameworks

Name Versions
Java Util Logging
JBoss Log Manager >= 1.0
Log4j >= 1.2
Log4j 2 >= 2.4
SLF4J >= 1.7

Web and application servers

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

Other instrumented technologies

Name Versions
Akka Remote >= 2.3
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

Installation

The Java sensor is automatically deployed, configured, and installed by the Instana agent. To ensure your Java applications are instrumented, make sure your JVM distribution is supported.

Configuration

Although there is no configuration required for out of the box metrics and distributed tracing, individual components are configurable.

For more information on how to configure the sensor, see Java configuration.

Metrics collection

On the JVM dashboard, configuration and performance metrics for the JVM instance are displayed, along with any custom metrics.

Configuration data

Configuration Description
Java version The Java version.
Java runtime The Java Runtime Environment (JRE).
Maximum heap Maximum heap size (GiB) allocated to the JVM.
Classpath The classpath parameter set in the JVM.

Performance metrics

Memory used

Total memory used by the JVM. The current measured KPI value is displayed.

Data point: Byte count is collected from java.lang.Runtime#totalMemory.

Threads

Number of threads that are in states: new, runnable, timed-waiting, waiting, or blocked. The values are displayed on a graph over a selected time period.

Data point:

  • Current thread-ids are collected from java.lang.management.ThreadMXBean#getAllThreadIds.
  • Thread states are collected from ThreadMXBean#getThreadInfo.

Heap Memory

Total heap memory used by the JVM. The value is displayed on a graph over a selected time period.

Data point:

  • Byte count is collected from java.lang.Runtime#totalMemory.
  • The maximum displayed in the graph is either determined by parsing the -Xmx command line parameter or is collected from java.lang.Runtime#maxMemory.

Memory Pools

Memory pool usage. Heap and non-heap pools are displayed on a graph over a selected time period.

Data point:

  • Pool information is collected from ManagementFactory#getMemoryPoolMXBeans.
  • Graph values are collected from each pools java.lang.management.MemoryUsage.
  • The maximum value is collected from getMax, the initial value is collected from getInit, and the current value is collected from getUsage.

Garbage Collection

Garbage collection activation and runtime values are displayed on a graph over a selected time period.

Data points:

  • Garbage collection information is collected from ManagementFactory#getGarbageCollectorMXBeans.
  • Graph values are collected from each collectors java.lang.management.GarbageCollectorMXBean.
  • Garbage collection runtime is collected from getCollectionTime which, according to JavaDoc, is the approximate accumulated collection elapsed time in milliseconds.
  • Invocation count is collected from getCollectionCount.
  • Both the getCollectionTime and getCollectionCount values are the calculated differential during 1 second.

Suspension

Calculated suspension of application execution displayed on a graph over a selected time period.

Data point: Calculated per the in-app Instana measurement thread.

Health signatures

Event Description
Garbage collection activity high A processing pipeline monitors the Garbage Collection time spent by the JVM Runtime Platform and validates it against a threshold.
JVM code cache is full A processing pipeline monitors the maximum Code Cache usage of the JVM Runtime Platform.
Perm Gen is full (CMS) A processing pipeline detects the maximum Perm Gen CMS Pools utilized.
Perm Gen is full (G1) A processing pipeline detects the maximum Perm Gen G1 Pools utilized.
Perm Gen is full (PS) A processing pipeline detects the maximum Perm Gen PS Pools utilized.
Threads are deadlocked A detector monitors the JVM Runtime Platform and detects if there are any Deadlocked threads.

Custom metrics

Dropwizard Metrics Library

If the JVM has the Dropwizard metrics library loaded, custom metrics are collected and displayed at the bottom of the JVM dashboard.

To prevent the backend from overloading, there is a default limit of 200 metrics.

To disable or change the limit of metrics being gathered, use the following configuration:

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

If the metrics are not displayed even though the library is loaded, register your MetricRegistry instance as the default. For example:

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 are collected and displayed at the bottom of the JVM’s dashboard. To prevent the backend from overloading, there is a default limit of 200 metrics.

To disable or change the limit of metrics being gathered, use the following configuration:

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

If the metrics not be displayed even though the library is loaded, consider registering your io.micrometer.core.instrument.MeterRegistry instance as the default one. For example:

import io.micrometer.core.instrument.Metrics;

Metrics.globalRegistry.add(meterRegistry)

Other features

Live Thread Dump

To view a live thread dump for the JVM, click Get Thread Dump.

Instana AutoTrace™

By default, all requests are monitored, and a distributed trace is created automatically for each of them. This includes cross host and cross language tracing.

For more information, see Instana AutoTrace™.

Logging MDC populated with the Trace ID

When using Log4j, Log4j2, or Logback, to enable a more precise correlation of logging and tracing, Instana automatically populates the MDC with the trace ID. The MDC variable name is instana.trace.id.

For information on how to use it in format strings, refer to the documentation for your logging framework.

Custom tracing

Fully automated out-of-the-box tracing instrumentation is provided, but in some cases, you may prefer to send custom traces to your Instana dashboard. If so, there are are number of available methods.

Java Trace SDK

If you want to instrument a framework that is not yet supported by Instana, or monitor the requests of a custom application, we recommend using the Java Trace SDK and viewing the GitHub repo.

Before you implement custom tracing using the SDK, please read the tracing best practices.

Java OpenTracing API

To collect traces that are described via the OpenTracing API, you must use Java OpenTracing. For more information, see OpenTracing.

IMPORTANT: Please disable automatic tracing (Instana AutoTrace™) before using the Java OpenTracing API. For more information, see Disabling automatic instrumentation.

OpenCensus Instana Trace Exporter

To trace data for Java applications, Instana provides an “Exporter” which is the logic that translates spans defined via the OpenCensus model to Instana’s. Using the Instana agent processes as proxy, Instana forwards traces that are exported by applications instrumented with Census to its backend.

For more information, see the GitHub repo.

IMPORTANT: Please disable automatic tracing (Instana AutoTrace™) if the agent is used on the same host as Census. For more information, see Disabling automatic instrumentation.

Jaeger

Jaeger is a distributed tracing system released as open source by Uber Technologies with a data model compatible with OpenTracing.

To send Jaeger traces directly to the Instana agent, configure a Sender to use the endpoint http://<instana-agent>:42699/com.instana.plugin.jaeger.trace.

Zipkin

Zipkin is a distributed tracing system similar to Jaeger. It has out of the box instrumentation support for some popular frameworks.

To send Zipkin spans to Instana, create a reporter with the endpoint http://<instana-agent>:42699/api/v2/spans.

Website monitoring (End User Monitoring)

Instana provides deep end user monitoring (EUM) that links server side traces with browser events to give you a complete view from server to browser. To start tracking website performance data, go to the Websites section within Instana and you are guided through the installation process.

For more information, see Website Monitoring.