Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 1 | perf-trace(1) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | perf-trace - strace inspired tool |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [verse] |
| 11 | 'perf trace' |
David Ahern | 5e2485b | 2013-09-28 13:13:01 -0600 | [diff] [blame] | 12 | 'perf trace record' |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
| 16 | This command will show the events associated with the target, initially |
| 17 | syscalls, but other system events like pagefaults, task lifetime events, |
| 18 | scheduling events, etc. |
| 19 | |
David Ahern | 5e2485b | 2013-09-28 13:13:01 -0600 | [diff] [blame] | 20 | This is a live mode tool in addition to working with perf.data files like |
| 21 | the other perf tools. Files can be generated using the 'perf record' command |
| 22 | but the session needs to include the raw_syscalls events (-e 'raw_syscalls:*'). |
Masanari Iida | 96355f2 | 2014-09-10 00:18:50 +0900 | [diff] [blame] | 23 | Alternatively, 'perf trace record' can be used as a shortcut to |
David Ahern | 5e2485b | 2013-09-28 13:13:01 -0600 | [diff] [blame] | 24 | automatically include the raw_syscalls events when writing events to a file. |
| 25 | |
| 26 | The following options apply to perf trace; options to perf trace record are |
| 27 | found in the perf record man page. |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 28 | |
| 29 | OPTIONS |
| 30 | ------- |
| 31 | |
David Ahern | ac9be8e | 2013-08-20 11:15:45 -0600 | [diff] [blame] | 32 | -a:: |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 33 | --all-cpus:: |
| 34 | System-wide collection from all CPUs. |
| 35 | |
Arnaldo Carvalho de Melo | 2ae3a31 | 2013-08-09 12:28:31 -0300 | [diff] [blame] | 36 | -e:: |
| 37 | --expr:: |
Arnaldo Carvalho de Melo | d303e85 | 2015-04-23 12:02:07 -0300 | [diff] [blame] | 38 | List of syscalls to show, currently only syscall names. |
Arnaldo Carvalho de Melo | b059efd | 2013-08-21 12:56:21 -0300 | [diff] [blame] | 39 | Prefixing with ! shows all syscalls but the ones specified. You may |
| 40 | need to escape it. |
Arnaldo Carvalho de Melo | 2ae3a31 | 2013-08-09 12:28:31 -0300 | [diff] [blame] | 41 | |
Arnaldo Carvalho de Melo | c24ff99 | 2013-08-19 12:01:10 -0300 | [diff] [blame] | 42 | -o:: |
| 43 | --output=:: |
| 44 | Output file name. |
| 45 | |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 46 | -p:: |
| 47 | --pid=:: |
| 48 | Record events on existing process ID (comma separated list). |
| 49 | |
David Ahern | ac9be8e | 2013-08-20 11:15:45 -0600 | [diff] [blame] | 50 | -t:: |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 51 | --tid=:: |
| 52 | Record events on existing thread ID (comma separated list). |
| 53 | |
David Ahern | ac9be8e | 2013-08-20 11:15:45 -0600 | [diff] [blame] | 54 | -u:: |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 55 | --uid=:: |
| 56 | Record events in threads owned by uid. Name or number. |
| 57 | |
Arnaldo Carvalho de Melo | f078c38 | 2015-02-21 11:36:52 -0800 | [diff] [blame] | 58 | --filter-pids=:: |
| 59 | Filter out events for these pids and for 'trace' itself (comma separated list). |
| 60 | |
Arnaldo Carvalho de Melo | 7c304ee0 | 2013-08-22 16:49:54 -0300 | [diff] [blame] | 61 | -v:: |
| 62 | --verbose=:: |
| 63 | Verbosity level. |
| 64 | |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 65 | --no-inherit:: |
| 66 | Child tasks do not inherit counters. |
| 67 | |
David Ahern | ac9be8e | 2013-08-20 11:15:45 -0600 | [diff] [blame] | 68 | -m:: |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 69 | --mmap-pages=:: |
Jiri Olsa | 27050f5 | 2013-09-01 12:36:13 +0200 | [diff] [blame] | 70 | 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 Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 73 | |
David Ahern | ac9be8e | 2013-08-20 11:15:45 -0600 | [diff] [blame] | 74 | -C:: |
Arnaldo Carvalho de Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 75 | --cpu:: |
| 76 | Collect samples only on the list of CPUs provided. Multiple CPUs can be provided as a |
| 77 | comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. |
| 78 | In per-thread mode with inheritance mode on (default), Events are captured only when |
| 79 | the thread executes on the designated CPUs. Default is to monitor all CPUs. |
| 80 | |
Arnaldo Carvalho de Melo | ae9ed03 | 2012-10-08 09:56:00 -0300 | [diff] [blame] | 81 | --duration: |
| 82 | Show only events that had a duration greater than N.M ms. |
| 83 | |
Arnaldo Carvalho de Melo | 1302d88 | 2012-10-17 17:13:12 -0300 | [diff] [blame] | 84 | --sched: |
| 85 | Accrue thread runtime and provide a summary at the end of the session. |
| 86 | |
David Ahern | 6810fc9 | 2013-08-28 22:29:52 -0600 | [diff] [blame] | 87 | -i |
| 88 | --input |
| 89 | Process events from a given perf data file. |
| 90 | |
David Ahern | 4bb0919 | 2013-09-04 12:37:43 -0600 | [diff] [blame] | 91 | -T |
| 92 | --time |
| 93 | Print full timestamp rather time relative to first sample. |
| 94 | |
Arnaldo Carvalho de Melo | 50c95cb | 2013-09-12 12:35:21 -0300 | [diff] [blame] | 95 | --comm:: |
| 96 | Show process COMM right beside its ID, on by default, disable with --no-comm. |
| 97 | |
David Ahern | fd2eaba | 2013-11-12 09:31:15 -0700 | [diff] [blame] | 98 | -s:: |
David Ahern | bf2575c | 2013-10-08 21:26:53 -0600 | [diff] [blame] | 99 | --summary:: |
David Ahern | fd2eaba | 2013-11-12 09:31:15 -0700 | [diff] [blame] | 100 | 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 Ahern | bf2575c | 2013-10-08 21:26:53 -0600 | [diff] [blame] | 107 | |
Arnaldo Carvalho de Melo | c522739 | 2013-09-27 18:06:19 -0300 | [diff] [blame] | 108 | --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 Fomichev | 598d02c | 2014-06-26 20:14:25 +0400 | [diff] [blame] | 112 | -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 Fomichev | e281a96 | 2014-06-26 20:14:28 +0400 | [diff] [blame] | 117 | --syscalls:: |
| 118 | Trace system calls. This options is enabled by default. |
| 119 | |
Arnaldo Carvalho de Melo | 77c9258 | 2015-02-21 11:49:10 -0800 | [diff] [blame] | 120 | --event:: |
| 121 | Trace other events, see 'perf list' for a complete list. |
| 122 | |
Kan Liang | 9d9cad7 | 2015-06-17 09:51:11 -0400 | [diff] [blame] | 123 | --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 Fomichev | 598d02c | 2014-06-26 20:14:25 +0400 | [diff] [blame] | 128 | PAGEFAULTS |
| 129 | ---------- |
| 130 | |
| 131 | When 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 | |
| 142 | For symbols resolution you may need to install debugging symbols. |
| 143 | |
| 144 | Please be aware that duration is currently always 0 and doesn't reflect actual |
| 145 | time it took for fault to be handled! |
| 146 | |
| 147 | When --verbose specified, perf trace tries to print all available information |
| 148 | for both IP and fault address in the form of dso@symbol+offset. |
| 149 | |
| 150 | EXAMPLES |
| 151 | -------- |
| 152 | |
Stanislav Fomichev | e281a96 | 2014-06-26 20:14:28 +0400 | [diff] [blame] | 153 | Trace only major pagefaults: |
| 154 | |
| 155 | $ perf trace --no-syscalls -F |
| 156 | |
Stanislav Fomichev | 598d02c | 2014-06-26 20:14:25 +0400 | [diff] [blame] | 157 | Trace 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 Melo | 514f1c6 | 2012-09-26 20:05:56 -0300 | [diff] [blame] | 166 | SEE ALSO |
| 167 | -------- |
| 168 | linkperf:perf-record[1], linkperf:perf-script[1] |