# perf-lock

## NAME



           perf-lock - Analyze lock events
    


## SYNOPSIS



           _perf lock_ {record|report|script|info|contention}
    


## DESCRIPTION



           You can analyze various lock behaviours and statistics with this
           _perf lock_ command.
    
               'perf lock record <command>' records lock events
               between start and end <command>. And this command
               produces the file "perf.data" which contains tracing
               results of lock events.
    
               'perf lock report' reports statistical data.
    
               'perf lock script' shows raw lock events.
    
               'perf lock info' shows metadata like threads or addresses
               of lock instances.
    
               'perf lock contention' shows contention statistics.
    


## COMMON OPTIONS



           -i, --input=<file>
               Input file name. (default: perf.data unless stdin is a fifo)
    
           --output=<file>
               Output file name for perf lock contention and report.
    
           -v, --verbose
               Be more verbose (show symbol address, etc).
    
           -q, --quiet
               Do not show any warnings or messages. (Suppress -v)
    
           -D, --dump-raw-trace
               Dump raw trace in ASCII.
    
           -f, --force
               Don’t complain, do it.
    
           --vmlinux=<file>
               vmlinux pathname
    
           --kallsyms=<file>
               kallsyms pathname
    


## REPORT OPTIONS



           -k, --key=<value>
               Sorting key. Possible values: acquired (default), contended,
               avg_wait, wait_total, wait_max, wait_min.
    
           -F, --field=<value>
               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.
    
           -c, --combine-locks
               Merge lock instances in the same class (based on name).
    
           -t, --threads
               The -t option is to show per-thread lock stat like below:
    
                   $ perf lock report -t -F acquired,contended,avg_wait
    
                   Name   acquired  contended   avg wait (ns)
    
                              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
    
           -E, --entries=<value>
               Display this many entries.
    


## INFO OPTIONS



           -t, --threads
               dump only the thread list in perf.data
    
           -m, --map
               dump only the map of lock instances (address:name table)
    


## CONTENTION OPTIONS



           -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. This option can be
               combined with -t, which shows owner’s per thread lock stats,
               or -v, which shows owner’s stacktrace. 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, percpu-rwmem, 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 _rq_ would match
               both _raw_spin_rq_lock_ and _irq_enter_rcu_.
    
           -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).
    
           -J, --inject-delay=<**time@function******[1] >
               Add delays to the given lock. It’s 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.
    
                   The 'time' 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.
    
                   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.
    


## NOTES



            1. time@function
               mailto:time@function
    


* * *