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.
   #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.

Author: yonghong-song

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