[PATCH 8/8] trace-cruncher: Add more comments to the examples

["Yordan Karadzhov (VMware)" <y.karadz@gmail.com>]

The changes aim to ease the understanding of the examples.
No functional changes are introduced.

Signed-off-by: Yordan Karadzhov (VMware) <y.karadz@gmail.com>
---
 examples/eprobe.py        | 10 +++++++++-
 examples/hist.py          | 32 ++++++++++++++++++++++++++++++++
 examples/hist_oop.py      | 14 +++++++++++---
 examples/syscall_trace.py |  2 +-
 4 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/examples/eprobe.py b/examples/eprobe.py
index a8be907..44fc7cd 100755
--- a/examples/eprobe.py
+++ b/examples/eprobe.py
@@ -11,21 +11,29 @@ import sys
 import tracecruncher.ftracepy as ft
 import tracecruncher.ft_utils as tc
 
+# Create an 'eprobe' that will be attached to the static event 'sys_enter_openat'
+# from system 'syscalls'. The probe will decode the string field of the event
+# called 'filename' and will record its content using the name 'file'.
 fields = tc.eprobe_add_string_field(name='file', target_field='filename',
                                     usr_space=True)
 event = tc.tc_event('syscalls', 'sys_enter_openat')
 eprobe = tc.tc_eprobe(name='sopen_in', target_event=event, fields=fields)
 
-tep = tc.local_tep()
+# Define a callback function that will print
+# a short human-readable version of the 'eprobe'.
 
+tep = tc.local_tep()
 def callback(event, record):
     print(tep.info(event, record))
 
+
 if __name__ == "__main__":
     if len(sys.argv) < 2:
         print('Usage: ', sys.argv[0], ' [PROCESS]')
         sys.exit(1)
 
+    # Create new Ftrace instance to work in. The tracing in this new instance
+    # is not going to be enabled yet.
     inst = ft.create_instance(tracing_on=False)
 
     # Enable the probe.
diff --git a/examples/hist.py b/examples/hist.py
index d668039..044be79 100755
--- a/examples/hist.py
+++ b/examples/hist.py
@@ -16,6 +16,20 @@ inst_name = 'khist_example'
 cmds = ['start', 'stop', 'show', 'continue', 'clear', 'close']
 
 def get_hist():
+    # From the event 'kmalloc' in system 'kmem', create a two-dimensional
+    # histogram, using the event fields 'call_site' and 'bytes_req'.
+    #
+    # The field 'call_site' will be displayed as a kernel symbol.
+    # The field 'bytes_req' will be displayed as normal field (wothout
+    # modifying the type).
+    #
+    # Instead of just recording the "hitcount" in each bin of the histogram,
+    # we will use the 'value' of 'bytes_alloc' as a weight of the individual
+    # histogram entries (events).
+    #
+    # The results will be ordered using 'bytes_req' as a primary and
+    # 'bytes_alloc' as a secondary sorting criteria. For 'bytes_req' we will
+    # use descending order.
     hist = ft.hist(name='h1',
                    system='kmem',
                    event='kmalloc',
@@ -37,30 +51,48 @@ if __name__ == "__main__":
 
     arg1 = sys.argv[1]
     if  arg1.isdigit() or arg1 == 'start':
+        # Create new Ftrace instance and a tracing histogram.
         inst = ft.create_instance(name=inst_name)
         hist = get_hist()
+
+        # Start taking data.
         hist.start(inst)
 
         if arg1.isdigit():
+            # Take data for a while, then stop, print the result, close
+            # the histogram and exit.
             time.sleep(int(arg1))
             hist.stop(inst)
             print(hist.read(inst))
             hist.close(inst)
         else:
+            # Detach the 'hist' object from the trace-cruncher module. This
+            # will prevent the kernel histogram from being destroyed when the
+            # module is closed (at exit).
             ft.detach(inst)
     else:
+        # Try to find existing Ftrace instance and histogram with the same
+        # definitions. The returned instancd is detached from the
+        # trace-cruncher module.
         inst = ft.find_instance(name=inst_name)
         hist = get_hist()
 
         if arg1 == 'stop':
+            # Stop taking data.
             hist.stop(inst)
         elif arg1 == 'show':
+            # Print the collected data.
             print(hist.read(inst))
         elif arg1 == 'continue':
+            # Continue taking data.
             hist.resume(inst)
         elif arg1 == 'clear':
+            # Reset the histogram.
             hist.clear(inst)
 
         if arg1 == 'close':
+            # Destroy the histogram in the kernel and attach the instance to
+            # the trace-cruncher module. This will ensure that the instance
+            # will be destroyed when the module is closed (at exit).
             ft.attach(inst)
             hist.close(inst)
diff --git a/examples/hist_oop.py b/examples/hist_oop.py
index 578b699..507269f 100755
--- a/examples/hist_oop.py
+++ b/examples/hist_oop.py
@@ -12,18 +12,26 @@ import time
 import tracecruncher.ft_utils as tc
 
 name = 'khist_example_oop'
-
 cmds = ['start', 'stop', 'show', 'continue', 'clear', 'close']
 
+# From the event 'kmalloc' in system 'kmem', create a two-dimensional
+# histogram, using the event fields 'call_site' and 'bytes_req'.
+# The field 'call_site' will be displayed as a kernel symbol.
+# The field 'bytes_req' will be displayed as normal field (wothout
+# modifying the type).
 evt = tc.tc_event('kmem', 'kmalloc')
-
 axes={'call_site': 'sym',
       'bytes_req': 'n'}
 
+# Instead of just recording the "hitcount" in each bin of the histogram,
+# we will use the 'value' of 'bytes_alloc' as a weight of the individual
+# histogram entries (events).
 weights=['bytes_alloc']
 
+# The results will be ordered using 'bytes_req' as a primary and
+# 'bytes_alloc' as a secondary sorting criteria. For 'bytes_req' we will
+# use descending order.
 sort_keys=['bytes_req', 'bytes_alloc']
-
 sort_dir={'bytes_req': 'desc'}
 
 if __name__ == "__main__":
diff --git a/examples/syscall_trace.py b/examples/syscall_trace.py
index bfa56ed..1117fab 100755
--- a/examples/syscall_trace.py
+++ b/examples/syscall_trace.py
@@ -19,7 +19,7 @@ args = 'file=+0($file):ustring delta_T=$delta_T:s64'
 # In order to trace a system call, we will create a synthetic event that
 # combines the 'sys_enter_XXX' and 'sys_exit_XXX' static events. A dynamic
 # 'eprobe' will be attached to this synthetic event in order to decode the
-# pointer argument of the system and to calculate the time spend between
+# pointer argument of the system call and to calculate the time spent between
 # 'sys_enter_XXX' and 'sys_exit_XXX' (syscall duration).
 
 eprobe = ft.eprobe(event=eprobe_evt,
-- 
2.32.0