rename tool lockstat.py to klockstat.py

The current lockstat.py is tracing three kernel functions
  mutex_lock_enter(), mutex_unlock_enter(), mutex_lock_return()
for kernel locking statistics.

There are some other efforts trying to get user lock stats by
tracing e.g. pthread locking primitives. For example,
Sasha Goldshtein's linux-tracing-workshop
   https://github.com/goldshtn/linux-tracing-workshop
is referenced in bcc/docs/tutorial_bcc_python_developer.md.
It has a tool called lockstat.py which traces pthread_mutex_init
to collect some lock statistics for userspace locks.

In bcc, in the past, we also had an effort to gather userspace
lock statistics with the same name lockstat.py.
   iovisor#1268

In the future, bcc could have a lockstat tool tracing userspace
locks. So let us rename the current lockstat.py to klockstat.py
to clearly express its scope.

README.md

@@ -118,7 +118,7 @@ pair of .c and .py files, and some are directories of files.
 - tools/[hardirqs](tools/hardirqs.py): Measure hard IRQ (hard interrupt) event time. [Examples](tools/hardirqs_example.txt).
 - tools/[inject](tools/inject.py): Targeted error injection with call chain and predicates [Examples](tools/inject_example.txt).
 - tools/[killsnoop](tools/killsnoop.py): Trace signals issued by the kill() syscall. [Examples](tools/killsnoop_example.txt).
-- tools/[lockstat](tools/lockstat.py): Traces kernel mutex lock events and display locks statistics. [Examples](tools/lockstat_example.txt).
+- tools/[klockstat](tools/klockstat.py): Traces kernel mutex lock events and display locks statistics. [Examples](tools/klockstat_example.txt).
 - tools/[llcstat](tools/llcstat.py): Summarize CPU cache references and misses by process. [Examples](tools/llcstat_example.txt).
 - tools/[mdflush](tools/mdflush.py): Trace md flush events. [Examples](tools/mdflush_example.txt).
 - tools/[memleak](tools/memleak.py): Display outstanding memory allocations to find memory leaks. [Examples](tools/memleak_example.txt).

man/man8/lockstat.8 → man/man8/klockstat.8

@@ -1,10 +1,10 @@
-.TH lockstat 8 "2019-10-22" "USER COMMANDS"
+.TH klockstat 8 "2019-10-22" "USER COMMANDS"
 .SH NAME
-lockstat \- Traces kernel mutex lock events and display locks statistics. Uses Linux eBPF/bcc.
+klockstat \- Traces kernel mutex lock events and display locks statistics. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B lockstat [\-h] [\-i] [\-n] [\-s] [\-c] [\-S FIELDS] [\-p] [\-t] [\-d DURATION]
+.B klockstat [\-h] [\-i] [\-n] [\-s] [\-c] [\-S FIELDS] [\-p] [\-t] [\-d DURATION]
 .SH DESCRIPTION
-lockstats traces kernel mutex lock events and display locks statistics
+klockstat traces kernel mutex lock events and display locks statistics
 and displays following data:
 
  Caller Avg Spin Count Max spin Total spin
@@ -101,57 +101,57 @@ Change the number of unique stack traces that can be stored and displayed.
 .TP
 Sort lock acquired results on acquired count:
 #
-.B lockstats -S acq_count
+.B klockstat -S acq_count
 
 .TP
 Sort lock held results on total held time:
 #
-.B lockstats -S hld_total
+.B klockstat -S hld_total
 
 .TP
 Combination of above:
 #
-.B lockstats -S acq_count,hld_total
+.B klockstat -S acq_count,hld_total
 
 .TP
 Trace system wide:
 #
-.B lockstats
+.B klockstat
 
 .TP
 Trace for 5 seconds only:
 #
-.B lockstats -d 5
+.B klockstat -d 5
 
 .TP
 Display stats every 5 seconds
 #
-.B lockstats -i 5
+.B klockstat -i 5
 
 .TP
 Trace locks for PID 123:
 #
-.B lockstats -p 123
+.B klockstat -p 123
 
 .TP
 Trace locks for PID 321:
 #
-.B lockstats -t 321
+.B klockstat -t 321
 
 .TP
 Display stats only for lock callers with 'pipe_' substring
 #
-.B lockstats -c pipe_
+.B klockstat -c pipe_
 
 .TP
 Display 3 locks:
 #
-.B lockstats -n 3
+.B klockstat -n 3
 
 .TP
 Display 10 levels of stack for the most expensive lock:
 #
-.B lockstats -n 1 -s 10
+.B klockstat -n 1 -s 10
 
 Tracing lock events... Hit Ctrl-C to end.
 ^C

snapcraft/snapcraft.yaml

@@ -151,8 +151,8 @@ apps:
  command: bcc-wrapper javathreads
  killsnoop:
  command: bcc-wrapper killsnoop
- lockstat:
- command: bcc-wrapper lockstat
+ klockstat:
+ command: bcc-wrapper klockstat
  llcstat:
  command: bcc-wrapper llcstat
  mdflush:

tests/python/test_tools_smoke.py

@@ -200,8 +200,8 @@ def test_killsnoop(self):
  self.run_with_int("killsnoop.py", kill=True)
 
  @skipUnless(kernel_version_ge(4,18), "requires kernel >= 4.18")
- def test_lockstat(self):
- self.run_with_int("lockstat.py")
+ def test_klockstat(self):
+ self.run_with_int("klockstat.py")
 
  @skipUnless(kernel_version_ge(4,9), "requires kernel >= 4.9")
  def test_llcstat(self):

tools/lockstat.py → tools/klockstat.py

@@ -1,8 +1,8 @@
 #!/usr/bin/python
 #
-# lockstats traces lock events and display locks statistics.
+# klockstat traces lock events and display locks statistics.
 #
-# USAGE: lockstats
+# USAGE: klockstat
 #
 
 from __future__ import print_function
@@ -16,17 +16,17 @@
 from sys import stderr
 
 examples = """
- lockstats # trace system wide
- lockstats -d 5 # trace for 5 seconds only
- lockstats -i 5 # display stats every 5 seconds
- lockstats -p 123 # trace locks for PID 123
- lockstats -t 321 # trace locks for PID 321
- lockstats -c pipe_ # display stats only for lock callers with 'pipe_' substring
- lockstats -S acq_count # sort lock acquired results on acquired count
- lockstats -S hld_total # sort lock held results on total held time
- lockstats -S acq_count,hld_total # combination of above
- lockstats -n 3 # display 3 locks
- lockstats -s 3 # display 3 levels of stack
+ klockstat # trace system wide
+ klockstat -d 5 # trace for 5 seconds only
+ klockstat -i 5 # display stats every 5 seconds
+ klockstat -p 123 # trace locks for PID 123
+ klockstat -t 321 # trace locks for PID 321
+ klockstat -c pipe_ # display stats only for lock callers with 'pipe_' substring
+ klockstat -S acq_count # sort lock acquired results on acquired count
+ klockstat -S hld_total # sort lock held results on total held time
+ klockstat -S acq_count,hld_total # combination of above
+ klockstat -n 3 # display 3 locks
+ klockstat -s 3 # display 3 levels of stack
 """
 
 # arg validation

tools/lockstat_example.txt → tools/klockstat_example.txt

@@ -1,8 +1,8 @@
-Demonstrations of lockstat, the Linux eBPF/bcc version.
+Demonstrations of klockstat, the Linux eBPF/bcc version.
 
-lockstats traces kernel mutex lock events and display locks statistics
+klockstat traces kernel mutex lock events and display locks statistics
 
-# lockstat.py
+# klockstat.py
 Tracing lock events... Hit Ctrl-C to end.
 ^C
  Caller Avg Spin Count Max spin Total spin
@@ -50,7 +50,7 @@ lock stats in maps and processing them in the python part.
 
 An -i option can be used to display stats in interval (5 seconds in example below):
 
-# lockstat.py -i 5
+# klockstat.py -i 5
 Tracing lock events... Hit Ctrl-C to end.
 
  Caller Avg Spin Count Max spin Total spin
@@ -73,7 +73,7 @@ Tracing lock events... Hit Ctrl-C to end.
 
 A -p option can be used to trace only selected process:
 
-# lockstat.py -p 883
+# klockstat.py -p 883
 Tracing lock events... Hit Ctrl-C to end.
 ^C
  Caller Avg Spin Count Max spin Total spin
@@ -89,7 +89,7 @@ Tracing lock events... Hit Ctrl-C to end.
 
 A -c option can be used to display only callers with specific substring:
 
-# lockstat.py -c pipe_
+# klockstat.py -c pipe_
 Tracing lock events... Hit Ctrl-C to end.
 ^C
  Caller Avg Spin Count Max spin Total spin
@@ -105,7 +105,7 @@ Tracing lock events... Hit Ctrl-C to end.
 
 An -n option can be used to display only specific number of callers:
 
-# lockstat.py -n 3
+# klockstat.py -n 3
 Tracing lock events... Hit Ctrl-C to end.
 ^C
  Caller Avg Spin Count Max spin Total spin
@@ -121,7 +121,7 @@ Tracing lock events... Hit Ctrl-C to end.
 
 An -s option can be used to display number of callers backtrace entries:
 
-# lockstat.py -n 1 -s 3
+# klockstat.py -n 1 -s 3
 Tracing lock events... Hit Ctrl-C to end.
 ^C
  Caller Avg Spin Count Max spin Total spin
@@ -139,7 +139,7 @@ Output can be sorted by using -S <fields> option on various
 fields, the acq_total will force the acquired table to be
 sorted on 'Total spin' column:
 
-# lockstat.py -S acq_total
+# klockstat.py -S acq_total
 Tracing lock events... Hit Ctrl-C to end.
 ^C
  Caller Avg Spin Count Max spin Total spin