The changes aim to ease the understanding of the examples.
No functional changes are introduced.
Signed-off-by: Yordan Karadzhov (VMware) <y.karadz@xxxxxxxxx>
---
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
|