Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8259479

JFR: Allow 'jfr' tool to show metadata without a recording

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 17
    • hotspot
    • None
    • jfr
    • behavioral
    • minimal
    • add/remove/modify command line option
    • JDK

    Description

      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*'

      Attachments

        Issue Links

          Activity

            People

              ddong Denghui Dong
              egahlin Erik Gahlin
              Erik Gahlin
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: