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