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,
141         e.g., -F sw:comm,tid,time,ip,sym  and -F trace:time,cpu,trace
143 		perf script -F <fields>
147 		perf script -F trace:<fields> -F sw:<fields> -F hw:<fields>
155 		-F -cpu,+insn
163 		-F trace: -F comm,tid,time,ip,sym
165 	The first -F suppresses trace events (field list is ""), but then the
166 	second invocation sets the fields to comm,tid,time,ip,sym. In this case a
173 		-F comm,tid,time,ip,sym -F trace:
175 	The first -F sets the fields for all events and the second -F
182 		-Fsw:-cpu,-period
190 		$ perf script -F comm,tid,trace
197         perf script -v -F sw:comm,tid,trace
200 	At this point usage is displayed, and perf-script exits.
205 	transaction abort, trace begin, trace end, in transaction, VM-Entry,
206 	VM-Exit, interrupt disabled and interrupt disable toggle respectively.
233 	a perf.data file recorded on the host at the same time.
236 	when "--all-cgroups" option is passed to 'perf record'.
239 	i.e., -F "" is not allowed.
245 …M/P/-: M=branch target mispredicted or branch direction was mispredicted, P=target predicted or di…
246 	X/- : X=branch inside a transactional region, -=not in transaction region or not supported
247 	A/- : A=TSX abort entry, -=not aborted region or not supported
254 	sample was recorded with perf record -b or -j any.
273 	For sample events it's possible to display misc field with -F +misc option,
286 	  $ perf script -F +misc ...
287 	   sched-messaging  1414 K     28690.636582:       4590 cycles ...
288 	   sched-messaging  1407 U     28690.636600:     325620 cycles ...
289 	   sched-messaging  1414 K     28690.636608:      19473 cycles ...
292 -k::
293 --vmlinux=<file>::
296 --kallsyms=<file>::
299 --symfs=<directory>::
302 -G::
303 --hide-call-graph::
306 --stop-bt::
309 -C::
310 --cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can
311 	be provided as a comma-separated list with no space: 0,1. Ranges of
312 	CPUs are specified with -: 0-2. Default is to report samples on all
315 -c::
316 --comms=::
320 --pid=::
323 --tid=::
326 -I::
327 --show-info::
333 --show-kernel-path::
336 --show-task-events
339 --show-mmap-events
342 --show-namespace-events
345 --show-switch-events
349 --show-lost-events
352 --show-round-events
355 --show-bpf-events
358 --show-cgroup-events
361 --show-text-poke-events
365 --demangle::
367 	disable with --no-demangle.
369 --demangle-kernel::
372 --addr2line=<path>::
375 --header
378 --header-only
381 --itrace::
386 	To disable decoding entirely, use --no-itrace.
388 --full-source-path::
391 --max-stack::
393         beyond the specified depth will be ignored. This is a trade-off
396         Note that when using the --itrace option the synthesized callchain size
401 --ns::
402 	Use 9 decimal places when displaying time (i.e. show the nanoseconds)
404 -f::
405 --force::
408 --time::
409 	Only analyze samples within given time window: <start>,<stop>. Times
410 	have the format seconds.nanoseconds. If start is not given (i.e. time
412 	stop time is not given (i.e. time string is 'x.y,') then analysis goes
414 	requires the argument to be quoted e.g. --time "1234.567,1234.789 1235,"
416 	Also support time percent with multiple time ranges. Time string is
417 	'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
420 	Select the second 10% time slice:
421 	perf script --time 10%/2
423 	Select from 0% to 10% time slice:
424 	perf script --time 0%-10%
426 	Select the first and second 10% time slices:
427 	perf script --time 10%/1,10%/2
430 	perf script --time 0%-10%,30%-40%
432 --max-blocks::
436 --reltime::
437 	Print time stamps relative to trace start.
439 --deltatime::
440 	Print time stamps relative to previous event.
442 --per-event-dump::
446 --inline::
449 	default, disable with --no-inline.
451 --insn-trace[=<raw|disasm>]::
454 	'raw' with --xed to show disassembly done by xed.
456 --xed::
457 	Run xed disassembler on output. Requires installing the xed disassembler.
459 -S::
460 --symbols=symbol[,symbol...]::
468 	perf script --symbols=noploop,0x4007a0
478 	4. address range comparison (see --addr-range).
480 --addr-range::
481        Use with -S or --symbols to list traced records within address range.
485        perf script -S 0x4007a0 --addr-range 10
487 --dsos=::
490 --call-trace::
492 	can be filtered with -C.
494 --call-ret-trace::
497 --graph-function::
501 --switch-on EVENT_NAME::
504 --switch-off EVENT_NAME::
507 --show-on-off-events::
508 	Show the --switch-on/off events too.
510 --stitch-lbr::
513 	perf record --call-graph lbr.
523 include::guest-files.txt[]
526 --------
527 linkperf:perf-record[1], linkperf:perf-script-perl[1],
528 linkperf:perf-script-python[1], linkperf:perf-intel-pt[1],
529 linkperf:perf-dlfilter[1]