perf/Documentation/perf-script.txt

1 perf-script(1)
5 ----
6 perf-script - Read perf.data (created by perf record) and display trace output
9 --------
12 'perf script' [<options>] record <script> [<record-options>] <command>
13 'perf script' [<options>] report <script> [script-args]
14 'perf script' [<options>] <script> <required-script-args> [<record-options>] <command>
15 'perf script' [<options>] <top-script> [script-args]
18 -----------
26   You can also run a set of pre-canned scripts that aggregate and
28   available via 'perf script -l').  The following variants allow you to
29   record and run those scripts:
33   output of 'perf script --list' i.e. the actual script name minus any
35   recorded using the -a (system-wide) 'perf record' option.
37   'perf script report <script> [args]' to run and display the results
39   script --list' i.e. the actual script name minus any language
40   extension.  The perf.data output from a previous run of 'perf script
45   'perf script <script> <required-script-args> <command>' to both
46   record the events required for <script> and to run the <script>
47   using 'live-mode' i.e. without writing anything to disk.  <script>
48   is the name displayed in the output of 'perf script --list' i.e. the
50   not specified, the events are recorded using the -a (system-wide)
56   piped to the stdin of the report script, using the '-o -' and '-i -'
59   'perf script <top-script>' to both record the events required for
60   <top-script> and to run the <top-script> using 'live-mode'
61   i.e. without writing anything to disk.  <top-script> is the name
62   displayed in the output of 'perf script --list' i.e. the actual
63   script name minus any language extension; a <top-script> is defined
66   [<record-options>] can be passed to the record steps of 'perf script
67   record' and 'live-mode' variants; this isn't possible however for
68   <top-script> 'live-mode' or 'perf script report' variants.
70   See the 'SEE ALSO' section for links to language-specific
71   information on how to write and run your own trace scripts.
74 -------
78 -D::
79 --dump-raw-trace=::
82 --dump-unsorted-raw-trace=::
83         Same as --dump-raw-trace but not sorted in time order.
85 -L::
86 --Latency=::
89 -l::
90 --list=::
93 -s ['lang']::
94 --script=::
99 -g::
100 --gen-script=::
101         Generate perf-script.[ext] starter script for given language,
104 --dlfilter=<file>::
106 	Refer linkperf:perf-dlfilter[1]
108 --dlarg=<arg>::
109 	Pass 'arg' as an argument to the dlfilter. --dlarg may be repeated
112 --list-dlfilters::
113         Display a list of available dlfilters. Use with option -v (must come
114         before option --list-dlfilters) to show long descriptions.
116 -a::
117         Force system-wide collection.  Scripts run without a <command>
118         normally use -a by default, while scripts run with a <command>
119         normally don't - this option allows the latter to be run in
120         system-wide mode.
122 -i::
123 --input=::
126 -d::
127 --debug-mode::
130 -F::
131 --fields::
133         comm, tid, pid, time, cpu, event, trace, ip, sym, dso, dsoff, addr, symoff,
134         srcline, period, iregs, uregs, brstack, brstacksym, flags, bpf-output,
140         e.g., -F sw:comm,tid,time,ip,sym  and -F trace:time,cpu,trace
142 		perf script -F <fields>
146 		perf script -F trace:<fields> -F sw:<fields> -F hw:<fields>
154 		-F -cpu,+insn
162 		-F trace: -F comm,tid,time,ip,sym
164 	The first -F suppresses trace events (field list is ""), but then the
165 	second invocation sets the fields to comm,tid,time,ip,sym. In this case a
172 		-F comm,tid,time,ip,sym -F trace:
174 	The first -F sets the fields for all events and the second -F
181 		-Fsw:-cpu,-period
189 		$ perf script -F comm,tid,trace
196         perf script -v -F sw:comm,tid,trace
199 	At this point usage is displayed, and perf-script exits.
204 	transaction abort, trace begin, trace end, in transaction, VM-Entry,
205 	VM-Exit, interrupt disabled and interrupt disable toggle respectively.
232 	a perf.data file recorded on the host at the same time.
235 	when "--all-cgroups" option is passed to 'perf record'.
238 	i.e., -F "" is not allowed.
244 …M/P/-: M=branch target mispredicted or branch direction was mispredicted, P=target predicted or di…
245 	X/- : X=branch inside a transactional region, -=not in transaction region or not supported
246 	A/- : A=TSX abort entry, -=not aborted region or not supported
253 	sample was recorded with perf record -b or -j any.
269 	For sample events it's possible to display misc field with -F +misc option,
282 	  $ perf script -F +misc ...
283 	   sched-messaging  1414 K     28690.636582:       4590 cycles ...
284 	   sched-messaging  1407 U     28690.636600:     325620 cycles ...
285 	   sched-messaging  1414 K     28690.636608:      19473 cycles ...
288 -k::
289 --vmlinux=<file>::
292 --kallsyms=<file>::
295 --symfs=<directory>::
298 -G::
299 --hide-call-graph::
302 --stop-bt::
305 -C::
306 --cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can
307 	be provided as a comma-separated list with no space: 0,1. Ranges of
308 	CPUs are specified with -: 0-2. Default is to report samples on all
311 -c::
312 --comms=::
316 --pid=::
319 --tid=::
322 -I::
323 --show-info::
329 --show-kernel-path::
332 --show-task-events
335 --show-mmap-events
338 --show-namespace-events
341 --show-switch-events
345 --show-lost-events
348 --show-round-events
351 --show-bpf-events
354 --show-cgroup-events
357 --show-text-poke-events
361 --demangle::
363 	disable with --no-demangle.
365 --demangle-kernel::
368 --header
371 --header-only
374 --itrace::
379 	To disable decoding entirely, use --no-itrace.
381 --full-source-path::
384 --max-stack::
386         beyond the specified depth will be ignored. This is a trade-off
389         Note that when using the --itrace option the synthesized callchain size
394 --ns::
395 	Use 9 decimal places when displaying time (i.e. show the nanoseconds)
397 -f::
398 --force::
401 --time::
402 	Only analyze samples within given time window: <start>,<stop>. Times
403 	have the format seconds.nanoseconds. If start is not given (i.e. time
405 	stop time is not given (i.e. time string is 'x.y,') then analysis goes
407 	requires the argument to be quoted e.g. --time "1234.567,1234.789 1235,"
409 	Also support time percent with multiple time ranges. Time string is
410 	'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
413 	Select the second 10% time slice:
414 	perf script --time 10%/2
416 	Select from 0% to 10% time slice:
417 	perf script --time 0%-10%
419 	Select the first and second 10% time slices:
420 	perf script --time 10%/1,10%/2
423 	perf script --time 0%-10%,30%-40%
425 --max-blocks::
429 --reltime::
430 	Print time stamps relative to trace start.
432 --deltatime::
433 	Print time stamps relative to previous event.
435 --per-event-dump::
439 --inline::
442 	default, disable with --no-inline.
444 --insn-trace::
445 	Show instruction stream for intel_pt traces. Combine with --xed to
448 --xed::
449 	Run xed disassembler on output. Requires installing the xed disassembler.
451 -S::
452 --symbols=symbol[,symbol...]::
460 	perf script --symbols=noploop,0x4007a0
470 	4. address range comparison (see --addr-range).
472 --addr-range::
473        Use with -S or --symbols to list traced records within address range.
477        perf script -S 0x4007a0 --addr-range 10
479 --dsos=::
482 --call-trace::
484 	can be filtered with -C.
486 --call-ret-trace::
489 --graph-function::
493 --switch-on EVENT_NAME::
496 --switch-off EVENT_NAME::
499 --show-on-off-events::
500 	Show the --switch-on/off events too.
502 --stitch-lbr::
505 	perf record --call-graph lbr.
515 include::guest-files.txt[]
518 --------
519 linkperf:perf-record[1], linkperf:perf-script-perl[1],
520 linkperf:perf-script-python[1], linkperf:perf-intel-pt[1],
521 linkperf:perf-dlfilter[1]