Summary

Improve the jfr metadata command, so it can print event metadata for the JDK utilized by the jfr tool. Also, add support for filtering events by name and category, similar to the existing jfr print command.

Problem

To consume JFR events programmatically, one must know the names of event and event fields for a particular JDK release. There is however no simple way for users to find such event metadata. There is the jfr metadata command, but it can only print metadata for a recording file. This means users need to create a dummy recording for the JDK they are interested in.

For example:

$ java -XX:StartFlightRecording:filename=dummy.jfr -version
$ jfr metadata dummy.jfr
$ rm dummy.jfr

This is cumbersome and unintuitive.

Solution

Changes

The original jfr metadata command mandatorily requires a recording file, now it becomes optional. If no recording file is specified to jfr metadata, print event metadata for the JDK that the jfr tool is using:

$ jfr metadata

New features

Also add support for filtering. For example, to show all GC events and the CPULoad event metadata, the following command could be used:

$ jfr metadata --categories GC --events CPULoad

Filtering will also work when operating against a recording file.

$ jfr metadata --categories GC recording.jfr

Specification

Display event metadata, such as labels, descriptions and field layout

  jfr metadata [--categories <filter>]
               [--events <filter>]
-              <file>
+              [<file>]

+  --categories <filter>   Select events matching a category name.
+                          The filter is a comma-separated list of names,
+                          simple and/or qualified, and/or quoted glob patterns
+  
+  --events <filter>       Select events matching an event name.
+                          The filter is a comma-separated list of names,
+                          simple and/or qualified, and/or quoted glob patterns
+
   <file>                  Location of the recording file (.jfr)
 `
+ If the <file> parameter is omitted, metadata from the JDK where 
+ the 'jfr' tool is located will be used

  Example usage:

+ jfr metadata 

  jfr metadata --events jdk.ThreadStart recording.jfr

- jfr metadata --events CPULoad,GarbageCollection recording.jfr
+ jfr metadata --events CPULoad,GarbageCollection

- jfr metadata --categories 'GC,JVM,Java*' recording.jfr
+ jfr metadata --categories 'GC,JVM,Java*'

- jfr metadata --events 'Thread*' recording.jfr
+ jfr metadata --events 'Thread*'