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 + +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.