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 --map-nr-entries=<value>::
 159         Maximum number of BPF map entries (default: 10240).
 160
 161 --max-stack=<value>::
 162         Maximum stack depth when collecting lock contention (default: 8).
 163
 164 --stack-skip=<value>::
 165         Number of stack depth to skip when finding a lock caller (default: 3).
 166
 167 -E::
 168 --entries=<value>::
 169         Display this many entries.
 170
 171 -l::
 172 --lock-addr::
 173         Show lock contention stat by address
 174
 175 -Y::
 176 --type-filter=<value>::
 177         Show lock contention only for given lock types (comma separated list).
 178         Available values are:
 179           semaphore, spinlock, rwlock, rwlock:R, rwlock:W, rwsem, rwsem:R, rwsem:W,
 180           rtmutex, rwlock-rt, rwlock-rt:R, rwlock-rt:W, pcpu-sem, pcpu-sem:R, pcpu-sem:W,
 181           mutex
 182
 183         Note that RW-variant of locks have :R and :W suffix.  Names without the
 184         suffix are shortcuts for the both variants.  Ex) rwsem = rwsem:R + rwsem:W.
 185
 186 -L::
 187 --lock-filter=<value>::
 188         Show lock contention only for given lock addresses or names (comma separated list).
 189
 190 -S::
 191 --callstack-filter=<value>::
 192         Show lock contention only if the callstack contains the given string.
 193         Note that it matches the substring so 'rq' would match both 'raw_spin_rq_lock'
 194         and 'irq_enter_rcu'.
 195
 196
 197 SEE ALSO
 198 --------
 199 linkperf:perf[1]