jfr - print and manipulate Flight Recorder files
To print the contents of a flight recording to standard out:
jfr print [options] file
To display aggregated event data on standard out:
jfr view [options] file
To configure a .jfc settings file:
jfr configure [options]
To print metadata information about flight recording events:
jfr metadata [file]
To view the summary statistics for a flight recording file:
jfr summary file
To remove events from a flight recording file:
jfr scrub [options] file
To assemble chunk files into a flight recording file:
jfr assemble repository file
To disassemble a flight recording file into chunk files:
jfr disassmble [options] file
The jfr command provides a tool for interacting with flight recorder files (.jfr). The main function is to filter, summarize and output flight recording files into human readable format. There is also support for scrubbing, merging and splitting recording files.
Flight recording files are created and saved as binary formatted files. Having a tool that can extract the contents from a flight recording and manipulate the contents and translate them into human readable format helps developers to debug performance issues with Java applications.
The jfr command has several subcommands:
Use jfr print to print the contents of a flight recording file to standard out.
The syntax is:
jfr print [--xml|--json] [--categories <filters>] [--events <filters>] [--stack-depth <depth>] <file>
where:
The default format for printing the contents of the flight recording file is human readable form unless either xml or json is specified. These options provide machine-readable output that can be further parsed or processed by user created scripts.
Use jfr --help print to see example usage of filters.
To reduce the amount of data displayed, it is possible to filter out events or categories of events. The filter operates on the symbolic name of an event, set by using the @Name annotation, or the category name, set by using 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 the --stack-depth command-line option.
Use jfr view to aggregate and display event data on standard out.
The syntax is:
jfr view [--verbose] [--width <integer>] [--truncate <mode>] [--cell-height <integer>] <view> <file>
where:
The <view> parameter can be an event type name. Use the jfr view types <file> to see a list. To display all views, use jfr view all-views <file>. To display all events, use jfr view all-events <file>.
Use jfr configure to configure a .jfc settings file.
The syntax is:
jfr configure [--interactive] [--verbose] [--input ] [--output ] [option=value]* [event-setting=value]*
The whitespace delimiter can be omitted for timespan values, i.e. 20ms. For more information about the settings syntax, see Javadoc of the jdk.jfr package.
Use jfr metadata to display information about events, such as event names, categories and field layout within a flight recording file.
The syntax is:
jfr metadata [--categories ] [--events ] []
If the parameter is omitted, metadata from the JDK where the 'jfr' tool is located will be used.
Use jfr summary to print statistics for a recording. For example, a summary can illustrate the number of recorded events and how much disk space they used. This is useful for troubleshooting and understanding the impact of event settings.
The syntax is:
jfr summary <file>
where:
Use jfr scrub to remove sensitive contents from a file or to reduce its size.
The syntax is:
jfr scrub [--include-events <filter>] [--exclude-events <filter>] [--include-categories <filter>] [--exclude-categories <filter>] [--include-threads <filter>] [--exclude-threads <filter>] <input-file> [<output-file>]
The filter is a comma-separated list of names, simple and/or qualified, and/or quoted glob patterns. If multiple filters are used, they are applied in the specified order.
Use jfr assemble to assemble chunk files into a recording file.
The syntax is:
jfr assemble <repository> <file>
where:
Flight recording information is written in chunks. A chunk contains all of the information necessary for parsing. A chunk typically contains events useful for troubleshooting. If a JVM should crash, these chunks can be recovered and used to create a flight recording file using this jfr assemble command. These chunk files are concatenated in chronological order and chunk files that are not finished (.part) are excluded.
Use jfr disassemble to decompose a flight recording file into its chunk file pieces.
The syntax is:
jfr disassemble [--max-chunks <chunks>] [--output <directory>] <file>
where:
This function can be useful for repairing 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. If needed, the resulting file names will be padded with zeros to preserve chronological order. For example, the chunk file name is myfile_001.jfr if the recording consists of more than 100 chunks.
Use jfr --version or jfr version to view the version string information for this jfr command.
To get help on any of the jfr subcommands, use:
jfr <--help|help> [subcommand]
where:
[subcommand] is any of: