1perf-lock(1)
2============
3
4NAME
5----
6perf-lock - Analyze lock events
7
8SYNOPSIS
9--------
10[verse]
11'perf lock' {record|report|script|info|contention}
12
13DESCRIPTION
14-----------
15You can analyze various lock behaviours
16and 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
32COMMON 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
62REPORT 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
106INFO 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
118CONTENTION 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-o::
176--lock-owner::
177	Show lock contention stat by owners.  Implies --threads and
178	requires --use-bpf.
179
180-Y::
181--type-filter=<value>::
182	Show lock contention only for given lock types (comma separated list).
183	Available values are:
184	  semaphore, spinlock, rwlock, rwlock:R, rwlock:W, rwsem, rwsem:R, rwsem:W,
185	  rtmutex, rwlock-rt, rwlock-rt:R, rwlock-rt:W, pcpu-sem, pcpu-sem:R, pcpu-sem:W,
186	  mutex
187
188	Note that RW-variant of locks have :R and :W suffix.  Names without the
189	suffix are shortcuts for the both variants.  Ex) rwsem = rwsem:R + rwsem:W.
190
191-L::
192--lock-filter=<value>::
193	Show lock contention only for given lock addresses or names (comma separated list).
194
195-S::
196--callstack-filter=<value>::
197	Show lock contention only if the callstack contains the given string.
198	Note that it matches the substring so 'rq' would match both 'raw_spin_rq_lock'
199	and 'irq_enter_rcu'.
200
201
202SEE ALSO
203--------
204linkperf:perf[1]
205