From e422f5e50ecefb96579b6391a2ada7f6367b83c4 Mon Sep 17 00:00:00 2001
From: Brendan Gregg <brendan.d.gregg@gmail.com>
Date: Fri, 1 Jul 2016 18:38:30 -0700
Subject: [PATCH] A tracepoint example (#596)

---
 README.md                                |  1 +
 examples/tracing/urandomread.py          | 49 ++++++++++++++++++++++++
 examples/tracing/urandomread_example.txt | 20 ++++++++++
 3 files changed, 70 insertions(+)
 create mode 100755 examples/tracing/urandomread.py
 create mode 100755 examples/tracing/urandomread_example.txt

diff --git a/README.md b/README.md
index c8199572b4e8..ae7b749a4b6b 100644
--- a/README.md
+++ b/README.md
@@ -65,6 +65,7 @@ Examples:
 - examples/[hello_world.py](examples/hello_world.py): Prints "Hello, World!" for new processes.
 - examples/tracing/[tcpv4connect.py](examples/tracing/tcpv4connect.py): Trace TCP IPv4 active connections. [Examples](examples/tracing/tcpv4connect_example.txt).
 - examples/tracing/[trace_fields.py](examples/tracing/trace_fields.py): Simple example of printing fields from traced events.
+- examples/tracing/[urandomread.py](examples/tracing/urandomread.py): A kernel tracepoint example, which traces random:urandom_read. [Examples](examples/tracing/urandomread_example.txt).
 - examples/tracing/[vfsreadlat.py](examples/tracing/vfsreadlat.py) examples/tracing/[vfsreadlat.c](examples/tracing/vfsreadlat.c): VFS read latency distribution. [Examples](examples/tracing/vfsreadlat_example.txt).
 
 #### Tools:
diff --git a/examples/tracing/urandomread.py b/examples/tracing/urandomread.py
new file mode 100755
index 000000000000..b2a58bd52638
--- /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 000000000000..43d962b425fc
--- /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.