System requirements

JVM support

The following table outlines the JVM distributions that are supported:

Considerations for Java Runtimes 8 or earlier versions

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.

Considerations for Java Runtimes 9 or later versions

Java 9 introduces modularized builds based on the Jigsaw framework. If you are using Java Runtimes 9 or later versions, ensure that you 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
  

  Note: 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
  

IBM J9 limitations

Instana supports IBM J9 subject to the following limitations:

• If -javaagent is not set as a command-line argument, certain versions of IBM J9 might not support all the required features. Therefore, start the JVM with Java agent by running the following command:

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

  The JAR file is available in maven central. For more information about the JVM agent, see the GitHub repository.

  If you are using Java 8 - Service refresh 3 fix pack 22 (Dec 2016), use the -XX:+EnableHCR option to perform the same operation. With this temporary option, late attached agents can redefine or retransform classes. However, this option might incur a performance penalty and might be removed in a future update when no longer necessary.

• Extra command-line switches might be required to enable tracing and metrics collection from IBM J9:

  • Use -Dcom.ibm.tools.attach.enable=yes as the default setting.

  • For IBM J9 SDK 6 or IBM J9 SDK 7, complete the following steps:

    • Disable class sharing by using the setting -Xshareclasses:none.
    • Enable an implementation of class sharing that supports bytecode instrumentation (BCI) by using the setting -Xshareclasses:enableBCI.

    Note: IBM J9 SDK configuration defaults have the following differences:

    • Version 6 (JRE 1.6.0) and version 7 (JRE 1.7.0) default to an implementation of class sharing that doesn't support BCI. Thus, class sharing must be turned off or BCI support must be turned on.
    • Version 8 (JRE 1.8.0) defaults to an implementation of class sharing that supports BCI.

Incompatible agent

Do not attempt to use agents from multiple vendors at the same time. You might encounter unpredictable results that might lead to application failure. The Instana agent does not automatically monitor JVMs that also run the following agents:

• AppDynamics
• DataDog
• Dynatrace
• Glow Root
• Kanela, the Kamon Instrumentation Agent
• ManageEngine APM Insight Java Agent
• New Relic
• Oracle Java Flight Recorder
• OpenTelemetry Instrumentation for Java
• Riverbed AppInternals
• Spring Loaded
• Wily Introscope, also known as CA Application Performance Management and Broadcom DX Application Performance Management

If you decide to monitor JVMs running any of these agents, set the following value:

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