.\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.

.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

.\"

.\" This code is free software; you can redistribute it and/or modify it

.\" under the terms of the GNU General Public License version 2 only, as

.\" published by the Free Software Foundation.

.\"

.\" This code is distributed in the hope that it will be useful, but WITHOUT

.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

.\" version 2 for more details (a copy is included in the LICENSE file that

.\" accompanied this code).

.\"

.\" You should have received a copy of the GNU General Public License version

.\" 2 along with this work; if not, write to the Free Software Foundation,

.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

.\"

.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

.\" or visit www.oracle.com if you need additional information or have any

.\" questions.

.\"

.\" Automatically generated by Pandoc 2.3.1

.\"

.TH "JFR" "1" "2019" "JDK 13" "JDK Commands"

.hy

.SH NAME

.PP

jfr \- parse and print Flight Recorder files

.SH SYNOPSIS

.PP

To print the contents of a flight recording to standard out:

.PP

\f[CB]jfr\f[R] \f[CB]print\f[R] [\f[I]options\f[R]] \f[I]file\f[R]

.PP

To print metadata information about flight recording events:

.PP

\f[CB]jfr\f[R] \f[CB]metadata\f[R] \f[I]file\f[R]

.PP

To assemble chunk files into a flight recording file:

.PP

\f[CB]jfr\f[R] \f[CB]assemble\f[R] \f[I]repository\f[R] \f[I]file\f[R]

.PP

To disassemble a flight recording file into chunk files:

.PP

\f[CB]jfr\f[R] \f[CB]disassmble\f[R] [\f[I]options\f[R]] \f[I]file\f[R]

.PP

To view the summary statistics for a flight recording file:

.PP

\f[CB]jfr\f[R] \f[CB]summary\f[R] \f[I]file\f[R]

.TP

.B \f[I]options\f[R]

Optional: Specifies command\-line options separated by spaces.

See the individual subcomponent sections for descriptions of the

available options.

.RS

.RE

.TP

.B \f[I]file\f[R]

Specifies the name of the target flight recording file

(\f[CB]\&.jfr\f[R]).

.RS

.RE

.TP

.B \f[I]repository\f[R]

Specifies the location of the chunk files which are to be assembled into

a flight recording.

.RS

.RE

.SH DESCRIPTION

.PP

The \f[CB]jfr\f[R] command provides a tool for interacting with flight

recorder files (\f[CB]\&.jfr\f[R]).

The main function is to filter, summarize and output flight recording

files into human readable format.

There is also support for merging and splitting recording files.

.PP

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.

.SS Subcommands

.PP

The \f[CB]jfr\f[R] command has several subcommands:

.IP \[bu] 2

\f[CB]print\f[R]

.IP \[bu] 2

\f[CB]summary\f[R]

.IP \[bu] 2

\f[CB]assemble\f[R]

.IP \[bu] 2

\f[CB]disassemble\f[R]

.IP \[bu] 2

\f[CB]metadata\f[R]

.SS \f[CB]jfr\ print\f[R] subcommand

.PP

Use \f[CB]jfr\ print\f[R] to print the contents of a flight recording file

to standard out.

The syntax is:

.PP

\f[CB]jfr\ print\f[R] [\f[CB]\-\-xml\f[R]|\f[CB]\-\-json\f[R]]

[\f[CB]\-\-categories\f[R] <\f[I]filters\f[R]>] [\f[CB]\-\-events\f[R]

<\f[I]filters\f[R]>] [\f[CB]\-\-stack\-depth\f[R] <\f[I]depth\f[R]>]

<\f[I]file\f[R]>

.PP

where:

.TP

.B \f[CB]\-\-xml\f[R]

Print the recording in XML format

.RS

.RE

.TP

.B \f[CB]\-\-json\f[R]

Print the recording in JSON format

.RS

.RE

.TP

.B \f[CB]\-\-categories\f[R] <\f[I]filters\f[R]>

Select events matching a category name.

The filter is a comma\-separated list of names, simple and/or qualified,

and/or quoted glob patterns

.RS

.RE

.TP

.B \f[CB]\-\-events\f[R] <\f[I]filters\f[R]>

Select events matching an event name.

The filter is a comma\-separated list of names, simple and/or qualified,

and/or quoted glob patterns

.RS

.RE

.TP

.B \f[CB]\-\-stack\-depth\f[R] <\f[I]depth\f[R]>

Number of frames in stack traces, by default 5

.RS

.RE

.TP

.B <\f[I]file\f[R]>

Location of the recording file (\f[CB]\&.jfr\f[R])

.RS

.RE

.PP

The default format for printing the contents of the flight recording

file is human readable form unless either \f[CB]xml\f[R] or \f[CB]json\f[R]

is specified.

These options provide machine\-readable output that can be further

parsed or processed by user created scripts.

.PP

Use \f[CB]jfr\ \-\-help\ print\f[R] to see example usage of filters.

.PP

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

\f[CB]\@Name\f[R] annotation, or the category name, set by using the

\f[CB]\@Category\f[R] 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.

.PP

For example, to show all GC events and the CPULoad event, the following

command could be used:

.PP

\f[CB]jfr\ print\ \-\-categories\ GC\ \-\-events\ CPULoad\ recording.jfr\f[R]

.PP

Event values are formatted according to the content types that are being

used.

For example, a field with the \f[CB]jdk.jfr.Percentage\f[R] annotation

that has the value 0.52 is formatted as 52%.

.PP

Stack traces are by default truncated to 5 frames, but the number can be

increased/decreased using the \f[CB]\-\-stack\-depth\f[R] command\-line

option.

.SS \f[CB]jfr\ summary\f[R] subcommand

.PP

Use \f[CB]jfr\ summary\f[R] 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.

.PP

The syntax is:

.PP

\f[CB]jfr\ summary\f[R] <\f[I]file\f[R]>

.PP

where:

.TP

.B <\f[I]file\f[R]>

Location of the flight recording file (\f[CB]\&.jfr\f[R])

.RS

.RE

.SS \f[CB]jfr\ metadata\f[R] subcommand

.PP

Use \f[CB]jfr\ metadata\f[R] to view information about events, such as

event names, categories and field layout within a flight recording file.

The syntax is:

.PP

\f[CB]jfr\ metadata\f[R] <\f[I]file\f[R]>

.PP

where:

.TP

.B <\f[I]file\f[R]>

Location of the flight recording file (\f[CB]\&.jfr\f[R])

.RS

.RE

.SS jfr \f[CB]assemble\f[R] subcommand

.PP

Use jfr \f[CB]assemble\f[R] to assemble chunk files into a recording file.

.PP

The syntax is:

.PP

\f[CB]jfr\ assemble\f[R] <\f[I]repository\f[R]> <\f[I]file\f[R]>

.PP

where:

.TP

.B <\f[I]repository\f[R]>

Directory where the repository containing chunk files is located

.RS

.RE

.TP

.B <\f[I]file\f[R]>

Location of the flight recording file (\f[CB]\&.jfr\f[R])

.RS

.RE

.PP

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 \f[CB]jfr\ assemble\f[R] command.

These chunk files are concatenated in chronological order and chunk

files that are not finished (.part) are excluded.

.SS \f[CB]jfr\ disassemble\f[R] subcommand

.PP

Use \f[CB]jfr\ disassemble\f[R] to decompose a flight recording file into

its chunk file pieces.

The syntax is:

.PP

\f[CB]jfr\ disassemble\f[R] [\f[CB]\-\-max\-chunks\f[R] <\f[I]chunks\f[R]>]

[\f[CB]\-\-output\f[R] <\f[I]directory\f[R]>] <\f[I]file\f[R]>

.PP

where:

.TP

.B \f[CB]\-\-output\f[R] <\f[I]directory\f[R]>

The location to write the disassembled file, by default the current

directory

.RS

.RE

.TP

.B \f[CB]\-\-max\-chunks\f[R] <\f[I]chunks\f[R]>

Maximum number of chunks per file, by default 5.

The chunk size varies, but is typically around 15 MB.

.RS

.RE

.TP

.B \f[CB]\-\-max\-size\f[R] <\f[I]size\f[R]>

Maximum number of bytes per file.

.RS

.RE

.TP

.B <\f[I]file\f[R]>

Location of the flight recording file (\f[CB]\&.jfr\f[R])

.RS

.RE

.PP

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 \f[CB]myfile_1.jfr\f[R],

\f[CB]myfile_2.jfr\f[R], etc.

If needed, the resulting file names will be padded with zeros to

preserve chronological order.

For example, the chunk file name is \f[CB]myfile_001.jfr\f[R] if the

recording consists of more than 100 chunks.

.SS jfr version and help subcommands

.PP

Use \f[CB]jfr\ \-\-version\f[R] or \f[CB]jfr\ version\f[R] to view the

version string information for this jfr command.

.PP

To get help on any of the jfr subcommands, use:

.PP

\f[CB]jfr\ <\-\-help|help>\f[R] [\f[I]subcommand\f[R]]

.PP

where:

.PP

[\f[I]subcommand\f[R]] is any of:

.IP \[bu] 2

\f[CB]print\f[R]

.IP \[bu] 2

\f[CB]metadata\f[R]

.IP \[bu] 2

\f[CB]summary\f[R]

.IP \[bu] 2

\f[CB]assemble\f[R]

.IP \[bu] 2

\f[CB]disassemble\f[R]