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-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
204SEE ALSO
205--------
206linkperf:perf[1]
207