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
orcgroupv2)
- 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.
- csr of
-
JDK-8336684 Enhance JCmd by adding a new command to summarize target r/t metadata
- In Progress