1JFR(1) JDK Commands JFR(1)
2
6 jfr - print and manipulate Flight Recorder files
7
9 To print the contents of a flight recording to standard out:
10 jfr print [options] file
12 To display aggregated event data on standard out:
14 jfr view [options] file
16 To configure a .jfc settings file:
18 jfr configure [options]
20 To print metadata information about flight recording events:
22 jfr metadata [file]
24 To view the summary statistics for a flight recording file:
26 jfr summary file
28 To remove events from a flight recording file:
30 jfr scrub [options] file
32 To assemble chunk files into a flight recording file:
34 jfr assemble repository file
36 To disassemble a flight recording file into chunk files:
38 jfr disassmble [options] file
40 options
42 Optional: Specifies command-line options separated by spaces.
43 See the individual subcomponent sections for descriptions of the
44 available options.
45 file Specifies the name of the target flight recording file (.jfr).
47 repository
49 Specifies the location of the chunk files which are to be assem‐
50 bled into a flight recording.
51
53 The jfr command provides a tool for interacting with flight recorder
54 files (.jfr). The main function is to filter, summarize and output
55 flight recording files into human readable format. There is also sup‐
56 port for scrubbing, merging and splitting recording files.
57 Flight recording files are created and saved as binary formatted files.
59 Having a tool that can extract the contents from a flight recording and
60 manipulate the contents and translate them into human readable format
61 helps developers to debug performance issues with Java applications.
62 Subcommands
64 The jfr command has several subcommands:
65 • print
67 • view
69 • configure
71 • metadata
73 • summary
75 • scrub
77 • assemble
79 • disassemble
81 jfr print subcommand
83 Use jfr print to print the contents of a flight recording file to stan‐
84 dard out.
85 The syntax is:
87 jfr print [--xml|--json] [--categories <filters>] [--events <filters>]
89 [--stack-depth <depth>] <file>
90 where:
92 --xml Print the recording in XML format.
94 --json Print the recording in JSON format.
96 --categories <filters>
98 Select events matching a category name. The filter is a comma-
99 separated list of names, simple and/or qualified, and/or quoted
100 glob patterns.
101 --events <filters>
103 Select events matching an event name. The filter is a comma-
104 separated list of names, simple and/or qualified, and/or quoted
105 glob patterns.
106 --stack-depth <depth>
108 Number of frames in stack traces, by default 5.
109 <file> Location of the recording file (.jfr)
111 The default format for printing the contents of the flight recording
113 file is human readable form unless either xml or json is specified.
114 These options provide machine-readable output that can be further
115 parsed or processed by user created scripts.
116 Use jfr --help print to see example usage of filters.
118 To reduce the amount of data displayed, it is possible to filter out
120 events or categories of events. The filter operates on the symbolic
121 name of an event, set by using the @Name annotation, or the category
122 name, set by using the @Category annotation. If multiple filters are
123 used, events from both filters will be included. If no filter is used,
124 all the events will be printed. If a combination of a category filter
125 and event filter is used, the selected events will be the union of the
126 two filters.
127 For example, to show all GC events and the CPULoad event, the following
129 command could be used:
130 jfr print --categories GC --events CPULoad recording.jfr
132 Event values are formatted according to the content types that are be‐
134 ing used. For example, a field with the jdk.jfr.Percentage annotation
135 that has the value 0.52 is formatted as 52%.
136 Stack traces are by default truncated to 5 frames, but the number can
138 be increased/decreased using the --stack-depth command-line option.
139 jfr view subcommand
141 Use jfr view to aggregate and display event data on standard out.
142 The syntax is:
144 jfr view [--verbose] [--width <integer>] [--truncate <mode>] [--cell-
146 height <integer>] <view> <file>
147 where:
149 --verbose
151 Displays the query that makes up the view.
152 --width <integer>
154 The width of the view in characters. Default value depends on
155 the view.
156 --truncate <mode>
158 How to truncate content that exceeds space in a table cell.
159 Mode can be 'beginning' or 'end'. Default value is 'end'.
160 --cell-height <integer>
162 Maximum number of rows in a table cell. Default value depends
163 on the view.
164 <view> Name of the view or event type to display. Use jfr --help view
166 to see a list of available views.
167 <file> Location of the recording file (.jfr)
169 The <view> parameter can be an event type name. Use the jfr view types
171 <file> to see a list. To display all views, use jfr view all-views
172 <file>. To display all events, use jfr view all-events <file>.
173 jfr configure subcommand
175 Use jfr configure to configure a .jfc settings file.
176 The syntax is:
178 jfr configure [--interactive] [--verbose] [--input ] [--output ] [op‐
180 tion=value]* [event-setting=value]*
181 --interactive
183 Interactive mode where the configuration is determined by a set
184 of questions.
185 --verbose
187 Displays the modified settings.
188 --input <files>
190 A comma-separated list of .jfc files from which the new configu‐
191 ration is based. If no file is specified, the default file in
192 the JDK is used (default.jfc). If 'none' is specified, the new
193 configuration starts empty.
194 --output <file>
196 The filename of the generated output file. If not specified,
197 the filename custom.jfc will be used.
198 option=value
200 The option value to modify. To see available options, use jfr
201 help configure
202 event-setting=value
204 The event setting value to modify. Use the form: <event-
205 name>#<setting-name>=<value> To add a new event setting, prefix
206 the event name with '+'.
207 The whitespace delimiter can be omitted for timespan values, i.e.
209 20ms. For more information about the settings syntax, see Javadoc of
210 the jdk.jfr package.
211 jfr metadata subcommand
213 Use jfr metadata to display information about events, such as event
214 names, categories and field layout within a flight recording file.
215 The syntax is:
217 jfr metadata [--categories ] [--events ] []
219 --categories <filter>
221 Select events matching a category name. The filter is a comma-
222 separated list of names, simple and/or qualified, and/or quoted
223 glob patterns.
224 --events <filter>
226 Select events matching an event name. The filter is a comma-
227 separated list of names, simple and/or qualified, and/or quoted
228 glob patterns.
229 <file> Location of the recording file (.jfr)
231 If the parameter is omitted, metadata from the JDK where the 'jfr' tool
233 is located will be used.
234 jfr summary subcommand
236 Use jfr summary to print statistics for a recording. For example, a
237 summary can illustrate the number of recorded events and how much disk
238 space they used. This is useful for troubleshooting and understanding
239 the impact of event settings.
240 The syntax is:
242 jfr summary <file>
244 where:
246 <file> Location of the flight recording file (.jfr)
248 jfr scrub subcommand
250 Use jfr scrub to remove sensitive contents from a file or to reduce its
251 size.
252 The syntax is:
254 jfr scrub [--include-events <filter>] [--exclude-events <filter>]
256 [--include-categories <filter>] [--exclude-categories <filter>] [--in‐
257 clude-threads <filter>] [--exclude-threads <filter>] <input-file>
258 [<output-file>]
259 --include-events <filter>
261 Select events matching an event name.
262 --exclude-events <filter>
264 Exclude events matching an event name.
265 --include-categories <filter>
267 Select events matching a category name.
268 --exclude-categories <filter>
270 Exclude events matching a category name.
271 --include-threads <filter>
273 Select events matching a thread name.
274 --exclude-threads <filter>
276 Exclude events matching a thread name.
277 <input-file>
279 The input file to read events from.
280 <output-file>
282 The output file to write filter events to. If no file is speci‐
283 fied, it will be written to the same path as the input file, but
284 with "-scrubbed" appended to the filename.
285 The filter is a comma-separated list of names, simple and/or qualified,
287 and/or quoted glob patterns. If multiple filters are used, they are
288 applied in the specified order.
289 jfr assemble subcommand
291 Use jfr assemble to assemble chunk files into a recording file.
292 The syntax is:
294 jfr assemble <repository> <file>
296 where:
298 <repository>
300 Directory where the repository containing chunk files is locat‐
301 ed.
302 <file> Location of the flight recording file (.jfr).
304 Flight recording information is written in chunks. A chunk contains
306 all of the information necessary for parsing. A chunk typically con‐
307 tains events useful for troubleshooting. If a JVM should crash, these
308 chunks can be recovered and used to create a flight recording file us‐
309 ing this jfr assemble command. These chunk files are concatenated in
310 chronological order and chunk files that are not finished (.part) are
311 excluded.
312 jfr disassemble subcommand
314 Use jfr disassemble to decompose a flight recording file into its chunk
315 file pieces.
316 The syntax is:
318 jfr disassemble [--max-chunks <chunks>] [--output <directory>] <file>
320 where:
322 --output <directory>
324 The location to write the disassembled file, by default the cur‐
325 rent directory
326 --max-chunks <chunks>
328 Maximum number of chunks per file, by default 5. The chunk size
329 varies, but is typically around 15 MB.
330 --max-size <size>
332 Maximum number of bytes per file.
333 <file> Location of the flight recording file (.jfr)
335 This function can be useful for repairing a broken file by removing the
337 faulty chunk. It can also be used to reduce the size of a file that is
338 too large to transfer. The resulting chunk files are named my‐
339 file_1.jfr, myfile_2.jfr, etc. If needed, the resulting file names
340 will be padded with zeros to preserve chronological order. For exam‐
341 ple, the chunk file name is myfile_001.jfr if the recording consists of
342 more than 100 chunks.
343 jfr version and help subcommands
345 Use jfr --version or jfr version to view the version string information
346 for this jfr command.
347 To get help on any of the jfr subcommands, use:
349 jfr <--help|help> [subcommand]
351 where:
353 [subcommand] is any of:
355 • print
357 • view
359 • configure
361 • metadata
363 • summary
365 • scrub
367 • assemble
369 • disassemble
371JDK 21 2023 JFR(1)