Documentation for -XX:[+|-]EnableDynamicAgentLoading

[JasonFengJ9]

Issue or pull request number:

• Add support for -XX:[+/-]EnableDynamicAgentLoading flag openj9#17215
• Implement JEP 451: Prepare to Disallow the Dynamic Loading of Agents openj9#17932
• JEP 451 skips the warning message if the agent library was loaded openj9#17990

Overview:
For Java 8 and later, the dynamic loading of JVM TI agents is enabled by default unless -XX:-EnableDynamicAgentLoading is specified.

For Java 21 and later, the following warnings are issued when an agent is loaded dynamically into a running VM after startup without specifying the -XX:+EnableDynamicAgentLoading option and the same agent wasn't loaded before:

WARNING: A {Java,JVM TI} agent has been loaded dynamically (file:/u/bob/agent.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

For AIX platform that can't detect if an agent library was previously loaded, the warnings will be issued when an agent is loaded dynamically through Attach API VirtualMachine.loadAgentLibrary(agent) even if the agent was loaded via the command line -agentpath:/Absolute/Path/to/agentLibrary at startup.

Release target:
Eclipse OpenJ9 0.41.0

Applies to the following JDK versions:
-XX:[+|-]EnableDynamicAgentLoading - 8 and later
Issuing the warning message - 21 and later

Applies to the following platforms:
All platforms

For new command line options:

• Option name and syntax: e.g. -XX:[+|-]EnableDynamicAgentLoading

[pshipton]

We should also mention the new jcmd supported command JVMTI.agent_load, at least in the release notes.

[JasonFengJ9]

0.41.md is not available yet.
Probably no need to update https://eclipse.dev/openj9/docs/tool_jcmd/ which doesn't show the diagnostic command details, only examples.

[Sreekala-Gopakumar]

@JasonFengJ9 - What was the reason for introducing this new option? What was going wrong in the absence of this option?

What is the default setting for this option? The following line was not clear

For Java 8 and later, the dynamic loading of JVM TI agents is enabled by default unless -XX:-EnableDynamicAgentLoading is specified.

The "unless -XX:-EnableDynamicAgentLoading is specified" is confusing. Is "dynamic loading of JVM TI agents" different from specifying -XX:+EnableDynamicAgentLoading? Or does this line mean that -XX:+EnableDynamicAgentLoading is the default setting?

[JasonFengJ9]

What was the reason for introducing this new option? What was going wrong in the absence of this option?

This is a JEP 451 requirement.

What is the default setting for this option?

The current default setting is -XX:+EnableDynamicAgentLoading.

Is "dynamic loading of JVM TI agents" different from specifying -XX:+EnableDynamicAgentLoading? Or does this line mean that -XX:+EnableDynamicAgentLoading the default setting?

Correct, -XX:+EnableDynamicAgentLoading is the default setting.

[Sreekala-Gopakumar]

@JasonFengJ9 - Is the following content correct?

"With the Attach API, your application can connect to a running VM and load an agent dynamically into that VM to run tasks. Some libraries misuse the Attach API to dynamically load an agent to run tasks without the approval of the application owner.

You can disable the dynamic loading of the agents into a VM after startup with the -XX:-EnableDynamicAgentLoading option. To enable dynamic loading explicitly, specify the -XX:+EnableDynamicAgentLoading option.

For Java™ 21 and later, the following warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the -XX:+EnableDynamicAgentLoading option or no agents are loaded at startup by using the command-line options:

WARNING: A {Java,JVM TI} agent has been loaded dynamically (file:/u/bob/agent.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
```"

[Sreekala-Gopakumar]

@JasonFengJ9 - I also need a clarification regarding "...or the agent hasn't been loaded" as mentioned in the issue #1140 (comment). Does it mean that warnings are issued even if the -XX:+EnableDynamicAgentLoading option is specified but agents are not loaded at startup by using the command-line options?

[JasonFengJ9]

@Sreekala-Gopakumar I made some modifications according to a later PR

• JEP 451 skips the warning message if the agent library was loaded openj9#17990

Is the following content correct?
I also need a clarification regarding "...or the agent hasn't been loaded" as mentioned in the issue #1140 (comment). Does it mean that warnings are issued even if the -XX:+EnableDynamicAgentLoading option is specified but agents are not loaded at startup by using the command-line options?

Please match the updated issue description.

[Sreekala-Gopakumar]

Thanks, Jason!