tools/perf/Documentation/perf-lock.txt

   1 perf-lock(1)
   2 ============
   3
   4 NAME
   5 ----
   6 perf-lock - Analyze lock events
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'perf lock' {record|report|script|info|contention}
  12
  13 DESCRIPTION
  14 -----------
  15 You can analyze various lock behaviours
  16 and statistics with this 'perf lock' command.
  17
  18   'perf lock record <command>' records lock events
  19   between start and end <command>. And this command
  20   produces the file "perf.data" which contains tracing
  21   results of lock events.
  22
  23   'perf lock report' reports statistical data.
  24
  25   'perf lock script' shows raw lock events.
  26
  27   'perf lock info' shows metadata like threads or addresses
  28   of lock instances.
  29
  30   'perf lock contention' shows contention statistics.
  31
  32 COMMON OPTIONS
  33 --------------
  34
  35 -i::
  36 --input=<file>::
  37         Input file name. (default: perf.data unless stdin is a fifo)
  38
  39 -v::
  40 --verbose::
  41         Be more verbose (show symbol address, etc).
  42
  43 -q::
  44 --quiet::
  45         Do not show any warnings or messages. (Suppress -v)
  46
  47 -D::
  48 --dump-raw-trace::
  49         Dump raw trace in ASCII.
  50
  51 -f::
  52 --force::
  53         Don't complain, do it.
  54
  55 --vmlinux=<file>::
  56         vmlinux pathname
  57
  58 --kallsyms=<file>::
  59         kallsyms pathname
  60
  61
  62 REPORT OPTIONS
  63 --------------
  64
  65 -k::
  66 --key=<value>::
  67         Sorting key. Possible values: acquired (default), contended,
  68         avg_wait, wait_total, wait_max, wait_min.
  69
  70 -F::
  71 --field=<value>::
  72         Output fields. By default it shows all the fields but users can
  73         customize that using this.  Possible values: acquired, contended,
  74         avg_wait, wait_total, wait_max, wait_min.
  75
  76 -c::
  77 --combine-locks::
  78         Merge lock instances in the same class (based on name).
  79
  80 -t::
  81 --threads::
  82     The -t option is to show per-thread lock stat like below:
  83
  84       $ perf lock report -t -F acquired,contended,avg_wait
  85
  86                     Name   acquired  contended   avg wait (ns)
  87
  88                     perf     240569          9            5784
  89                  swapper     106610         19             543
  90                   :15789      17370          2           14538
  91             ContainerMgr       8981          6             874
  92                    sleep       5275          1           11281
  93          ContainerThread       4416          4             944
  94          RootPressureThr       3215          5            1215
  95              rcu_preempt       2954          0               0
  96             ContainerMgr       2560          0               0
  97                  unnamed       1873          0               0
  98          EventManager_De       1845          1             636
  99          futex-default-S       1609          0               0
 100
 101 -E::
 102 --entries=<value>::
 103         Display this many entries.
 104
 105
 106 INFO OPTIONS
 107 ------------
 108
 109 -t::
 110 --threads::
 111         dump thread list in perf.data
 112
 113 -m::
 114 --map::
 115         dump map of lock instances (address:name table)
 116
 117
 118 CONTENTION OPTIONS
 119 --------------
 120
 121 -k::
 122 --key=<value>::
 123         Sorting key. Possible values: contended, wait_total (default),
 124         wait_max, wait_min, avg_wait.
 125
 126 -F::
 127 --field=<value>::
 128         Output fields. By default it shows all but the wait_min fields
 129         and users can customize that using this.  Possible values:
 130         contended, wait_total, wait_max, wait_min, avg_wait.
 131
 132 -t::
 133 --threads::
 134         Show per-thread lock contention stat
 135
 136 -b::
 137 --use-bpf::
 138         Use BPF program to collect lock contention stats instead of
 139         using the input data.
 140
 141 -a::
 142 --all-cpus::
 143         System-wide collection from all CPUs.
 144
 145 -C::
 146 --cpu=<value>::
 147         Collect samples only on the list of CPUs provided. Multiple CPUs can be
 148         provided as a comma-separated list with no space: 0,1. Ranges of CPUs
 149         are specified with -: 0-2.  Default is to monitor all CPUs.
 150
 151 -p::
 152 --pid=<value>::
 153         Record events on existing process ID (comma separated list).
 154
 155 --tid=<value>::
 156         Record events on existing thread ID (comma separated list).
 157
 158 -M::
 159 --map-nr-entries=<value>::
 160         Maximum number of BPF map entries (default: 16384).
 161         This will be aligned to a power of 2.
 162
 163 --max-stack=<value>::
 164         Maximum stack depth when collecting lock contention (default: 8).
 165
 166 --stack-skip=<value>::
 167         Number of stack depth to skip when finding a lock caller (default: 3).
 168
 169 -E::
 170 --entries=<value>::
 171         Display this many entries.
 172
 173 -l::
 174 --lock-addr::
 175         Show lock contention stat by address
 176
 177 -o::
 178 --lock-owner::
 179         Show lock contention stat by owners.  Implies --threads and
 180         requires --use-bpf.
 181
 182 -Y::
 183 --type-filter=<value>::
 184         Show lock contention only for given lock types (comma separated list).
 185         Available values are:
 186           semaphore, spinlock, rwlock, rwlock:R, rwlock:W, rwsem, rwsem:R, rwsem:W,
 187           rtmutex, rwlock-rt, rwlock-rt:R, rwlock-rt:W, pcpu-sem, pcpu-sem:R, pcpu-sem:W,
 188           mutex
 189
 190         Note that RW-variant of locks have :R and :W suffix.  Names without the
 191         suffix are shortcuts for the both variants.  Ex) rwsem = rwsem:R + rwsem:W.
 192
 193 -L::
 194 --lock-filter=<value>::
 195         Show lock contention only for given lock addresses or names (comma separated list).
 196
 197 -S::
 198 --callstack-filter=<value>::
 199         Show lock contention only if the callstack contains the given string.
 200         Note that it matches the substring so 'rq' would match both 'raw_spin_rq_lock'
 201         and 'irq_enter_rcu'.
 202
 203
 204 SEE ALSO
 205 --------
 206 linkperf:perf[1]