Summary

Add jcmd <pid> VM.usage_metadata to print metadata describing the JVM invocation.

Problem

Many monitoring and observability agent(s) (and other such tools) want to obtain metadata from JVMs that describes how they were configured and invoked, e.g:

• JVM version class and/or module path
• JAVA_HOME
• any JVM flags specified
• any JVM arguments specified
• program arguments
• JVM start time
• JVM uptime
• if executing in the context of a "resource manager" (Docker etc)
• ...

in order to obtain such, these agent(s) must currently invoke multiple jcmd's, if such exists.

This is not optimal for a variety of reasons.

Solution

Add a new command that the jcmd command line tool can use to print metadata about JVM usage.

The output is formatted (either in plain text or as JSON) as a list of key,value tuples.

The command effectively treats the individual metadata "fields" as System property names, and where none exist for particular metadata (such as JVM uptime) a "synthetic" property (name) is used in order to uniquely name such metadata.

Here is example output (the output is JSON encoded to enable programmatic parsing).

135986:
{ 
 "timestamp" : "2024-09-10T12:06:02.953-0700", 
  "jvm.starttime" : "2024-09-10T19:05:41.976+0000", 
  "java.home" : "/home/auser/src/git/jdk/open/build/linux-x86_64-server-release/jdk", 
  "java.version" : "24-internal", 
  "java.vm.version" : "24-internal-adhoc.lpgc.open", 
  "sun.java.launcher" : "SUN_STANDARD", 
  "jvm.args" : [ "-Dapplication.home=/home/auser/src/git/jdk/open/build/linux-x86_64-server-release/jdk", "-Xms8m", "-Djdk.module.main=jdk.jshell" ], 
  "sun.java.command" : "jdk.jshell/jdk.internal.jshell.tool.JShellToolProvider",
  "java.class.path" : "", 
  "jvm.pid" : "135986", 
  "jvm.uptime.ms" : "21123", 
  "user.name" : "auser", 
  "user.dir" : "/home/auser/src/git/jdk/open", 
  "os.name" : "Linux", "os.version" : "4.18.0-553.16.1.el8_10.x86_64", 
  "os.arch" : "amd64" 
}

an example of plain text is:

135986:
"timestamp"="2024-09-10T12:26:17.478-0700", 
"jvm.starttime"="2024-09-10T19:05:41.976+0000",
"java.home"="/home/auser/src/git/jdk/open/build/linux-x86_64-server-release/jdk", 
"java.version"="24-internal", "java.vm.version"="24-internal-adhoc.auser.open", 
"sun.java.launcher"="SUN_STANDARD", 
"jvm.args"="'-Dapplication.home=/home/auser/src/git/jdk/open/build/linux-x86_64-server-release/jdk', '-Xms8m', '-Djdk.module.main=jdk.jshell'", 
"sun.java.command"="jdk.jshell/jdk.internal.jshell.tool.JShellToolProvider", "java.class.path"="", 
"jvm.pid"="135986", 
"jvm.uptime.ms"="1235648", 
"user.name"="auser", 
"user.dir"="/home/auser/src/git/jdk/open", 
"os.name"="Linux", 
"os.version"="4.18.0-553.16.1.el8_10.x86_64", "os.arch"="amd64"

Specification

The man page jcmd(1) describes this new jcmd as:

VM.usage_metadata [options]

Print VM usage metadata as a formatted list of key & (non null) value tuples.

Impact: Low

Note:

The following options must be specified using either key or key=value syntax.

options:

• format: (Optional) Output format ("plain" or "json") (STRING, plain)

• filepath: The file path to the output file into which, append usage metadata (STRING, no default value)

• fields: a comma separated list of fields (System properties, real or synthetic) to print (when non-null) overriding the default (STRING, see below)

Fields are either System Property names(c.f: java.lang.System for definitions), or certain "synthetic" properties (where there is no pre-existing System Property):

• jvm.args: any command line arguments specified for the JVM.

• jvm.container.info: (linux only) if the JVM is executing within the context of a cgroup, emit:

  • type (cgroupv1 or cgroupv2)
  • container (host) name (usually by convention the container id)
  • memory.limit
  • # of active.cpus therein.

• jvm.flags: the JVM flags.

• jvm.pid: the process id of the JVM.

• jvm.starttime: the time when the JVM completed its initialization just prior to commencing execution of user code.

• jvm.uptime.ms: the uptime (in ms) of the JVM.

• timestamp: the current time.