rbbcc 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 162758633aea60cbe4979dd77f61603a7f2032d624594b523f990d703d9fc0e6
-  data.tar.gz: 39b9b0b9fd390f45a5a242d6182197d9e39de0fb0444f06c94872a42b5dd4d5a
+  metadata.gz: 35d11d74dd0d8eacf88978ec066ede1d64aef374027d819f5891a124822db4e9
+  data.tar.gz: 22125362cf25181c33b253d7c6ece7d2e9b9fa2d8933d8c7f120c453384df5d8
 SHA512:
-  metadata.gz: e807d4903cbd8683eb58b073700a24993824e23027de3445d2729728e9cbe7d556a7948a15efaf5c5e7462521675854ec40e32e9776d64c637778fcbad4ad79c
-  data.tar.gz: fcecb00f5eb34f247987b445c59daa221b99ed477ffcd5355e965ac20c97cbe748b3650f2066de1b6575e4ffaf97c7cf21bf9751a7e55ec02cfb0a1837f3e7be
+  metadata.gz: d145f5307df79f42679892b26b4f3f320dbdfb7d931f65f9f2b84ba4032d780991c2f2d0fb36a06b030bc59e45d16b4cca201d42e0368eb5ed4d4853958d44f3
+  data.tar.gz: 86c50507da5cc6ba947def8ce7c169937a432579ce92e0b70c0d24d4316fbba7c45a2de22d602b0c166f473db8e8fddeab1d961b07b97dd719b0a30f15fd9234

data/Gemfile.lock

@@ -12,7 +12,7 @@ GEM
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
-    rake (10.5.0)
+    rake (13.0.1)
 
 PLATFORMS
   ruby
@@ -21,7 +21,7 @@ DEPENDENCIES
   bundler (~> 2.0)
   minitest
   pry
-  rake (~> 10.0)
+  rake (~> 13.0)
   rbbcc!
 
 BUNDLED WITH

data/README.md

@@ -94,6 +94,10 @@ $ docker run --privileged \
             runc-5025  [003] d...  1237.797464: : Hello, World!
 ```
 
+## Documents
+
+See [docs/](docs/) for getting started and tutorial.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/docs/README.md

@@ -1,5 +1,7 @@
 # RbBCC Docs
 
 * [Getting Started](getting_started.md)
+* [Ruby Tutorial](tutorial_bcc_ruby_developer.md)
+* [Projects Using RbBCC](projects_using_rbbcc.md)
 
 **Please see also [BCC itself's README](https://github.com/iovisor/bcc/#readme) and [docs](https://github.com/iovisor/bcc/tree/master/docs).** 

data/docs/answers/01-hello-world.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# Original hello_world.py:
+# Copyright (c) PLUMgrid, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License")
+#
+# This Ruby version follows the Apache License 2.0
+
+# run in project examples directory with:
+# sudo ./hello_world.rb"
+# see trace_fields.rb for a longer example
+
+require "rbbcc"
+include RbBCC
+
+# This may not work for 4.17 on x64, you need replace kprobe__sys_clone with kprobe____x64_sys_clone
+BCC.new(text: 'int kprobe__sys_clone(void *ctx) { bpf_trace_printk("Hello, World!\\n"); return 0; }').trace_print

data/docs/answers/02-sys_sync.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+require "rbbcc"
+include RbBCC
+
+puts "Tracing sys_sync()... Ctrl-C to end."
+begin
+  BCC.new(text: <<~BPF).trace_print
+    int kprobe__sys_sync(void *ctx) {
+      bpf_trace_printk("sys_sync() called\\n");
+      return 0;
+    }
+  BPF
+rescue Interrupt
+  puts
+  puts "Done"
+end

data/docs/answers/03-hello_fields.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+require "rbbcc"
+include RbBCC
+
+# define BPF program
+prog = <<BPF
+int hello(void *ctx) {
+    bpf_trace_printk("Hello, World!\\n");
+    return 0;
+}
+BPF
+
+# load BPF program
+b = BCC.new(text: prog)
+b.attach_kprobe(event: b.get_syscall_fnname("clone"), fn_name: "hello")
+
+# header
+puts("%-18s %-16s %-6s %s" % ["TIME(s)", "COMM", "PID", "MESSAGE"])
+
+# format output
+begin
+  b.trace_fields do |task, pid, cpu, flags, ts, msg|
+    print("%-18.9f %-16s %-6d %s" % [ts, task, pid, msg])
+  end
+rescue Interrupt
+  puts
+  puts "Done"
+rescue => e
+  p e
+  retry
+end

data/docs/answers/04-sync_timing.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# Original sync_timing.py:
+# Licensed under the Apache License, Version 2.0 (the "License")
+#
+# This Ruby version follows the Apache License 2.0
+
+require "rbbcc"
+include RbBCC
+
+# load BPF program
+b = BCC.new(text: <<BPF)
+#include <uapi/linux/ptrace.h>
+
+BPF_HASH(last);
+
+int do_trace(struct pt_regs *ctx) {
+    u64 ts, *tsp, delta, key = 0;
+
+    // attempt to read stored timestamp
+    tsp = last.lookup(&key);
+    if (tsp != 0) {
+        delta = bpf_ktime_get_ns() - *tsp;
+        if (delta < 1000000000) {
+            // output if time is less than 1 second
+            bpf_trace_printk("%d\\n", delta / 1000000);
+        }
+        last.delete(&key);
+    }
+
+    // update stored timestamp
+    ts = bpf_ktime_get_ns();
+    last.update(&key, &ts);
+    return 0;
+}
+BPF
+
+b.attach_kprobe(event: b.get_syscall_fnname("sync"), fn_name: "do_trace")
+puts("Tracing for quick sync's... Ctrl-C to end")
+
+# format output
+start = 0
+b.trace_fields do |task, pid, cpu, flags, ts, ms|
+  start = ts.to_f if start.zero?
+  ts = ts.to_f - start
+  puts("At time %.2f s: multiple syncs detected, last %s ms ago" % [ts, ms.chomp])
+end

data/docs/answers/05-sync_count.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+require "rbbcc"
+include RbBCC
+
+# load BPF program
+b = BCC.new(text: <<BPF)
+#include <uapi/linux/ptrace.h>
+
+BPF_HASH(last);
+
+int do_trace(struct pt_regs *ctx) {
+    u64 ts, *tsp, delta, key = 0, counter_key = 1, zero = 0;
+
+    // initialize counter key
+    if (last.lookup_or_try_init(&counter_key, &zero))
+        last.increment(counter_key);
+
+    // attempt to read stored timestamp
+    tsp = last.lookup(&key);
+    if (tsp != 0) {
+        delta = bpf_ktime_get_ns() - *tsp;
+        if (delta < 1000000000) {
+            // output if time is less than 1 second
+            bpf_trace_printk("%d\\n", delta / 1000000);
+        }
+        last.delete(&key);
+    }
+
+    // update stored timestamp
+    ts = bpf_ktime_get_ns();
+    last.update(&key, &ts);
+    return 0;
+}
+BPF
+
+COUNTER_KEY = 1
+
+b.attach_kprobe(event: b.get_syscall_fnname("sync"), fn_name: "do_trace")
+puts("Tracing for quick sync's... Ctrl-C to end")
+
+# format output
+start = 0
+begin
+  b.trace_fields do |task, pid, cpu, flags, ts, ms|
+    start = ts.to_f if start.zero?
+    ts = ts.to_f - start
+    puts("At time %.2f s: multiple syncs detected, last %s ms ago" % [ts, ms.chomp])
+  end
+rescue Interrupt
+  table = b["last"]
+  puts "Count of sys_sync: %d" % table[COUNTER_KEY].to_bcc_value
+end

data/docs/answers/06-disksnoop.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+#
+# disksnoop.rb	Trace block device I/O: basic version of iosnoop.
+#		For Linux, uses BCC, eBPF. Embedded C.
+# This is ported from original disksnoop.py
+#
+# Written as a basic example of tracing latency.
+#
+# Licensed under the Apache License, Version 2.0 (the "License")
+#
+# 11-Aug-2015	Brendan Gregg	Created disksnoop.py
+
+require 'rbbcc'
+include RbBCC
+
+REQ_WRITE = 1		# from include/linux/blk_types.h
+
+# load BPF program
+b = BCC.new(text: <<CLANG)
+#include <uapi/linux/ptrace.h>
+#include <linux/blkdev.h>
+
+BPF_HASH(start, struct request *);
+
+void trace_start(struct pt_regs *ctx, struct request *req) {
+  // stash start timestamp by request ptr
+  u64 ts = bpf_ktime_get_ns();
+
+  start.update(&req, &ts);
+}
+
+void trace_completion(struct pt_regs *ctx, struct request *req) {
+  u64 *tsp, delta;
+
+  tsp = start.lookup(&req);
+  if (tsp != 0) {
+    delta = bpf_ktime_get_ns() - *tsp;
+    bpf_trace_printk("%d %x %d\\n", req->__data_len,
+        req->cmd_flags, delta / 1000);
+    start.delete(&req);
+  }
+}
+CLANG
+
+b.attach_kprobe(event: "blk_start_request", fn_name: "trace_start") if BCC.get_kprobe_functions('blk_start_request')
+b.attach_kprobe(event: "blk_mq_start_request", fn_name: "trace_start")
+b.attach_kprobe(event: "blk_account_io_completion", fn_name: "trace_completion")
+
+# header
+puts("%-18s %-2s %-7s %8s" % ["TIME(s)", "T", "BYTES", "LAT(ms)"])
+
+# format output
+loop do
+  begin
+    task, pid, cpu, flags, ts, msg = b.trace_fields
+    bytes_s, bflags_s, us_s = msg.split
+
+    if (bflags_s.to_i(16) & REQ_WRITE).nonzero?
+      type_s = "W"
+    elsif bytes_s == "0" # see blk_fill_rwbs() for logic
+      type_s = "M"
+    else
+      type_s = "R"
+    end
+    ms = us_s.to_i.to_f / 1000
+
+    puts("%-18.9f %-2s %-7s %8.2f" % [ts, type_s, bytes_s, ms])
+  rescue Interrupt
+    exit
+  end
+end

data/docs/answers/07-hello_perf_output.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+#
+# This is a Hello World example that uses BPF_PERF_OUTPUT.
+# Ported from hello_perf_output.py
+
+require 'rbbcc'
+include RbBCC
+
+# define BPF program
+prog = """
+#include <linux/sched.h>
+
+// define output data structure in C
+struct data_t {
+    u32 pid;
+    u64 ts;
+    char comm[TASK_COMM_LEN];
+};
+BPF_PERF_OUTPUT(events);
+
+int hello(struct pt_regs *ctx) {
+    struct data_t data = {};
+
+    data.pid = bpf_get_current_pid_tgid();
+    data.ts = bpf_ktime_get_ns();
+    bpf_get_current_comm(&data.comm, sizeof(data.comm));
+
+    events.perf_submit(ctx, &data, sizeof(data));
+
+    return 0;
+}
+"""
+
+# load BPF program
+b = BCC.new(text: prog)
+b.attach_kprobe(event: b.get_syscall_fnname("clone"), fn_name: "hello")
+
+# header
+puts("%-18s %-16s %-6s %s" % ["TIME(s)", "COMM", "PID", "MESSAGE"])
+
+# process event
+start = 0
+print_event = lambda { |cpu, data, size|
+  event = b["events"].event(data)
+  if start == 0
+    start = event.ts
+  end
+
+  time_s = ((event.ts - start).to_f) / 1000000000
+  puts("%-18.9f %-16s %-6d %s" % [time_s, event.comm, event.pid,
+                                  "Hello, perf_output!"])
+}
+
+# loop with callback to print_event
+b["events"].open_perf_buffer(&print_event)
+
+loop do
+  b.perf_buffer_poll()
+end

data/docs/answers/08-sync_perf_output.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+require "rbbcc"
+include RbBCC
+
+# load BPF program
+b = BCC.new(text: <<BPF)
+#include <uapi/linux/ptrace.h>
+
+struct data_t {
+    u32 pid;
+    u64 ts;
+    u64 delta;
+};
+BPF_PERF_OUTPUT(events);
+BPF_HASH(last);
+
+int do_trace(struct pt_regs *ctx) {
+    u64 ts, *tsp, delta, key = 0;
+
+    // attempt to read stored timestamp
+    tsp = last.lookup(&key);
+    if (tsp != 0) {
+        struct data_t data = {};
+        delta = bpf_ktime_get_ns() - *tsp;
+        if (delta < 1000000000) {
+            data.pid = bpf_get_current_pid_tgid();
+            data.ts = bpf_ktime_get_ns();
+            data.delta = delta;
+            events.perf_submit(ctx, &data, sizeof(data));
+        }
+        last.delete(&key);
+    }
+
+    // update stored timestamp
+    ts = bpf_ktime_get_ns();
+    last.update(&key, &ts);
+    return 0;
+}
+BPF
+
+b.attach_kprobe(event: b.get_syscall_fnname("sync"), fn_name: "do_trace")
+puts("Tracing for quick sync's... Ctrl-C to end")
+
+# format output
+start = 0
+b["events"].open_perf_buffer do |_, data, _|
+  event = b["events"].event(data)
+  if start == 0
+    start = event.ts
+  end
+
+  time_s = ((event.ts - start).to_f) / 1_000_000_000
+  puts("At time %.2f s: multiple syncs detected, last %s ms ago" % [time_s, event.delta / 1_000_000])
+end
+
+loop do
+  b.perf_buffer_poll()
+end

data/docs/answers/09-bitehist.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+require 'rbbcc'
+include RbBCC
+
+# load BPF program
+b = BCC.new(text: <<BPF)
+#include <uapi/linux/ptrace.h>
+#include <linux/blkdev.h>
+
+BPF_HISTOGRAM(dist);
+
+int kprobe__blk_account_io_completion(struct pt_regs *ctx, struct request *req)
+{
+  dist.increment(bpf_log2l(req->__data_len / 1024));
+  return 0;
+}
+BPF
+
+# header
+puts("Tracing... Hit Ctrl-C to end.")
+
+# trace until Ctrl-C
+begin
+  loop { sleep 0.1 }
+rescue Interrupt
+  puts
+end
+
+# output
+b["dist"].print_log2_hist("kbytes")

data/docs/answers/10-disklatency.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# Licensed under the Apache License, Version 2.0 (the "License")
+
+require 'rbbcc'
+include RbBCC
+
+b = BCC.new(text: <<BPF)
+#include <uapi/linux/ptrace.h>
+#include <linux/blkdev.h>
+
+BPF_HASH(start, struct request *);
+BPF_HISTOGRAM(dist);
+
+// note this program mixes R/W
+// For next step, handle req->cmd_flags and prepare hist hash per op.
+
+void trace_start(struct pt_regs *ctx, struct request *req) {
+  // stash start timestamp by request ptr
+  u64 ts = bpf_ktime_get_ns();
+
+  start.update(&req, &ts);
+}
+
+void trace_completion(struct pt_regs *ctx, struct request *req) {
+  u64 *tsp, delta;
+
+  tsp = start.lookup(&req);
+  if (tsp != 0) {
+    delta = bpf_ktime_get_ns() - *tsp;
+    dist.increment(bpf_log2l(delta / 1000)); // us
+    start.delete(&req);
+  }
+}
+BPF
+
+b.attach_kprobe(event: "blk_start_request", fn_name: "trace_start") if BCC.get_kprobe_functions('blk_start_request')
+b.attach_kprobe(event: "blk_mq_start_request", fn_name: "trace_start")
+b.attach_kprobe(event: "blk_account_io_completion", fn_name: "trace_completion")
+
+# header
+puts("Tracing... Hit Ctrl-C to end.")
+
+# trace until Ctrl-C
+begin
+  loop { sleep 0.1 }
+rescue Interrupt
+  puts
+end
+
+# output
+b["dist"].print_log2_hist("usec")

data/docs/answers/11-vfsreadlat.c

@@ -0,0 +1,46 @@
+/*
+ * From: https://github.com/iovisor/bcc/blob/master/examples/tracing/vfsreadlat.c
+ *
+ * vfsreadlat.c		VFS read latency distribution.
+ *			For Linux, uses BCC, eBPF. See .py/.rb file.
+ *
+ * Copyright (c) 2013-2015 PLUMgrid, http://plumgrid.com
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of version 2 of the GNU General Public
+ * License as published by the Free Software Foundation.
+ *
+ * 15-Aug-2015	Brendan Gregg	Created this.
+ */
+
+#include <uapi/linux/ptrace.h>
+
+BPF_HASH(start, u32);
+BPF_HISTOGRAM(dist);
+
+int do_entry(struct pt_regs *ctx)
+{
+  u32 pid;
+  u64 ts, *val;
+
+  pid = bpf_get_current_pid_tgid();
+  ts = bpf_ktime_get_ns();
+  start.update(&pid, &ts);
+  return 0;
+}
+
+int do_return(struct pt_regs *ctx)
+{
+  u32 pid;
+  u64 *tsp, delta;
+
+  pid = bpf_get_current_pid_tgid();
+  tsp = start.lookup(&pid);
+
+  if (tsp != 0) {
+    delta = bpf_ktime_get_ns() - *tsp;
+    dist.increment(bpf_log2l(delta / 1000));
+    start.delete(&pid);
+  }
+
+  return 0;
+}

data/docs/answers/11-vfsreadlat.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+#
+# Original: from vfsreadlat.py
+# Copyright (c) 2015 Brendan Gregg.
+# Licensed under the Apache License, Version 2.0 (the "License")
+# Ruby version follows.
+#
+# vfsreadlat.rb		VFS read latency distribution.
+#			For Linux, uses BCC, eBPF. See .c file.
+#
+# Written as a basic example of a function latency distribution histogram.
+#
+# USAGE: vfsreadlat.rb [interval [count]]
+#
+# The default interval is 5 seconds. A Ctrl-C will print the partially
+# gathered histogram then exit.
+
+require "rbbcc"
+include RbBCC
+
+def usage
+  puts("USAGE: %s [interval [count]]" % $0)
+  exit
+end
+
+# arguments
+interval = 5
+count = -1
+if ARGV.size > 0
+  begin
+    interval = ARGV[0].to_i
+    raise if interval == 0
+    count = ARGV[1].to_i if ARGV[1]
+  rescue	=> e # also catches -h, --help
+    usage()
+  end
+end
+
+# load BPF program
+b = BCC.new(src_file: "11-vfsreadlat.c")
+b.attach_kprobe(event: "vfs_read", fn_name: "do_entry")
+b.attach_kretprobe(event: "vfs_read", fn_name: "do_return")
+
+# header
+print("Tracing... Hit Ctrl-C to end.")
+
+# output
+cycle = 0
+do_exit = false
+loop do
+  if count > 0
+    cycle += 1
+    exit if cycle > count
+  end
+
+  begin
+    sleep(interval)
+  rescue Interrupt
+    do_exit = true
+  end
+
+  puts
+  b["dist"].print_log2_hist("usecs")
+  b["dist"].clear
+  exit if do_exit
+end

data/docs/answers/12-urandomread.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+#
+# urandomread.rb 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
+#
+# Original urandomread.py Copyright 2016 Netflix, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License")
+# Ruby version follows.
+
+require 'rbbcc'
+include RbBCC
+
+b = BCC.new(text: <<BPF)
+TRACEPOINT_PROBE(random, urandom_read) {
+    // args is from /sys/kernel/debug/tracing/events/random/urandom_read/format
+    bpf_trace_printk("%d\\n", args->got_bits);
+    return 0;
+}
+BPF
+
+# header
+puts("%-18s %-16s %-6s %s" % ["TIME(s)", "COMM", "PID", "GOTBITS"])
+
+# format output
+loop do
+  begin
+    b.trace_fields do |task, pid, cpu, flags, ts, msg|
+      puts("%-18.9f %-16s %-6d %s" % [ts, task, pid, msg])
+    end
+  rescue Interrupt
+    exit
+  end
+end