'\" t
.\"     Title: perf-lock
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2023-09-12
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF\-LOCK" "1" "2023\-09\-12" "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 <command>\*(Aq records lock events
between start and end <command>\&. 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=<file>
.RS 4
Input file name\&. (default: perf\&.data unless stdin is a fifo)
.RE
.PP
\-\-output=<file>
.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=<file>
.RS 4
vmlinux pathname
.RE
.PP
\-\-kallsyms=<file>
.RS 4
kallsyms pathname
.RE
.SH "REPORT OPTIONS"
.PP
\-k, \-\-key=<value>
.RS 4
Sorting key\&. Possible values: acquired (default), contended, avg_wait, wait_total, wait_max, wait_min\&.
.RE
.PP
\-F, \-\-field=<value>
.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=<value>
.RS 4
Display this many entries\&.
.RE
.SH "INFO OPTIONS"
.PP
\-t, \-\-threads
.RS 4
dump thread list in perf\&.data
.RE
.PP
\-m, \-\-map
.RS 4
dump map of lock instances (address:name table)
.RE
.sp
CONTENTION OPTIONS
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
\-k::
\-\-key=<value>::
        Sorting key\&. Possible values: contended, wait_total (default),
        wait_max, wait_min, avg_wait\&.

\-F::
\-\-field=<value>::
        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\&.

\-t::
\-\-threads::
        Show per\-thread lock contention stat

\-b::
\-\-use\-bpf::
        Use BPF program to collect lock contention stats instead of
        using the input data\&.

\-a::
\-\-all\-cpus::
        System\-wide collection from all CPUs\&.

\-C::
\-\-cpu=<value>::
        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\&.

\-p::
\-\-pid=<value>::
        Record events on existing process ID (comma separated list)\&.

\-\-tid=<value>::
        Record events on existing thread ID (comma separated list)\&.

\-M::
\-\-map\-nr\-entries=<value>::
        Maximum number of BPF map entries (default: 16384)\&.
        This will be aligned to a power of 2\&.

\-\-max\-stack=<value>::
        Maximum stack depth when collecting lock contention (default: 8)\&.

\-\-stack\-skip=<value>::
        Number of stack depth to skip when finding a lock caller (default: 3)\&.

\-E::
\-\-entries=<value>::
        Display this many entries\&.

\-l::
\-\-lock\-addr::
        Show lock contention stat by address

\-o::
\-\-lock\-owner::
        Show lock contention stat by owners\&.  Implies \-\-threads and
        requires \-\-use\-bpf\&.

\-Y::
\-\-type\-filter=<value>::
        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, pcpu\-sem, pcpu\-sem:R, pcpu\-sem:W,
          mutex

        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\&.

\-L::
\-\-lock\-filter=<value>::
        Show lock contention only for given lock addresses or names (comma separated list)\&.

\-S::
\-\-callstack\-filter=<value>::
        Show lock contention only if the callstack contains the given string\&.
        Note that it matches the substring so \*(Aqrq\*(Aq would match both \*(Aqraw_spin_rq_lock\*(Aq
        and \*(Aqirq_enter_rcu\*(Aq\&.

\-x::
\-\-field\-separator=<SEP>::
        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\&.

\-\-lock\-cgroup::
        Show lock contention stat by cgroup\&.  Requires \-\-use\-bpf\&.

\-G::
\-\-cgroup\-filter=<value>::
        Show lock contention only in the given cgroups (comma separated list)\&.


SEE ALSO
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
\fBperf\fR(1)