XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P2
    • Resolution: Approved
    • Fix Version/s: 12
    • Component/s: hotspot
    • Labels:
    • Subcomponent:
      jfr
    • Compatibility Risk:
      minimal
    • Interface Kind:
      add/remove command in $JDK/bin

      Description

      Summary

      Provide a tool for interacting with Flight Recorder files (.jfr).

      The main functionality will allow binary file contents to be filtered, summarized and output in a human readable format. There will also be support for merging and splitting recording files.

      Problem

      Developers need a straightforward way to extract contents from a JFR recording file that doesn't involve writing a Java program, or downloading a separate tool.

      Solution

      The tool is built on top of the API available in jdk.jfr and the implementation located in the jdk.jfr module. The tool is well suited for demonstrating functionality in presentations, demos and documentation. It will work on all platforms, and in scenarios where a graphical client can’t be used.

      An alternative is JMC, but it requires an always up to date JMC parser. Also, JMC doesn't support splitting and merging of recording files.

      The functionality provided by the tool has been available in the JDK since the inception of JFR, but it has been undocumented and located in internal packages. In JDK 9, the functionality was cleaned up and proper testing added. The proposal is to move the functionality into a command line tool called jfr.

      The commands supported by the tool are:

      Print

      Print the contents of a recording file to standard out. To reduce the amount of data, it is possible to filter out events or categories of events. The filter operates on the symbolic name of an event, which is set using the @Name annotation, or the category name, set by the @Category annotation. If multiple filters are used, events from both filters will be included. If no filter is used, all the events will be printed. If a combination of a category filter and event filter is used, the selected events will be the union of the two filters. For example, to show all GC events and the CPULoad event the following command could be used:

      $> jfr print --categories GC --events CPULoad recording.jfr

      Event values are formatted according to the content types that are being used. For example, a field with the jdk.jfr.Percentage annotation that has the value 0.52 is formatted as 52%. Stack traces are by default truncated to 5 frames, but the number can be increased/decreased using a command-line option. It is also possible to output the data in XML and JSON. Such output will not be formatted according to the content type. This is to make the data machine-readable for scripts parsing the output.

      Metadata

      Print metadata about events, such as event names, categories and field layout.

      Assemble

      Assemble chunk files into a recording file, useful for recovering recording data from a crashed JVM. The files are concatenated in chronological order and files that are not finished (.part) are excluded.

      Disassemble

      Disassemble a recording file into chunk files, useful for debugging the parser and to repair a broken file by removing the faulty chunk. It can also be used to reduce the size of a file that is too large to transfer. The resulting chunk files are named myfile_1.jfr, myfile_2.jfr etc. and padded with zeros if needed to preserve chronological order, for example myfile_001.jfr if the recording consists of more than 100 chunks.

      Summary

      Print statistics for a recording, for example the number of events and how much disk space they use. Useful for troubleshooting and understanding the impact of event settings.

      Version

      Display the version of the tool, starting from 1.0. The version will be bumped when a new command-line flag is added/removed/changed, or the output format is changed.

      Help

      Display available commands, or detailed information about a particular command.

      Specification

      Print command

       jfr print [--xml|--json]
                 [--categories <filters>]
                 [--events <filters>]
                 [--stack-depth <depth>]  
                 <file>
      
       --xml                   Print recording in XML format
       --json                  Print recording in JSON format
       --categories <filters>  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 <filters>      Select events matching an event name.
                               The filter is a comma-separated list of names,
                               simple and/or qualified, and/or quoted glob patterns
       --stack-depth <depth>   Number of frames in stack traces, by default 5
       <file>                  Location of the recording file (.jfr)

      Metadata command

      jfr metadata <file>
      
      <file>                   Location of the recording file (.jfr)

      Summary command

      jfr summary <file>
      
      <file>                   Location of the recording file (.jfr)

      Assemble command

      jfr assemble <repository> 
                   <file>
      
      <repository>             Directory where the repository is located
      <file>                   Location of the recording file (.jfr)

      Disassemble command

      jfr disassemble [--max-chunks <chunks>]
                      [--output <directory>]    
                      <file>
      
      --output <directory>  The location to write the disassembled file, 
                            by default the current directory                  
      --max-chunks <chunks> Maximum number of chunks per file, by default 5.
                            The chunk size varies, but is typically around 15 MB.
      --max-size <size>     Maximum number of bytes per file. 
      <file>                Location of the recording file (.jfr)

      Version command

      jfr <--version|version>

      Help command

      jfr <--help|help> 
          [command]
      
      command                The name of the command to get help for

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                egahlin Erik Gahlin
                Reporter:
                egahlin Erik Gahlin
                Reviewed By:
                Karen Kinnear, Markus Grönlund
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: