1 perf-script(1)
2 =============
3
4 NAME
5 ----
6 perf-script - Read perf.data (created by perf
7
8 SYNOPSIS
9 --------
10 [verse]
11 'perf script' [<options>]
12 'perf script' [<options>] record <script> [<re
13 'perf script' [<options>] report <script> [scr
14 'perf script' [<options>] <script> <required-s
15 'perf script' [<options>] <top-script> [script
16
17 DESCRIPTION
18 -----------
19 This command reads the input file and displays
20
21 There are several variants of perf script:
22
23 'perf script' to see a detailed trace of the
24 recorded.
25
26 You can also run a set of pre-canned scripts
27 summarize the raw trace data in various ways
28 available via 'perf script -l'). The follow
29 record and run those scripts:
30
31 'perf script record <script> <command>' to r
32 for 'perf script report'. <script> is the n
33 output of 'perf script --list' i.e. the actu
34 language extension. If <command> is not spe
35 recorded using the -a (system-wide) 'perf re
36
37 'perf script report <script> [args]' to run
38 of <script>. <script> is the name displayed
39 script --list' i.e. the actual script name m
40 extension. The perf.data output from a prev
41 record <script>' is used and should be prese
42 succeed. [args] refers to the (mainly optio
43 the script.
44
45 'perf script <script> <required-script-args>
46 record the events required for <script> and
47 using 'live-mode' i.e. without writing anyth
48 is the name displayed in the output of 'perf
49 actual script name minus any language extens
50 not specified, the events are recorded using
51 'perf record' option. If <script> has any r
52 should be specified before <command>. This
53 optional script args to be specified; if opt
54 desired, they can be specified using separat
55 and 'perf script report' commands, with the
56 piped to the stdin of the report script, usi
57 options of the corresponding commands.
58
59 'perf script <top-script>' to both record th
60 <top-script> and to run the <top-script> usi
61 i.e. without writing anything to disk. <top
62 displayed in the output of 'perf script --li
63 script name minus any language extension; a
64 as any script name ending with the string 't
65
66 [<record-options>] can be passed to the reco
67 record' and 'live-mode' variants; this isn't
68 <top-script> 'live-mode' or 'perf script rep
69
70 See the 'SEE ALSO' section for links to lang
71 information on how to write and run your own
72
73 OPTIONS
74 -------
75 <command>...::
76 Any command you can specify in a shell
77
78 -D::
79 --dump-raw-trace=::
80 Display verbose dump of the trace data
81
82 --dump-unsorted-raw-trace=::
83 Same as --dump-raw-trace but not sorte
84
85 -L::
86 --Latency=::
87 Show latency attributes (irqs/preempti
88
89 -l::
90 --list=::
91 Display a list of available trace scri
92
93 -s ['lang']::
94 --script=::
95 Process trace data with the given scri
96 If the string 'lang' is specified in p
97 list of supported languages will be di
98
99 -g::
100 --gen-script=::
101 Generate perf-script.[ext] starter scr
102 using current perf.data.
103
104 --dlfilter=<file>::
105 Filter sample events using the given s
106 Refer linkperf:perf-dlfilter[1]
107
108 --dlarg=<arg>::
109 Pass 'arg' as an argument to the dlfil
110 to add more arguments.
111
112 --list-dlfilters::
113 Display a list of available dlfilters.
114 before option --list-dlfilters) to sho
115
116 -a::
117 Force system-wide collection. Scripts
118 normally use -a by default, while scri
119 normally don't - this option allows th
120 system-wide mode.
121
122 -i::
123 --input=::
124 Input file name. (default: perf.data u
125
126 -d::
127 --debug-mode::
128 Do various checks like samples orderin
129
130 -F::
131 --fields::
132 Comma separated list of fields to prin
133 comm, tid, pid, time, cpu, event, trac
134 srcline, period, iregs, uregs, brstack
135 brstackinsn, brstackinsnlen, brstackdi
136 insnlen, synth, phys_addr, metric, mis
137 code_page_size, ins_lat, machine_pid,
138
139 Field list can be prepended with the t
140 to indicate to which event type the fi
141 e.g., -F sw:comm,tid,time,ip,sym and
142
143 perf script -F <fields>
144
145 is equivalent to:
146
147 perf script -F trace:<fields>
148
149 i.e., the specified fields apply to al
150 is not given.
151
152 In addition to overriding fields, it i
153 fields from the defaults. For example
154
155 -F -cpu,+insn
156
157 removes the cpu field and adds the ins
158 cannot be mixed with normal overriding
159
160 The arguments are processed in the ord
161 reset a prior request. e.g.:
162
163 -F trace: -F comm,tid,time,ip,
164
165 The first -F suppresses trace events (
166 second invocation sets the fields to c
167 warning is given to the user:
168
169 "Overriding previous field req
170
171 Alternatively, consider the order:
172
173 -F comm,tid,time,ip,sym -F tra
174
175 The first -F sets the fields for all e
176 suppresses trace events. The user is g
177 the override, and the result of the ab
178 events are displayed with the given fi
179
180 It's possible tp add/remove fields onl
181
182 -Fsw:-cpu,-period
183
184 removes cpu and period from software e
185
186 For the 'wildcard' option if a user se
187 event type, a message is displayed to
188 ignored for that type. For example:
189
190 $ perf script -F comm,tid,trac
191 'trace' not valid for hardware
192 'trace' not valid for software
193
194 Alternatively, if the type is given an
195 is an error. For example:
196
197 perf script -v -F sw:comm,tid,trace
198 'trace' not valid for software events.
199
200 At this point usage is displayed, and
201
202 The flags field is synthesized and may
203 Trace decoding. The flags are "bcrosyi
204 call, return, conditional, system, asy
205 transaction abort, trace begin, trace
206 VM-Exit, interrupt disabled and interr
207 Known combinations of flags are printe
208 "call" for "bc", "return" for "br", "j
209 "int" for "bci", "iret" for "bri", "sy
210 "async" for "by", "hw int" for "bcyi",
211 "tr end" for "bE", "vmentry" for "bcg"
212 However the "x", "D" and "t" flags wil
213 cases e.g. "jcc (xD)" for a condit
214 with interrupts disabled. Note, interr
215 whereas interrupts becoming enabled is
216
217 The callindent field is synthesized an
218 Instruction Trace decoding. For calls
219 name of the symbol indented with space
220
221 When doing instruction trace decoding,
222 instruction bytes, disassembled instru
223 and the instruction length of the curr
224
225 The synth field is used by synthesized
226 Instruction Trace decoding.
227
228 The ipc (instructions per cycle) field
229 Instruction Trace decoding.
230
231 The machine_pid and vcpu fields are de
232 perf inject to insert a perf.data file
233 a perf.data file recorded on the host
234
235 The cgroup fields requires sample havi
236 when "--all-cgroups" option is passed
237
238 Finally, a user may not set fields to
239 i.e., -F "" is not allowed.
240
241 The brstack output includes branch rel
242 /v/v/v/v/cycles syntax in the followin
243 FROM: branch source instruction
244 TO : branch target instruction
245 M/P/-: M=branch target mispredicted or
246 X/- : X=branch inside a transactional
247 A/- : A=TSX abort entry, -=not aborted
248 cycles
249
250 The brstacksym is identical to brstack
251
252 When brstackinsn is specified the full
253 is printed. This is the full execution
254 sample was recorded with perf record -
255
256 Use brstackinsnlen to print the brstac
257 can’t know the next sequential instr
258 you calculate that based on its length
259
260 brstackdisasm acts like brstackinsn, b
261 perf is built with the capstone librar
262
263 The brstackoff field will print an off
264
265 With the metric option perf script can
266 sampling periods, similar to perf stat
267 specifying a group with multiple event
268 for perf record. perf will sample on t
269 print computed metrics for all the eve
270 that the metric computed is averaged o
271 period (since the last sample), not ju
272
273 For sample events it's possible to dis
274 following letters are displayed for ea
275
276 PERF_RECORD_MISC_KERNEL
277 PERF_RECORD_MISC_USER
278 PERF_RECORD_MISC_HYPERVISOR
279 PERF_RECORD_MISC_GUEST_KERNEL
280 PERF_RECORD_MISC_GUEST_USER
281 PERF_RECORD_MISC_MMAP_DATA*
282 PERF_RECORD_MISC_COMM_EXEC
283 PERF_RECORD_MISC_SWITCH_OUT
284 PERF_RECORD_MISC_SWITCH_OUT_PREEMPT
285
286 $ perf script -F +misc ...
287 sched-messaging 1414 K 28690.6
288 sched-messaging 1407 U 28690.6
289 sched-messaging 1414 K 28690.6
290 misc field ___________/
291
292 -k::
293 --vmlinux=<file>::
294 vmlinux pathname
295
296 --kallsyms=<file>::
297 kallsyms pathname
298
299 --symfs=<directory>::
300 Look for files with symbols relative t
301
302 -G::
303 --hide-call-graph::
304 When printing symbols do not display c
305
306 --stop-bt::
307 Stop display of callgraph at these sym
308
309 -C::
310 --cpu:: Only report samples for the list of CP
311 be provided as a comma-separated list
312 CPUs are specified with -: 0-2. Defaul
313 CPUs.
314
315 -c::
316 --comms=::
317 Only display events for these comms. C
318 file://filename entries.
319
320 --pid=::
321 Only show events for given process ID
322
323 --tid=::
324 Only show events for given thread ID (
325
326 -I::
327 --show-info::
328 Display extended information about the
329 information which may be very large an
330 It currently includes: cpu and numa to
331 It can only be used with the perf scri
332
333 --show-kernel-path::
334 Try to resolve the path of [kernel.kal
335
336 --show-task-events
337 Display task related events (e.g. FORK
338
339 --show-mmap-events
340 Display mmap related events (e.g. MMAP
341
342 --show-namespace-events
343 Display namespace events i.e. events o
344
345 --show-switch-events
346 Display context switch events i.e. eve
347 PERF_RECORD_SWITCH_CPU_WIDE.
348
349 --show-lost-events
350 Display lost events i.e. events of typ
351
352 --show-round-events
353 Display finished round events i.e. eve
354
355 --show-bpf-events
356 Display bpf events i.e. events of type
357
358 --show-cgroup-events
359 Display cgroup events i.e. events of t
360
361 --show-text-poke-events
362 Display text poke events i.e. events o
363 PERF_RECORD_KSYMBOL.
364
365 --demangle::
366 Demangle symbol names to human readabl
367 disable with --no-demangle.
368
369 --demangle-kernel::
370 Demangle kernel symbol names to human
371
372 --addr2line=<path>::
373 Path to addr2line binary.
374
375 --header
376 Show perf.data header.
377
378 --header-only
379 Show only perf.data header.
380
381 --itrace::
382 Options for decoding instruction traci
383
384 include::itrace.txt[]
385
386 To disable decoding entirely, use --no
387
388 --full-source-path::
389 Show the full path for source files fo
390
391 --max-stack::
392 Set the stack depth limit when parsing
393 beyond the specified depth will be ign
394 between information loss and faster pr
395 workloads that can have a very long ca
396 Note that when using the --itrace opti
397 will override this value if the synthe
398
399 Default: 127
400
401 --ns::
402 Use 9 decimal places when displaying t
403
404 -f::
405 --force::
406 Don't do ownership validation.
407
408 --time::
409 Only analyze samples within given time
410 have the format seconds.nanoseconds. I
411 string is ',x.y') then analysis starts
412 stop time is not given (i.e. time stri
413 to end of file. Multiple ranges can be
414 requires the argument to be quoted e.g
415
416 Also support time percent with multipl
417 'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
418
419 For example:
420 Select the second 10% time slice:
421 perf script --time 10%/2
422
423 Select from 0% to 10% time slice:
424 perf script --time 0%-10%
425
426 Select the first and second 10% time s
427 perf script --time 10%/1,10%/2
428
429 Select from 0% to 10% and 30% to 40% s
430 perf script --time 0%-10%,30%-40%
431
432 --max-blocks::
433 Set the maximum number of program bloc
434 each sample.
435
436 --reltime::
437 Print time stamps relative to trace st
438
439 --deltatime::
440 Print time stamps relative to previous
441
442 --per-event-dump::
443 Create per event files with a "perf.da
444 printing to stdout, useful, for instan
445
446 --inline::
447 If a callgraph address belongs to an i
448 will be printed. Each entry has functi
449 default, disable with --no-inline.
450
451 --insn-trace[=<raw|disasm>]::
452 Show instruction stream in bytes (raw)
453 for intel_pt traces. The default is 'r
454 'raw' with --xed to show disassembly d
455
456 --xed::
457 Run xed disassembler on output. Requir
458
459 -S::
460 --symbols=symbol[,symbol...]::
461 Only consider the listed symbols. Symb
462 but they may also be hexadecimal addre
463
464 The hexadecimal address may be the sta
465 any other address to filter the trace
466
467 For example, to select the symbol nopl
468 perf script --symbols=noploop,0x4007a0
469
470 Support filtering trace records by sym
471 symbol, any hexadecimal address and ad
472
473 The comparison order is:
474
475 1. symbol name comparison
476 2. symbol start address comparison.
477 3. any hexadecimal address comparison.
478 4. address range comparison (see --add
479
480 --addr-range::
481 Use with -S or --symbols to list traced
482
483 For example, to list the traced records
484 [0x4007a0, 0x0x4007a9]:
485 perf script -S 0x4007a0 --addr-range 10
486
487 --dsos=::
488 Only consider symbols in these DSOs.
489
490 --call-trace::
491 Show call stream for intel_pt traces.
492 can be filtered with -C.
493
494 --call-ret-trace::
495 Show call and return stream for intel_
496
497 --graph-function::
498 For itrace only show specified functio
499 itrace. Multiple functions can be sepa
500
501 --switch-on EVENT_NAME::
502 Only consider events after this event
503
504 --switch-off EVENT_NAME::
505 Stop considering events after this eve
506
507 --show-on-off-events::
508 Show the --switch-on/off events too.
509
510 --stitch-lbr::
511 Show callgraph with stitched LBRs, whi
512 callgraph. The perf.data file must hav
513 perf record --call-graph lbr.
514 Disabled by default. In common cases w
515 it can recreate better call stacks tha
516 output. But this approach is not foolp
517 where it creates incorrect call stacks
518 The known limitations include exceptio
519 setjmp/longjmp will have calls/returns
520
521 :GMEXAMPLECMD: script
522 :GMEXAMPLESUBCMD:
523 include::guest-files.txt[]
524
525 SEE ALSO
526 --------
527 linkperf:perf-record[1], linkperf:perf-script-
528 linkperf:perf-script-python[1], linkperf:perf-
529 linkperf:perf-dlfilter[1]
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.