[PATCH 1/4] trace-cruncher: Fix coments & style in ft_utils.py

[PATCH 1/4] trace-cruncher: Fix coments & style in ft_utils.py

[Yordan Karadzhov (VMware)]

No functional changes are introduced by this patch.

Signed-off-by: Yordan Karadzhov (VMware) <y.karadz@gmail.com>
---
 tracecruncher/ft_utils.py | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/tracecruncher/ft_utils.py b/tracecruncher/ft_utils.py
index 26978f3..26a7306 100644
--- a/tracecruncher/ft_utils.py
+++ b/tracecruncher/ft_utils.py
@@ -14,8 +14,8 @@ from . import ftracepy as ft
 def local_tep():
     """ Get the "tep" event of the current system (local).
     """
-    tep = ft.tep_handle();
-    tep.init_local(dir=ft.dir());
+    tep = ft.tep_handle()
+    tep.init_local(dir=ft.dir())
 
     return tep
 
@@ -23,8 +23,8 @@ def local_tep():
 def find_event_id(system, event):
     """ Get the unique identifier of a trace event.
     """
-    tep = ft.tep_handle();
-    tep.init_local(dir=ft.dir(), systems=[system]);
+    tep = ft.tep_handle()
+    tep.init_local(dir=ft.dir(), systems=[system])
 
     return tep.get_event(system=system, name=event).id()
 
@@ -51,7 +51,7 @@ class event:
             self.evt_id = -1
 
     def id(self):
-        """ Retrieve the unique ID of the kprobe event.
+        """ Retrieve the unique ID of the event.
         """
         return int(self.evt_id)
 
@@ -74,7 +74,7 @@ class event:
                             filter=filter)
 
     def clear_filter(self, instance=ft.no_arg()):
-        """ Define the filter for this event.
+        """ Clear the filter for this event.
         """
         ft.clear_event_filter(instance=instance,
                               system=self.system,
@@ -120,7 +120,7 @@ class kprobe(kprobe_base):
         self.add_raw_field(name, probe)
 
     def add_array_arg(self, name, param_id, param_type, offset=0, size=-1):
-        """ Add a array parameter data field to this probe.
+        """ Add an array function parameter data field to this probe.
         """
         if size < 0:
             size = 10
@@ -133,7 +133,7 @@ class kprobe(kprobe_base):
             self.add_raw_field(field_name, probe)
 
     def add_string_arg(self, name, param_id, offset=0, usr_space=False):
-        """ Add a pointer function parameter data field to this probe.
+        """ Add a string function parameter data field to this probe.
         """
         p_type = 'ustring' if usr_space else 'string'
         self.add_ptr_arg(name=name,
@@ -142,7 +142,7 @@ class kprobe(kprobe_base):
                          offset=offset)
 
     def add_string_array_arg(self, name, param_id, offset=0, usr_space=False, size=-1):
-        """ Add a string array parameter data field to this probe.
+        """ Add a string array function parameter data field to this probe.
         """
         p_type = 'ustring' if usr_space else 'string'
         self.add_array_arg(name=name,
@@ -156,13 +156,13 @@ class kprobe(kprobe_base):
         """
         probe = ' '.join('{!s}={!s}'.format(key,val) for (key, val) in self.fields.items())
 
-        self.kp = ft.kprobe(event=self.name, function=self.func, probe=probe);
-        self.kp.register();
+        self.kp = ft.kprobe(event=self.name, function=self.func, probe=probe)
+        self.kp.register()
         self.evt_id = find_event_id(system=ft.tc_event_system(), event=self.name)
 
 
 def parse_record_array_field(event, record, field, size=-1):
-    """ Register this probe to Ftrace.
+    """ Parse the content of an array function parameter data field.
     """
     if size < 0:
         size = 10
@@ -187,8 +187,8 @@ class kretval_probe(kprobe_base):
     def register(self):
         """ Register this probe to Ftrace.
         """
-        self.kp = ft.kprobe(event=self.name, function=self.func);
-        self.kp.register();
+        self.kp = ft.kprobe(event=self.name, function=self.func)
+        self.kp.register()
         self.evt_id = find_event_id(system=ft.tc_event_system(), event=self.name)
 
 
@@ -200,7 +200,7 @@ class khist:
         self.name = name
         self.inst = None
 
-        inst_name = name+'_inst'
+        inst_name = name + '_inst'
         if find:
             self.inst = ft.find_instance(name=inst_name)
             self.attached = False
-- 
2.32.0

[PATCH 2/4] trace-cruncher: Fix misleading comment in start_tracing.py

[Yordan Karadzhov (VMware)]

The new comment in the code describes correctly the example usage of
the 'enable_events' API.

Signed-off-by: Yordan Karadzhov (VMware) <y.karadz@gmail.com>
---
 examples/start_tracing.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/examples/start_tracing.py b/examples/start_tracing.py
index aaeb0cf..367c626 100755
--- a/examples/start_tracing.py
+++ b/examples/start_tracing.py
@@ -11,7 +11,8 @@ import tracecruncher.ftracepy as ft
 # Create new Ftrace instance to work in.
 inst = ft.create_instance()
 
-# Enable all static events from systems "sched" and "irq".
+# Enable several static events, including "sched_switch" and "sched_waking"
+# from systems "sched" and all events from system "irq".
 ft.enable_events(instance=inst,
                  events={'sched': ['sched_switch', 'sched_waking'],
                          'irq':   ['all']})
-- 
2.32.0

[PATCH 3/4] trace-cruncher: Refactor the python classes for kprobes

[Yordan Karadzhov (VMware)]

Currently the usage of the python classes for kprobes exhibits a pattern
that is inconsistent with the usage of the classes for histograms and
synthetic events. The constructors of the histograms and synth. event
classes will directly register the new events on the system, so once the
corresponding object is created it is ready to be used. However, this is not
the case for the constructors of the classes 'kprobe' and 'kretval_probe'.
For these two classes, the user is expected to explicitly call the 'register'
method before using the new dynamic event. Since such inconsistency can
be confusing, here we refactor the 'kprobe' and 'kretval_probe' classes,
eliminating the 'register' method and moving the registration inside the
constructor.

Signed-off-by: Yordan Karadzhov (VMware) <y.karadz@gmail.com>
---
 tracecruncher/ft_utils.py | 136 ++++++++++++++++++--------------------
 1 file changed, 65 insertions(+), 71 deletions(-)

diff --git a/tracecruncher/ft_utils.py b/tracecruncher/ft_utils.py
index 26a7306..741887b 100644
--- a/tracecruncher/ft_utils.py
+++ b/tracecruncher/ft_utils.py
@@ -81,87 +81,86 @@ class event:
                               event=self.name)
 
 
-class kprobe_base(event):
-    def __init__(self, name, func=''):
+class _kprobe_base(event):
+    def __init__(self, name, func):
         """ Constructor.
         """
         super().__init__(system=ft.tc_event_system(), name=name, static=False)
         self.func = func
         self.kp = None
+        self.evt_id = -1
 
-    def set_function(self, name):
-        """ Set the name of the function to be traced.
+    def register(self):
+        """ Register this probe to Ftrace.
         """
-        self.func = name
-
+        self.kp.register()
+        self.evt_id = find_event_id(system=ft.tc_event_system(), event=self.name)
 
-class kprobe(kprobe_base):
-    def __init__(self, name, func=''):
+class kprobe(_kprobe_base):
+    def __init__(self, name, func, fields):
         """ Constructor.
         """
         super().__init__(name, func)
-        self.fields = {}
-
-    def add_raw_field(self, name, probe):
-        """ Add a raw definition of a data field to this probe.
-        """
-        self.fields[str(name)] = str(probe)
-
-    def add_arg(self, name, param_id, param_type):
-        """ Add a function parameter data field to this probe.
-        """
-        probe = '$arg{0}:{1}'.format(param_id, param_type)
-        self.add_raw_field(name, probe)
+        self.fields = fields
+        probe = ' '.join('{!s}={!s}'.format(key,val) for (key, val) in self.fields.items())
+        self.kp = ft.kprobe(event=self.name, function=self.func, probe=probe)
+        self.register()
 
-    def add_ptr_arg(self, name, param_id, param_type, offset=0):
-        """ Add a pointer function parameter data field to this probe.
-        """
-        probe = '+{0}($arg{1}):{2}'.format(offset, param_id, param_type)
-        self.add_raw_field(name, probe)
+def kprobe_add_raw_field(name, probe, fields={}):
+    """ Add a raw definition of a data field to the probe descriptor.
+    """
+    fields[str(name)] = str(probe)
+    return fields
 
-    def add_array_arg(self, name, param_id, param_type, offset=0, size=-1):
-        """ Add an array function parameter data field to this probe.
-        """
-        if size < 0:
-            size = 10
-
-        ptr_size = ctypes.sizeof(ctypes.c_voidp)
-        for i in range(size):
-            field_name = name + str(i)
-            probe = '+{0}(+{1}'.format(offset, i * ptr_size)
-            probe += '($arg{0})):{1}'.format(param_id, param_type)
-            self.add_raw_field(field_name, probe)
-
-    def add_string_arg(self, name, param_id, offset=0, usr_space=False):
-        """ Add a string function parameter data field to this probe.
-        """
-        p_type = 'ustring' if usr_space else 'string'
-        self.add_ptr_arg(name=name,
-                         param_id=param_id,
-                         param_type=p_type,
-                         offset=offset)
-
-    def add_string_array_arg(self, name, param_id, offset=0, usr_space=False, size=-1):
-        """ Add a string array function parameter data field to this probe.
-        """
-        p_type = 'ustring' if usr_space else 'string'
-        self.add_array_arg(name=name,
-                           param_id=param_id,
-                           param_type=p_type,
-                           offset=offset,
-                           size=size)
+def kprobe_add_arg(name, param_id, param_type, fields={}):
+    """ Add a function parameter data field to the probe descriptor.
+    """
+    probe = '$arg{0}:{1}'.format(param_id, param_type)
+    return kprobe_add_raw_field(name=name, probe=probe, fields=fields)
 
-    def register(self):
-        """ Register this probe to Ftrace.
-        """
-        probe = ' '.join('{!s}={!s}'.format(key,val) for (key, val) in self.fields.items())
+def kprobe_add_ptr_arg(name, param_id, param_type, offset=0, fields={}):
+    """ Add a pointer function parameter data field to the probe descriptor.
+    """
+    probe = '+{0}($arg{1}):{2}'.format(offset, param_id, param_type)
+    return kprobe_add_raw_field(name=name, probe=probe, fields=fields)
 
-        self.kp = ft.kprobe(event=self.name, function=self.func, probe=probe)
-        self.kp.register()
-        self.evt_id = find_event_id(system=ft.tc_event_system(), event=self.name)
+def kprobe_add_array_arg(name, param_id, param_type, offset=0,
+                         size=-1, fields={}):
+    """ Add an array function parameter data field to the probe descriptor.
+    """
+    if size < 0:
+        size = 10
 
+    ptr_size = ctypes.sizeof(ctypes.c_voidp)
+    for i in range(size):
+        field_name = name + str(i)
+        probe = '+{0}(+{1}'.format(offset, i * ptr_size)
+        probe += '($arg{0})):{1}'.format(param_id, param_type)
+        return kprobe_add_raw_field(name=field_name, probe=probe, fields=fields)
 
-def parse_record_array_field(event, record, field, size=-1):
+def kprobe_add_string_arg(name, param_id, offset=0, usr_space=False, fields={}):
+    """ Add a string function parameter data field to the probe descriptor.
+    """
+    p_type = 'ustring' if usr_space else 'string'
+    return kprobe_add_ptr_arg(name=name,
+                              param_id=param_id,
+                              param_type=p_type,
+                              offset=offset,
+                              fields=fields)
+
+def kprobe_add_string_array_arg(name, param_id, offset=0, usr_space=False,
+                                size=-1, fields={}):
+    """ Add a string array function parameter data field to the probe descriptor.
+    """
+    p_type = 'ustring' if usr_space else 'string'
+    return kprobe_add_array_arg(name=name,
+                                param_id=param_id,
+                                param_type=p_type,
+                                offset=offset,
+                                size=size,
+                                fields=fields)
+
+def kprobe_parse_record_array_field(event, record, field, size=-1):
     """ Parse the content of an array function parameter data field.
     """
     if size < 0:
@@ -178,18 +177,13 @@ def parse_record_array_field(event, record, field, size=-1):
     return arr
 
 
-class kretval_probe(kprobe_base):
-    def __init__(self, name, func=''):
+class kretval_probe(_kprobe_base):
+    def __init__(self, name, func):
         """ Constructor.
         """
         super().__init__(name, func)
-
-    def register(self):
-        """ Register this probe to Ftrace.
-        """
         self.kp = ft.kprobe(event=self.name, function=self.func)
         self.kp.register()
-        self.evt_id = find_event_id(system=ft.tc_event_system(), event=self.name)
 
 
 class khist:
-- 
2.32.0

[PATCH 4/4] trace-cruncher: Update 'kprobe_open.py' example

[Yordan Karadzhov (VMware)]

The class kprobe has been refactored. Here we update the corresponding
example accordingly. We also add more comments, explaining the usage
of the APIs.

Signed-off-by: Yordan Karadzhov (VMware) <y.karadz@gmail.com>
---
 examples/kprobe_open.py | 45 ++++++++++++++++++++++++++++++++---------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/examples/kprobe_open.py b/examples/kprobe_open.py
index dff4861..141df66 100755
--- a/examples/kprobe_open.py
+++ b/examples/kprobe_open.py
@@ -11,24 +11,42 @@ import sys
 import tracecruncher.ftracepy as ft
 import tracecruncher.ft_utils as tc
 
-open_probe = tc.kprobe(name='open', func='do_sys_openat2')
+# We will define a kprobe event, to be recorded every time the function
+# 'do_sys_openat2' in the kernrl is called.
 
-open_probe.add_string_arg(name='file', param_id=2)
+# Add to the kprobe event a string field 'file', that will record the second
+# argument of the function.
+fields = tc.kprobe_add_string_arg(name='file', param_id=2)
 
-open_probe.add_ptr_arg(name='flags',
-                       param_id=3,
-                       param_type='x64')
+# Add to the kprobe event a field 'flags'. This field will take the third
+# argument of the function, which is a pointer to an object and will convert
+# its starting address into hexadecimal integer. This will decode the first
+# data field of the object.
+fields = tc.kprobe_add_ptr_arg(name='flags',
+                               param_id=3,
+                               param_type='x64',
+                               fields=fields)
 
-open_probe.add_ptr_arg(name='mode',
-                       param_id=3,
-                       param_type='x64',
-                       offset=8)
+# Add to the kprobe event a field 'flags'. This field will take the third
+# argument of the function, which is a pointer to an object and will convert
+# its starting address plus offset of 8 into hexadecimal integer. This will
+# decode the second data field of the object.
+fields = tc.kprobe_add_ptr_arg(name='mode',
+                               param_id=3,
+                               param_type='x64',
+                               offset=8,
+                               fields=fields)
 
-open_probe.register()
+# Create the kprobe event.
+open_probe = tc.kprobe(name='open',
+                       func='do_sys_openat2',
+                       fields=fields)
 
 tep = tc.local_tep()
 tc.short_kprobe_print(tep, [open_probe])
 
+# Define a callback function that will print
+# a short human-readable version.
 def callback(event, record):
     print(tep.info(event, record))
 
@@ -38,6 +56,13 @@ if __name__ == "__main__":
         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.
     open_probe.enable(instance=inst)
+
+    # Subscribe for the kprobe event (using the default function name 'callback')
+    # and trace the user process.
     ft.trace_process(instance=inst, argv=sys.argv[1:])
-- 
2.32.0