System requirements for Java monitoring

Instana supports the following JVM distributions:

• Amazon Corretto
• Azul Zulu
• IBM J9 (For more information, see IBM J9 and OpenJ9 considerations and IBM J9 and OpenJ9 limitations)
• Eclipse OpenJ9 (For more information, see IBM J9 and OpenJ9 considerations)
• OpenJDK
• AdoptOpenJDK
• Oracle HotSpot
• SAP JVM
• Sun HotSpot
• BEA JRockit
• Hitachi JVM

If you are using Java Runtimes 8 or earlier versions, ensure that you complete the following actions:

• 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 at $JAVA_HOME/lib/tools.jar.

• If you use Java 8, upgrade to Java 8 1.8.0_181 or later versions. The Java 8 builds up to 1.8.0_40 have many known issues that are related to the implementation of the lambda function. So for Java 8, the Instana agent does not support 1.8.0_40 or earlier versions. Therefore, you must upgrade to later versions because some crashes are fixed in them.

Java 9 introduces modularized builds based on the Jigsaw framework. If you are using Java Runtimes 9 or later versions, complete the following actions:

• If you use a custom runtime image, such as the ones created with jmod or jlink , make sure that you include the following modules in the instrumented JVM:

  • java.instrument
  • jdk.attach

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

  java --list-modules
   

  If you run the command on a JVM 8 or earlier, the Unrecognized option: --list-modules error message is displayed.

• If Apache Tomcat is running on Windows as a service, then the monitored processes do not run as the C:\java12\bin\java.exe file but as theC:\Program Files\Apache Software Foundation\Tomcat 8.5\bin\Tomcat8.exe file.

  Instana supports this setup. But before you start the service, the bin directory on the JVM running the service must be on the PATH. To set the path, run the following command:

  set PATH=%PATH%;C:\java12\bin
   

  The path must be set because the server jvm.dll file needs to load the C:\java12\bin\instrument.dll file. If the file is not specified on the path, the server cannot find it, and the following error is displayed:

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

If you are using Java Runtime 21, you might encounter the following warning messages:

WARNING: A Java agent has been loaded dynamically (/tmp/.instana/javaagent-loader-1.3.56.jar)
WARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading to hide this warning
WARNING: If a serviceability tool is not in use, please run with -Djdk.instrument.traceUsage for more information
WARNING: Dynamic loading of agents will be disallowed by default in a future release
 

To prevent this problem, add the following command in virtual machine arguments before you start your application:

-XX:+EnableDynamicAgentLoading
 

The Instana host agent creates temporary JAR files in the $TMP/.instana directory. These JAR files are required for the JVM monitoring. For successful JVM monitoring, ensure that the root user that runs the agent and the user that runs the JVM have the necessary read and write permissions for the $TMP directory. Also, do not clean up the Instana files from the $TMP and $TMP/.instana directories.

If you see logs, such as Suppressed spans due to high number of short or Discarded span due to queue overflow, in the agent log, it means that the Java Tracer experienced heavy load on span processing. As a result, the Java Tracer drops a few spans to avoid performance issues in the application.

To reduce the load, the Java Tracer performs the following steps:

1. It suppresses the exit spans that have a short duration.
2. If the load is still high, it groups spans in batches.
3. If batching is not successful, it drops a few spans.