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
  

  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
  

Considerations for Java Runtime 21

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
  

Note: Support for Virtual threads is now available.

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. By using this temporary option, late-attached agents can redefine or retransform classes. In addition, if the following log line is present in the agent logs, ensure to pass the -XX:+EnableHCR option as a startup parameter.

  WARN  | instana-http-client-thread-16-2 | LoggerEndpoint   | com.instana.agent - 1.1.680 | JVM (1234) - JVM does not support retransformation, tracing is currently unsupported
  

  However, the -XX:+EnableHCR 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.

$TMP directory permission requirements

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, ensure that you do not clean up the Instana files from the $TMP and $TMP/.instana directories.

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

Span rate limiting

Log messages that are related to span rate limiting appear only when agent logging is in debug mode. For more information about agent logging, see Agent logging.

If you see logs like 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 dropped 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.