Merge pull request #185 from brendangregg/master

print_log2_hist() for #143

examples/bitehist.py

@@ -5,8 +5,6 @@
 #
 # Written as a basic example of using a histogram to show a distribution.
 #
-# USAGE: bitehist.py [interval [count]]
-#
 # The default interval is 5 seconds. A Ctrl-C will print the partially
 # gathered histogram then exit.
 #
@@ -16,90 +14,19 @@
 # 15-Aug-2015	Brendan Gregg	Created this.
 
 from bcc import BPF
-from ctypes import c_ushort, c_int, c_ulonglong
 from time import sleep
-from sys import argv
-
-def usage():
-	print("USAGE: %s [interval [count]]" % argv[0])
-	exit()
-
-# arguments
-interval = 5
-count = -1
-if len(argv) > 1:
-	try:
-		interval = int(argv[1])
-		if interval == 0:
-			raise
-		if len(argv) > 2:
-			count = int(argv[2])
-	except:	# also catches -h, --help
-		usage()
 
 # load BPF program
 b = BPF(src_file = "bitehist.c")
 b.attach_kprobe(event="blk_start_request", fn_name="do_request")
-dist_max = 64
 
 # header
 print("Tracing... Hit Ctrl-C to end.")
 
-# functions
-stars_max = 38
-def stars(val, val_max, width):
-	i = 0
-	text = ""
-	while (1):
-		if (i > (width * val / val_max) - 1) or (i > width - 1):
-			break
-		text += "*"
-		i += 1
-	if val > val_max:
-		text = text[:-1] + "+"
-	return text
-
-def print_log2_hist(dist, val_type):
-	idx_max = -1
-	val_max = 0
-	for i in range(1, dist_max + 1):
-		try:
-			val = dist[c_int(i)].value
-			if (val > 0):
-				idx_max = i
-			if (val > val_max):
-				val_max = val
-		except:
-			break
-	if idx_max > 0:
-		print("     %-15s : count     distribution" % val_type);
-	for i in range(1, idx_max + 1):
-		low = (1 << i) >> 1
-		high = (1 << i) - 1
-		if (low == high):
-			low -= 1
-		try:
-			val = dist[c_int(i)].value
-			print("%8d -> %-8d : %-8d |%-*s|" % (low, high, val,
-			    stars_max, stars(val, val_max, stars_max)))
-		except:
-			break
-
 # output
-loop = 0
-do_exit = 0
-while (1):
-	if count > 0:
-		loop += 1
-		if loop > count:
-			exit()
-	try:
-		sleep(interval)
-	except KeyboardInterrupt:
-		pass; do_exit = 1
-
+try:
+	sleep(99999999)
+except KeyboardInterrupt:
 	print
-	print_log2_hist(b["dist"], "kbytes")
-	b["dist"].clear()
-	if do_exit:
-		exit()
+
+b["dist"].print_log2_hist()

examples/bitehist_example.txt

 Demonstrations of bitehist.py, the Linux eBPF/bcc version.
 
 This prints a power-of-2 histogram to show the block I/O size distribution.
-By default, a summary is printed every five seconds:
+A summary is printed after Ctrl-C is hit.
 
 # ./bitehist.py 
 Tracing... Hit Ctrl-C to end.
-
-     kbytes          : count     distribution
-       0 -> 1        : 0        |                                      |
-       2 -> 3        : 0        |                                      |
-       4 -> 7        : 26       |*************                         |
-       8 -> 15       : 3        |*                                     |
-      16 -> 31       : 5        |**                                    |
-      32 -> 63       : 6        |***                                   |
-      64 -> 127      : 7        |***                                   |
-     128 -> 255      : 75       |**************************************|
-
-     kbytes          : count     distribution
-       0 -> 1        : 0        |                                      |
-       2 -> 3        : 0        |                                      |
-       4 -> 7        : 83       |**************************************|
-       8 -> 15       : 2        |                                      |
-      16 -> 31       : 6        |**                                    |
-      32 -> 63       : 6        |**                                    |
-      64 -> 127      : 5        |**                                    |
-     128 -> 255      : 21       |*********                             |
 ^C
-     kbytes          : count     distribution
-       0 -> 1        : 0        |                                      |
-       2 -> 3        : 0        |                                      |
-       4 -> 7        : 8        |**************************************|
-
-The first output shows a bimodal distribution. The largest mode of 75 I/O were
-between 128 and 255 Kbytes in size, and another mode of 26 I/O were between 4
-and 7 Kbytes in size. 
-
-The next output summary shows the workload is doing more 4 - 7 Kbyte I/O.
-
-The final output is partial, showing what was measured until Ctrl-C was hit.
-
-
-For an output interval of one second, and three summaries:
-
-# ./bitehist.py 1 3
-Tracing... Hit Ctrl-C to end.
-
-     kbytes          : count     distribution
-       0 -> 1        : 0        |                                      |
+     value           : count     distribution
+       0 -> 1        : 3        |                                      |
        2 -> 3        : 0        |                                      |
-       4 -> 7        : 4        |**************************************|
-
-     kbytes          : count     distribution
-       0 -> 1        : 0        |                                      |
-       2 -> 3        : 0        |                                      |
-       4 -> 7        : 5        |**************************************|
+       4 -> 7        : 211      |**********                            |
        8 -> 15       : 0        |                                      |
       16 -> 31       : 0        |                                      |
-      32 -> 63       : 1        |*******                               |
-
-     kbytes          : count     distribution
-       0 -> 1        : 0        |                                      |
-       2 -> 3        : 0        |                                      |
-       4 -> 7        : 4        |**************************************|
-
+      32 -> 63       : 0        |                                      |
+      64 -> 127      : 1        |                                      |
+     128 -> 255      : 800      |**************************************|
 
-Full usage:
+This output shows a bimodal distribution. The largest mod of 800 I/O were
+between 128 and 255 Kbytes in size, and another mode of 211 I/O were between
+4 and 7 Kbytes in size.
 
-# ./bitehist.py -h
-USAGE: ./bitehist.py [interval [count]]
+Understanding this distribution is useful for characterizing workloads and
+understanding performance. The existance of this distribution is not visible
+from averages alone.

examples/hello_world.py

@@ -4,15 +4,10 @@
 
 # run in project examples directory with:
 # sudo ./hello_world.py"
+# see trace_fields.py for a longer example
 
 from bcc import BPF
 
-prog = """
-int hello(void *ctx) {
-  bpf_trace_printk("Hello, World!\\n");
-  return 0;
-}
-"""
-b = BPF(text=prog)
+b = BPF(text='void hello(void *ctx) { bpf_trace_printk("Hello, World!\\n"); }')
 b.attach_kprobe(event="sys_clone", fn_name="hello")
-b.trace_print(fmt="{1} {5}")
+b.trace_print()

examples/trace_fields.py

+#!/usr/bin/env python
+# Copyright (c) PLUMgrid, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+# This is an example of tracing an event and printing custom fields.
+# run in project examples directory with:
+# sudo ./trace_fields.py"
+
+from bcc import BPF
+
+prog = """
+int hello(void *ctx) {
+  bpf_trace_printk("Hello, World!\\n");
+  return 0;
+}
+"""
+b = BPF(text=prog)
+b.attach_kprobe(event="sys_clone", fn_name="hello")
+print "PID MESSAGE"
+b.trace_print(fmt="{1} {5}")

examples/vfsreadlat.py

@@ -41,51 +41,10 @@ if len(argv) > 1:
 b = BPF(src_file = "vfsreadlat.c")
 b.attach_kprobe(event="vfs_read", fn_name="do_entry")
 b.attach_kretprobe(event="vfs_read", fn_name="do_return")
-dist_max = 64
 
 # header
 print("Tracing... Hit Ctrl-C to end.")
 
-# functions
-stars_max = 38
-def stars(val, val_max, width):
-	i = 0
-	text = ""
-	while (1):
-		if (i > (width * val / val_max) - 1) or (i > width - 1):
-			break
-		text += "*"
-		i += 1
-	if val > val_max:
-		text = text[:-1] + "+"
-	return text
-
-def print_log2_hist(dist, val_type):
-	idx_max = -1
-	val_max = 0
-	for i in range(1, dist_max + 1):
-		try:
-			val = dist[c_int(i)].value
-			if (val > 0):
-				idx_max = i
-			if (val > val_max):
-				val_max = val
-		except:
-			break
-	if idx_max > 0:
-		print("     %-15s : count     distribution" % val_type);
-	for i in range(1, idx_max + 1):
-		low = (1 << i) >> 1
-		high = (1 << i) - 1
-		if (low == high):
-			low -= 1
-		try:
-			val = dist[c_int(i)].value
-			print("%8d -> %-8d : %-8d |%-*s|" % (low, high, val,
-			    stars_max, stars(val, val_max, stars_max)))
-		except:
-			break
-
 # output
 loop = 0
 do_exit = 0
@@ -100,7 +59,7 @@ while (1):
 		pass; do_exit = 1
 
 	print
-	print_log2_hist(b["dist"], "usecs")
+	b["dist"].print_log2_hist("usecs")
 	b["dist"].clear()
 	if do_exit:
 		exit()

src/python/bcc/__init__.py

@@ -95,6 +95,7 @@ KALLSYMS = "/proc/kallsyms"
 ksym_addrs = []
 ksym_names = []
 ksym_loaded = 0
+stars_max = 38
 
 @atexit.register
 def cleanup_kprobes():
@@ -220,6 +221,52 @@ class BPF(object):
             else:
                 super(BPF.Table, self).clear()
 
+        @staticmethod
+        def _stars(val, val_max, width):
+            i = 0
+            text = ""
+            while (1):
+                if (i > (width * val / val_max) - 1) or (i > width - 1):
+                    break
+                text += "*"
+                i += 1
+            if val > val_max:
+                text = text[:-1] + "+"
+            return text
+
+        def print_log2_hist(self, val_type="value"):
+            """print_log2_hist(type=value)
+
+            Prints a table as a log2 histogram. The table must be stored as
+            log2. The type argument is optional, and is a column header.
+            """
+            global stars_max
+            log2_dist_max = 64
+            idx_max = -1
+            val_max = 0
+            for i in range(1, log2_dist_max + 1):
+                try:
+                    val = self[ct.c_int(i)].value
+                    if (val > 0):
+                        idx_max = i
+                    if (val > val_max):
+                        val_max = val
+                except:
+                    break
+            if idx_max > 0:
+                print("     %-15s : count     distribution" % val_type);
+            for i in range(1, idx_max + 1):
+                low = (1 << i) >> 1
+                high = (1 << i) - 1
+                if (low == high):
+                    low -= 1
+                try:
+                    val = self[ct.c_int(i)].value
+                    print("%8d -> %-8d : %-8d |%-*s|" % (low, high, val,
+                        stars_max, self._stars(val, val_max, stars_max)))
+                except:
+                    break
+
 
         def __iter__(self):
             return BPF.Table.Iter(self, self.Key)