JFR tool

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