1JFR(1)                           JDK Commands                           JFR(1)
2
3
4

NAME

6       jfr - parse and print Flight Recorder files
7

SYNOPSIS

9       To print the contents of a flight recording to standard out:
10
11       jfr print [options] file
12
13       To print metadata information about flight recording events:
14
15       jfr metadata file
16
17       To assemble chunk files into a flight recording file:
18
19       jfr assemble repository file
20
21       To disassemble a flight recording file into chunk files:
22
23       jfr disassmble [options] file
24
25       To view the summary statistics for a flight recording file:
26
27       jfr summary file
28
29       options
30              Optional:  Specifies  command-line  options separated by spaces.
31              See the individual subcomponent sections for descriptions of the
32              available options.
33
34       file   Specifies the name of the target flight recording file (.jfr).
35
36       repository
37              Specifies the location of the chunk files which are to be assem‐
38              bled into a flight recording.
39

DESCRIPTION

41       The jfr command provides a tool for interacting  with  flight  recorder
42       files  (.jfr).   The  main  function is to filter, summarize and output
43       flight recording files into human readable format.  There is also  sup‐
44       port for merging and splitting recording files.
45
46       Flight recording files are created and saved as binary formatted files.
47       Having a tool that can extract the contents from a flight recording and
48       manipulate  the  contents and translate them into human readable format
49       helps developers to debug performance issues with Java applications.
50
51   Subcommands
52       The jfr command has several subcommands:
53
54       • print
55
56       • summary
57
58       • assemble
59
60       • disassemble
61
62       • metadata
63
64   jfr print subcommand
65       Use jfr print to print the contents of a flight recording file to stan‐
66       dard out.  The syntax is:
67
68       jfr print  [--xml|--json] [--categories <filters>] [--events <filters>]
69       [--stack-depth <depth>] <file>
70
71       where:
72
73       --xml  Print the recording in XML format
74
75       --json Print the recording in JSON format
76
77       --categories <filters>
78              Select events matching a category name.  The filter  is  a  com‐
79              ma-separated  list  of  names,  simple  and/or qualified, and/or
80              quoted glob patterns
81
82       --events <filters>
83              Select events matching an event name.   The  filter  is  a  com‐
84              ma-separated  list  of  names,  simple  and/or qualified, and/or
85              quoted glob patterns
86
87       --stack-depth <depth>
88              Number of frames in stack traces, by default 5
89
90       <file> Location of the recording file (.jfr)
91
92       The default format for printing the contents of  the  flight  recording
93       file  is  human  readable  form unless either xml or json is specified.
94       These options provide  machine-readable  output  that  can  be  further
95       parsed or processed by user created scripts.
96
97       Use jfr --help print to see example usage of filters.
98
99       To  reduce  the  amount of data displayed, it is possible to filter out
100       events or categories of events.  The filter operates  on  the  symbolic
101       name  of  an  event, set by using the @Name annotation, or the category
102       name, set by using the @Category annotation.  If multiple  filters  are
103       used, events from both filters will be included.  If no filter is used,
104       all the events will be printed.  If a combination of a category  filter
105       and  event filter is used, the selected events will be the union of the
106       two filters.
107
108       For example, to show all GC events and the CPULoad event, the following
109       command could be used:
110
111       jfr print --categories GC --events CPULoad recording.jfr
112
113       Event  values are formatted according to the content types that are be‐
114       ing used.  For example, a field with the jdk.jfr.Percentage  annotation
115       that has the value 0.52 is formatted as 52%.
116
117       Stack  traces  are by default truncated to 5 frames, but the number can
118       be increased/decreased using the --stack-depth command-line option.
119
120   jfr summary subcommand
121       Use jfr summary to print statistics for a recording.   For  example,  a
122       summary  can illustrate the number of recorded events and how much disk
123       space they used.  This is useful for troubleshooting and  understanding
124       the impact of event settings.
125
126       The syntax is:
127
128       jfr summary <file>
129
130       where:
131
132       <file> Location of the flight recording file (.jfr)
133
134   jfr metadata subcommand
135       Use jfr metadata to view information about events, such as event names,
136       categories and field layout within a flight recording file.  The syntax
137       is:
138
139       jfr metadata <file>
140
141       where:
142
143       <file> Location of the flight recording file (.jfr)
144
145   jfr assemble subcommand
146       Use jfr assemble to assemble chunk files into a recording file.
147
148       The syntax is:
149
150       jfr assemble <repository> <file>
151
152       where:
153
154       <repository>
155              Directory where the repository containing chunk files is located
156
157       <file> Location of the flight recording file (.jfr)
158
159       Flight  recording  information  is written in chunks.  A chunk contains
160       all of the information necessary for parsing.  A chunk  typically  con‐
161       tains  events useful for troubleshooting.  If a JVM should crash, these
162       chunks can be recovered and used to create a flight recording file  us‐
163       ing  this  jfr assemble command.  These chunk files are concatenated in
164       chronological order and chunk files that are not finished  (.part)  are
165       excluded.
166
167   jfr disassemble subcommand
168       Use jfr disassemble to decompose a flight recording file into its chunk
169       file pieces.  The syntax is:
170
171       jfr disassemble [--max-chunks <chunks>] [--output <directory>] <file>
172
173       where:
174
175       --output <directory>
176              The location to write the disassembled file, by default the cur‐
177              rent directory
178
179       --max-chunks <chunks>
180              Maximum number of chunks per file, by default 5.  The chunk size
181              varies, but is typically around 15 MB.
182
183       --max-size <size>
184              Maximum number of bytes per file.
185
186       <file> Location of the flight recording file (.jfr)
187
188       This function can be useful for repairing a broken file by removing the
189       faulty chunk.  It can also be used to reduce the size of a file that is
190       too large to  transfer.   The  resulting  chunk  files  are  named  my‐
191       file_1.jfr,  myfile_2.jfr,  etc.   If  needed, the resulting file names
192       will be padded with zeros to preserve chronological order.   For  exam‐
193       ple, the chunk file name is myfile_001.jfr if the recording consists of
194       more than 100 chunks.
195
196   jfr version and help subcommands
197       Use jfr --version or jfr version to view the version string information
198       for this jfr command.
199
200       To get help on any of the jfr subcommands, use:
201
202       jfr <--help|help> [subcommand]
203
204       where:
205
206       [subcommand] is any of:
207
208       • print
209
210       • metadata
211
212       • summary
213
214       • assemble
215
216       • disassemble
217
218
219
220JDK 17                               2021                               JFR(1)