How to Prevent Java Agent from Loading in JDK Tools Inside Cloud‑Native Containers

Background

Large‑scale cloud‑native microservice deployments increasingly rely on Java Agent technology to inject non‑intrusive governance logic (observability, tracing, traffic control) into Java processes without modifying application code.

Problem

When the Java Agent is injected via environment variables (e.g., JAVA_TOOL_OPTIONS), the agent is loaded by every JVM started in the container, including JDK tools such as java -version, jps, jstack, and jcmd. This adds 6‑7 seconds of start‑up latency, consumes extra CPU and memory, and hampers rapid troubleshooting because diagnostic tools must first load the agent.

Root Cause

JVM options are read from several environment variables: JAVA_TOOL_OPTIONS – read by all Java commands, including JDK tools. JDK_JAVA_OPTIONS – introduced in OpenJDK 9, read only by the java launcher. IBM_JAVA_OPTIONS and OPENJ9_JAVA_OPTIONS – vendor‑specific extensions.

Because JDK tools also honor JAVA_TOOL_OPTIONS, they inadvertently load the Java Agent.

Solution with Dragonwell

Dragonwell (Alibaba’s OpenJDK distribution) adds two environment variables that let users separate agent injection from tool execution: DRAGONWELL_JAVA_OPTIONS – analogous to IBM_JAVA_OPTIONS, used for Dragonwell‑specific JVM flags. DRAGONWELL_JAVA_TOOL_OPTIONS_JDK_ONLY – when set to true, the JVM treats JAVA_TOOL_OPTIONS as applicable only to the java command; JDK tools ignore it, preventing the agent from loading in those processes.

Usage Guidelines

For parameters that should affect both the Java runtime and JDK tools, set them in JAVA_TOOL_OPTIONS.

For Dragonwell‑specific switches, set them in DRAGONWELL_JAVA_OPTIONS.

To apply Java‑wide parameters without affecting JDK tools, set JAVA_TOOL_OPTIONS **and** DRAGONWELL_JAVA_TOOL_OPTIONS_JDK_ONLY=true.

On JDK 9+ platforms, prefer the standard JDK_JAVA_OPTIONS variable instead of JAVA_TOOL_OPTIONS.

Result

After configuring the Dragonwell variables, diagnostic tools such as jps, jstack, and java -version run without loading the Java Agent, while the business Java process continues to load the agent and thus retains full microservice governance capabilities.

References

Demo repository (MSE simple demo): https://github.com/aliyun/alibabacloud-microservice-demo/tree/master/mse-simple-demo/helm/mse-simple-demo

MSE documentation: https://mp.weixin.qq.com/s/95WZHL0HhFtzxMlfK-8jkg

IBM_JAVA_OPTIONS documentation: https://www.ibm.com/docs/en/zos/2.3.0?topic=runtime-java-options

OPENJ9_JAVA_OPTIONS documentation: https://www.eclipse.org/openj9/docs/cmdline_specifying/#precedence

Discussion on Dragonwell GitHub issue: https://github.com/alibaba/dragonwell8/issues/330#issuecomment-1138083844