'\" t
.\" Title: perf-lock
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 09/04/2026
.\" Manual: perf Manual
.\" Source: perf
.\" Language: English
.\"
.TH "PERF\-LOCK" "1" "09/04/2026" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-lock \- Analyze lock events
.SH "SYNOPSIS"
.sp
.nf
\fIperf lock\fR {record|report|script|info|contention}
.fi
.SH "DESCRIPTION"
.sp
You can analyze various lock behaviours and statistics with this \fIperf lock\fR command\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf lock record \*(Aq records lock events
between start and end \&. And this command
produces the file "perf\&.data" which contains tracing
results of lock events\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf lock report\*(Aq reports statistical data\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf lock script\*(Aq shows raw lock events\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf lock info\*(Aq shows metadata like threads or addresses
of lock instances\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf lock contention\*(Aq shows contention statistics\&.
.fi
.if n \{\
.RE
.\}
.SH "COMMON OPTIONS"
.PP
\-i, \-\-input=
.RS 4
Input file name\&. (default: perf\&.data unless stdin is a fifo)
.RE
.PP
\-\-output=
.RS 4
Output file name for perf lock contention and report\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose (show symbol address, etc)\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
Do not show any warnings or messages\&. (Suppress \-v)
.RE
.PP
\-D, \-\-dump\-raw\-trace
.RS 4
Dump raw trace in ASCII\&.
.RE
.PP
\-f, \-\-force
.RS 4
Don\(cqt complain, do it\&.
.RE
.PP
\-\-vmlinux=
.RS 4
vmlinux pathname
.RE
.PP
\-\-kallsyms=
.RS 4
kallsyms pathname
.RE
.SH "REPORT OPTIONS"
.PP
\-k, \-\-key=
.RS 4
Sorting key\&. Possible values: acquired (default), contended, avg_wait, wait_total, wait_max, wait_min\&.
.RE
.PP
\-F, \-\-field=
.RS 4
Output fields\&. By default it shows all the fields but users can customize that using this\&. Possible values: acquired, contended, avg_wait, wait_total, wait_max, wait_min\&.
.RE
.PP
\-c, \-\-combine\-locks
.RS 4
Merge lock instances in the same class (based on name)\&.
.RE
.PP
\-t, \-\-threads
.RS 4
The \-t option is to show per\-thread lock stat like below:
.sp
.if n \{\
.RS 4
.\}
.nf
$ perf lock report \-t \-F acquired,contended,avg_wait
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Name acquired contended avg wait (ns)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
perf 240569 9 5784
swapper 106610 19 543
:15789 17370 2 14538
ContainerMgr 8981 6 874
sleep 5275 1 11281
ContainerThread 4416 4 944
RootPressureThr 3215 5 1215
rcu_preempt 2954 0 0
ContainerMgr 2560 0 0
unnamed 1873 0 0
EventManager_De 1845 1 636
futex\-default\-S 1609 0 0
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-E, \-\-entries=
.RS 4
Display this many entries\&.
.RE
.SH "INFO OPTIONS"
.PP
\-t, \-\-threads
.RS 4
dump only the thread list in perf\&.data
.RE
.PP
\-m, \-\-map
.RS 4
dump only the map of lock instances (address:name table)
.RE
.SH "CONTENTION OPTIONS"
.PP
\-k, \-\-key=
.RS 4
Sorting key\&. Possible values: contended, wait_total (default), wait_max, wait_min, avg_wait\&.
.RE
.PP
\-F, \-\-field=
.RS 4
Output fields\&. By default it shows all but the wait_min fields and users can customize that using this\&. Possible values: contended, wait_total, wait_max, wait_min, avg_wait\&.
.RE
.PP
\-t, \-\-threads
.RS 4
Show per\-thread lock contention stat
.RE
.PP
\-b, \-\-use\-bpf
.RS 4
Use BPF program to collect lock contention stats instead of using the input data\&.
.RE
.PP
\-a, \-\-all\-cpus
.RS 4
System\-wide collection from all CPUs\&.
.RE
.PP
\-C, \-\-cpu=
.RS 4
Collect samples only on the list of CPUs provided\&. Multiple CPUs can be provided as a comma\-separated list with no space: 0,1\&. Ranges of CPUs are specified with \-: 0\-2\&. Default is to monitor all CPUs\&.
.RE
.PP
\-p, \-\-pid=
.RS 4
Record events on existing process ID (comma separated list)\&.
.RE
.PP
\-\-tid=
.RS 4
Record events on existing thread ID (comma separated list)\&.
.RE
.PP
\-M, \-\-map\-nr\-entries=
.RS 4
Maximum number of BPF map entries (default: 16384)\&. This will be aligned to a power of 2\&.
.RE
.PP
\-\-max\-stack=
.RS 4
Maximum stack depth when collecting lock contention (default: 8)\&.
.RE
.PP
\-\-stack\-skip=
.RS 4
Number of stack depth to skip when finding a lock caller (default: 3)\&.
.RE
.PP
\-E, \-\-entries=
.RS 4
Display this many entries\&.
.RE
.PP
\-l, \-\-lock\-addr
.RS 4
Show lock contention stat by address
.RE
.PP
\-o, \-\-lock\-owner
.RS 4
Show lock contention stat by owners\&. This option can be combined with \-t, which shows owner\(cqs per thread lock stats, or \-v, which shows owner\(cqs stacktrace\&. Requires \-\-use\-bpf\&.
.RE
.PP
\-Y, \-\-type\-filter=
.RS 4
Show lock contention only for given lock types (comma separated list)\&. Available values are: semaphore, spinlock, rwlock, rwlock:R, rwlock:W, rwsem, rwsem:R, rwsem:W, rtmutex, rwlock\-rt, rwlock\-rt:R, rwlock\-rt:W, percpu\-rwmem, pcpu\-sem, pcpu\-sem:R, pcpu\-sem:W, mutex
.sp
.if n \{\
.RS 4
.\}
.nf
Note that RW\-variant of locks have :R and :W suffix\&. Names without the
suffix are shortcuts for the both variants\&. Ex) rwsem = rwsem:R + rwsem:W\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-L, \-\-lock\-filter=
.RS 4
Show lock contention only for given lock addresses or names (comma separated list)\&.
.RE
.PP
\-S, \-\-callstack\-filter=
.RS 4
Show lock contention only if the callstack contains the given string\&. Note that it matches the substring so
\fIrq\fR
would match both
\fIraw_spin_rq_lock\fR
and
\fIirq_enter_rcu\fR\&.
.RE
.PP
\-x, \-\-field\-separator=
.RS 4
Show results using a CSV\-style output to make it easy to import directly into spreadsheets\&. Columns are separated by the string specified in SEP\&.
.RE
.PP
\-\-lock\-cgroup
.RS 4
Show lock contention stat by cgroup\&. Requires \-\-use\-bpf\&.
.RE
.PP
\-G, \-\-cgroup\-filter=
.RS 4
Show lock contention only in the given cgroups (comma separated list)\&.
.RE
.PP
\-J, \-\-inject\-delay=<\m[blue]\fBtime@function\fR\m[]\&\s-2\u[1]\d\s+2>
.RS 4
Add delays to the given lock\&. It\(cqs added to the contention\-end part so that the (new) owner of the lock will be delayed\&. But by slowing down the owner, the waiters will also be delayed as well\&. This is working only with \-b/\-\-use\-bpf\&.
.sp
.if n \{\
.RS 4
.\}
.nf
The \*(Aqtime\*(Aq is specified in nsec but it can have a unit suffix\&. Available
units are "ms", "us" and "ns"\&. Currently it accepts up to 10ms of delays
for safety reasons\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Note that it will busy\-wait after it gets the lock\&. Delaying locks can
have significant consequences including potential kernel crashes\&. Please
use it at your own risk\&.
.fi
.if n \{\
.RE
.\}
.RE
.SH "SEE ALSO"
.sp
\fBperf\fR(1)
.SH "NOTES"
.IP " 1." 4
time@function
.RS 4
\%mailto:time@function
.RE