blob: 13293de8869fe932c9610f3a3c5612c838a65bc4 [file] [log] [blame]
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -03001perf-trace(1)
2=============
3
4NAME
5----
6perf-trace - strace inspired tool
7
8SYNOPSIS
9--------
10[verse]
11'perf trace'
David Ahern5e2485b2013-09-28 13:13:01 -060012'perf trace record'
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030013
14DESCRIPTION
15-----------
16This command will show the events associated with the target, initially
17syscalls, but other system events like pagefaults, task lifetime events,
18scheduling events, etc.
19
David Ahern5e2485b2013-09-28 13:13:01 -060020This is a live mode tool in addition to working with perf.data files like
21the other perf tools. Files can be generated using the 'perf record' command
22but the session needs to include the raw_syscalls events (-e 'raw_syscalls:*').
Masanari Iida96355f22014-09-10 00:18:50 +090023Alternatively, 'perf trace record' can be used as a shortcut to
David Ahern5e2485b2013-09-28 13:13:01 -060024automatically include the raw_syscalls events when writing events to a file.
25
26The following options apply to perf trace; options to perf trace record are
27found in the perf record man page.
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030028
29OPTIONS
30-------
31
David Ahernac9be8e2013-08-20 11:15:45 -060032-a::
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030033--all-cpus::
34 System-wide collection from all CPUs.
35
Arnaldo Carvalho de Melo2ae3a312013-08-09 12:28:31 -030036-e::
37--expr::
Arnaldo Carvalho de Melod303e852015-04-23 12:02:07 -030038 List of syscalls to show, currently only syscall names.
Arnaldo Carvalho de Melob059efd2013-08-21 12:56:21 -030039 Prefixing with ! shows all syscalls but the ones specified. You may
40 need to escape it.
Arnaldo Carvalho de Melo2ae3a312013-08-09 12:28:31 -030041
Arnaldo Carvalho de Meloc24ff992013-08-19 12:01:10 -030042-o::
43--output=::
44 Output file name.
45
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030046-p::
47--pid=::
48 Record events on existing process ID (comma separated list).
49
David Ahernac9be8e2013-08-20 11:15:45 -060050-t::
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030051--tid=::
52 Record events on existing thread ID (comma separated list).
53
David Ahernac9be8e2013-08-20 11:15:45 -060054-u::
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030055--uid=::
56 Record events in threads owned by uid. Name or number.
57
Arnaldo Carvalho de Melof078c382015-02-21 11:36:52 -080058--filter-pids=::
59 Filter out events for these pids and for 'trace' itself (comma separated list).
60
Arnaldo Carvalho de Melo7c304ee02013-08-22 16:49:54 -030061-v::
62--verbose=::
63 Verbosity level.
64
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030065--no-inherit::
66 Child tasks do not inherit counters.
67
David Ahernac9be8e2013-08-20 11:15:45 -060068-m::
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030069--mmap-pages=::
Jiri Olsa27050f52013-09-01 12:36:13 +020070 Number of mmap data pages (must be a power of two) or size
71 specification with appended unit character - B/K/M/G. The
72 size is rounded up to have nearest pages power of two value.
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030073
David Ahernac9be8e2013-08-20 11:15:45 -060074-C::
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -030075--cpu::
76Collect samples only on the list of CPUs provided. Multiple CPUs can be provided as a
77comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
78In per-thread mode with inheritance mode on (default), Events are captured only when
79the thread executes on the designated CPUs. Default is to monitor all CPUs.
80
Arnaldo Carvalho de Meloae9ed032012-10-08 09:56:00 -030081--duration:
82 Show only events that had a duration greater than N.M ms.
83
Arnaldo Carvalho de Melo1302d882012-10-17 17:13:12 -030084--sched:
85 Accrue thread runtime and provide a summary at the end of the session.
86
David Ahern6810fc92013-08-28 22:29:52 -060087-i
88--input
89 Process events from a given perf data file.
90
David Ahern4bb09192013-09-04 12:37:43 -060091-T
92--time
93 Print full timestamp rather time relative to first sample.
94
Arnaldo Carvalho de Melo50c95cb2013-09-12 12:35:21 -030095--comm::
96 Show process COMM right beside its ID, on by default, disable with --no-comm.
97
David Ahernfd2eaba2013-11-12 09:31:15 -070098-s::
David Ahernbf2575c2013-10-08 21:26:53 -060099--summary::
David Ahernfd2eaba2013-11-12 09:31:15 -0700100 Show only a summary of syscalls by thread with min, max, and average times
101 (in msec) and relative stddev.
102
103-S::
104--with-summary::
105 Show all syscalls followed by a summary by thread with min, max, and
106 average times (in msec) and relative stddev.
David Ahernbf2575c2013-10-08 21:26:53 -0600107
Arnaldo Carvalho de Meloc5227392013-09-27 18:06:19 -0300108--tool_stats::
109 Show tool stats such as number of times fd->pathname was discovered thru
110 hooking the open syscall return + vfs_getname or via reading /proc/pid/fd, etc.
111
Stanislav Fomichev598d02c2014-06-26 20:14:25 +0400112-F=[all|min|maj]::
113--pf=[all|min|maj]::
114 Trace pagefaults. Optionally, you can specify whether you want minor,
115 major or all pagefaults. Default value is maj.
116
Stanislav Fomicheve281a962014-06-26 20:14:28 +0400117--syscalls::
118 Trace system calls. This options is enabled by default.
119
Arnaldo Carvalho de Melo77c92582015-02-21 11:49:10 -0800120--event::
121 Trace other events, see 'perf list' for a complete list.
122
Kan Liang9d9cad72015-06-17 09:51:11 -0400123--proc-map-timeout::
124 When processing pre-existing threads /proc/XXX/mmap, it may take a long time,
125 because the file may be huge. A time out is needed in such cases.
126 This option sets the time out limit. The default value is 500 ms.
127
Stanislav Fomichev598d02c2014-06-26 20:14:25 +0400128PAGEFAULTS
129----------
130
131When tracing pagefaults, the format of the trace is as follows:
132
133<min|maj>fault [<ip.symbol>+<ip.offset>] => <addr.dso@addr.offset> (<map type><addr level>).
134
135- min/maj indicates whether fault event is minor or major;
136- ip.symbol shows symbol for instruction pointer (the code that generated the
137 fault); if no debug symbols available, perf trace will print raw IP;
138- addr.dso shows DSO for the faulted address;
139- map type is either 'd' for non-executable maps or 'x' for executable maps;
140- addr level is either 'k' for kernel dso or '.' for user dso.
141
142For symbols resolution you may need to install debugging symbols.
143
144Please be aware that duration is currently always 0 and doesn't reflect actual
145time it took for fault to be handled!
146
147When --verbose specified, perf trace tries to print all available information
148for both IP and fault address in the form of dso@symbol+offset.
149
150EXAMPLES
151--------
152
Stanislav Fomicheve281a962014-06-26 20:14:28 +0400153Trace only major pagefaults:
154
155 $ perf trace --no-syscalls -F
156
Stanislav Fomichev598d02c2014-06-26 20:14:25 +0400157Trace syscalls, major and minor pagefaults:
158
159 $ perf trace -F all
160
161 1416.547 ( 0.000 ms): python/20235 majfault [CRYPTO_push_info_+0x0] => /lib/x86_64-linux-gnu/libcrypto.so.1.0.0@0x61be0 (x.)
162
163 As you can see, there was major pagefault in python process, from
164 CRYPTO_push_info_ routine which faulted somewhere in libcrypto.so.
165
Arnaldo Carvalho de Melo514f1c62012-09-26 20:05:56 -0300166SEE ALSO
167--------
168linkperf:perf-record[1], linkperf:perf-script[1]