A tracepoint example (#596)
diff --git a/examples/tracing/urandomread.py b/examples/tracing/urandomread.py
new file mode 100755
index 0000000..b2a58bd
--- /dev/null
+++ b/examples/tracing/urandomread.py
@@ -0,0 +1,49 @@
+#!/usr/bin/python
+#
+# tracepoint Example of instrumenting a kernel tracepoint.
+# For Linux, uses BCC, BPF. Embedded C.
+#
+# REQUIRES: Linux 4.7+ (BPF_PROG_TYPE_TRACEPOINT support).
+#
+# Test by running this, then in another shell, run:
+# dd if=/dev/urandom of=/dev/null bs=1k count=5
+#
+# Copyright 2016 Netflix, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+from __future__ import print_function
+from bcc import BPF
+
+# define BPF program
+bpf_text = """
+#include <uapi/linux/ptrace.h>
+
+struct urandom_read_args {
+ // from /sys/kernel/debug/tracing/events/random/urandom_read/format
+ // this may be automatically generated in a future bcc version
+ u64 __unused__;
+ u32 got_bits;
+ u32 pool_left;
+ u32 input_left;
+};
+
+int printarg(struct urandom_read_args *args) {
+ bpf_trace_printk("%d\\n", args->got_bits);
+ return 0;
+};
+"""
+
+# load BPF program
+b = BPF(text=bpf_text)
+b.attach_tracepoint("random:urandom_read", "printarg")
+
+# header
+print("%-18s %-16s %-6s %s" % ("TIME(s)", "COMM", "PID", "GOTBITS"))
+
+# format output
+while 1:
+ try:
+ (task, pid, cpu, flags, ts, msg) = b.trace_fields()
+ except ValueError:
+ continue
+ print("%-18.9f %-16s %-6d %s" % (ts, task, pid, msg))
diff --git a/examples/tracing/urandomread_example.txt b/examples/tracing/urandomread_example.txt
new file mode 100755
index 0000000..43d962b
--- /dev/null
+++ b/examples/tracing/urandomread_example.txt
@@ -0,0 +1,20 @@
+Examples of urandomread.py, the Linux eBPF/bcc version.
+
+
+To demonstrate this, the following workload was issued:
+
+# dd if=/dev/urandom of=/dev/null bs=1k count=5
+
+While urandomread.py was tracing in another session:
+
+# ./urandomread.py
+TIME(s) COMM PID GOTBITS
+22592556.392825000 dd 14228 8192
+22592556.392949000 dd 14228 8192
+22592556.393068999 dd 14228 8192
+22592556.393183999 dd 14228 8192
+22592556.393298000 dd 14228 8192
+
+The GOTBITS of 8192 matches the workload of 1 Kbyte (8 Kbit) reads.
+
+This program was really written as a simple example of tracing a tracepoint.