Merge pull request #104 from iovisor/docs

Docs

README.md

@@ -97,6 +97,39 @@ verify_cpu+0
 ]: 150
 ```
 
+## One-Liners
+
+The following one-liners demonstrate different capabilities:
+
+```
+# Files opened by process
+bpftrace -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'
+
+# Syscall count by program
+bpftrace -e 'tracepoint:raw_syscalls:sys_enter { @[comm] = count(); }'
+
+# Read bytes by process:
+bpftrace -e 'tracepoint:syscalls:sys_exit_read /args->ret/ { @[comm] = sum(args->ret); }'
+
+# Read size distribution by process:
+bpftrace -e 'tracepoint:syscalls:sys_exit_read { @[comm] = hist(args->ret); }'
+
+# Show per-second syscall rates:
+bpftrace -e 'tracepoint:raw_syscalls:sys_enter { @ = count(); } interval:s:1 { print(@); clear(@); }'
+
+# Trace disk size by process
+bpftrace -e 'tracepoint:block:block_rq_issue { printf("%d %s %d\n", pid, comm, args->bytes); }'
+
+# Count page faults by process
+bpftrace -e 'software:faults:1 { @[comm] = count(); }'
+
+# Count LLC cache misses by process name and PID (uses PMCs):
+bpftrace -e 'hardware:cache-misses:1000000 { @[comm, pid] = count(); }'
+
+# Profile user-level stacks at 99 Hertz, for PID 189:
+bpftrace -e 'profile:hz:99 /pid == 189/ { @[ustack] = count(); }'
+```
+
 ## Tools
 
 bpftrace contains various tools, which also serve as examples of programming in the bpftrace language.
@@ -223,11 +256,13 @@ Functions:
 - `print(@x[, int top [, int div]])` - Print a map, with optional top entry count and divisor
 - `clear(@x)` - Delet all key/values from a map
 - `sym(void *p)` - Resolve kernel address
-- `usym(void *p)` - Resolve user space address (incomplete)
+- `usym(void *p)` - Resolve user space address
 - `kaddr(char *name)` - Resolve kernel symbol name
+- `uaddr(char *name)` - Resolve user space symbol name
 - `reg(char *name)` - Returns the value stored in the named register
 - `join(char *arr[])` - Prints the string array
 - `time(char *fmt)` - Print the current time
+- `system(char *fmt)` - Execute shell command
 - `exit()` - Quit bpftrace
 
 See the [Reference Guide](docs/reference_guide.md) for more detail.

docs/reference_guide.md

@@ -50,8 +50,10 @@ This is a work in progress. If something is missing, check the bpftrace source t
     - [6. `sym()`: Symbol Resolution, Kernel-Level](#6-str-symbol-resolution-kernel-level)
     - [7. `usym()`: Symbol Resolution, User-Level](#7-usym-symbol-resolution-user-level)
     - [8. `kaddr()`: Address Resolution, Kernel-Level](#8-kaddr-address-resolution-kernel-level)
-    - [9. `reg()`: Registers](#9-reg-registers)
-    - [10. `exit()`: Exit](#10-exit-exit)
+    - [9. `uaddr()`: Address Resolution, User-Level](#9-uaddr-address-resolution-user-level)
+    - [10. `reg()`: Registers](#10-reg-registers)
+    - [11. `system()`: System](#11-system-system)
+    - [12. `exit()`: Exit](#12-exit-exit)
 - [Map Functions](#map-functions)
     - [1. Builtins](#1-builtins-2)
     - [2. `count()`: Count](#2-count-count)
@@ -360,15 +362,15 @@ These can be used in bpftrace scripts to document your code.
 
 ## 4. `->`: C Struct Navigation
 
-**TODO**: see issue [#31](https://github.com/iovisor/bpftrace/issues/31)
-
-Future example:
+Example:
 
 ```
-bpftrace -e 'kprobe:do_nanosleep { printf("secs: %d\n", arg0->tv_nsec); }
+bpftrace -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'
 ```
 
-or
+This is returning the `filename` member from the `args` struct, which for tracepoint probes contains the tracepoint arguments.
+
+A future example is to add struct support to kprobes, so that this is possible (see issue [#34](https://github.com/iovisor/bpftrace/issues/34)):
 
 ```
 bpftrace -e 'kprobe:do_nanosleep { printf("secs: %d\n", ((struct timespec *)arg0)->tv_nsec); }'
@@ -452,6 +454,8 @@ returned: 21
 [...]
 ```
 
+**TODO**: see issue [#34](https://github.com/iovisor/bpftrace/issues/34) for supporting struct arguments on kprobes.
+
 ## 3. `uprobe`/`uretprobe`: Dynamic Tracing, User-Level
 
 Syntax:
@@ -557,14 +561,42 @@ block I/O created by 28941
 
 ## 6. `tracepoint`: Static Tracing, Kernel-Level Arguments
 
-**TODO**: see issue [#32](https://github.com/iovisor/bpftrace/issues/32)
+Example:
+
+```
+# bpftrace-tp -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'
+Attaching 1 probe...
+irqbalance /proc/interrupts
+irqbalance /proc/stat
+snmpd /proc/diskstats
+snmpd /proc/stat
+snmpd /proc/vmstat
+snmpd /proc/net/dev
+[...]
+```
 
-Future examples:
+The available members for each tracepoint can be listed from their /format file in /sys. For example:
 
 ```
-bpftrace -e 'tracepoint:block:block_rq_insert { printf("sectors: %d\n", args->nr_sector); }'
+# cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_open/format
+name: sys_enter_open
+ID: 603
+format:
+	field:unsigned short common_type;	offset:0;	size:2;	signed:0;
+	field:unsigned char common_flags;	offset:2;	size:1;	signed:0;
+	field:unsigned char common_preempt_count;	offset:3;	size:1;	signed:0;
+	field:int common_pid;	offset:4;	size:4;	signed:1;
+
+	field:int __syscall_nr;	offset:8;	size:4;	signed:1;
+	field:const char * filename;	offset:16;	size:8;	signed:0;
+	field:int flags;	offset:24;	size:8;	signed:0;
+	field:umode_t mode;	offset:32;	size:8;	signed:0;
+
+print fmt: "filename: 0x%08lx, flags: 0x%08lx, mode: 0x%08lx", ((unsigned long)(REC->filename)), ((unsigned long)(REC->flags)), ((unsigned long)(REC->mode))
 ```
 
+Apart from the `filename` member, we can also print `flags`, `mode`, and more. After the "common" members listed first, the members are specific to the tracepoint.
+
 ## 7. `usdt`: Static Tracing, User-Level
 
 Syntax:
@@ -1019,7 +1051,9 @@ Note that for this example to work, bash had to be recompiled with frame pointer
 - `sym(void *p)` - Resolve kernel address
 - `usym(void *p)` - Resolve user space address
 - `kaddr(char *name)` - Resolve kernel symbol name
+- `uaddr(char *name)` - Resolve user-level symbol name
 - `reg(char *name)` - Returns the value stored in the named register
+- `system(char *fmt)` - Execute shell command
 - `exit()` - Quit bpftrace
 
 Some of these are asynchronous: the kernel queues the event, but some time later (milliseconds) it is processed in user-space. The asynchronous actions are: <tt>printf()</tt>, <tt>time()</tt>, and <tt>join()</tt>. Both <tt>sym()</tt> and <tt>usym()</tt>, as well as the variables <tt>stack</tt> and </tt>ustack</tt>, record addresses synchronously, but then do symbol translation asynchronously.
@@ -1148,7 +1182,23 @@ This is printing the `usbcore_name` string from drivers/usb/core/usb.c:
 const char *usbcore_name = "usbcore";
 ```
 
-## 9. `reg()`: Registers
+## 9. `uaddr()`: Address resolution, user-level
+
+Syntax: `uaddr(char *name)`
+
+Examples:
+
+```
+# bpftrace -e 'uprobe:/bin/bash:readline { printf("PS1: %s\n", str(*uaddr("ps1_prompt"))); }'
+Attaching 1 probe...
+PS1: \[\e[34;1m\]\u@\h:\w>\[\e[0m\]
+PS1: \[\e[34;1m\]\u@\h:\w>\[\e[0m\]
+^C
+```
+
+This is printing the `ps1_prompt` string from /bin/bash, whenever a `readline()` function is executed.
+
+## 10. `reg()`: Registers
 
 Syntax: `reg(char *name)`
 
@@ -1164,7 +1214,29 @@ Attaching 1 probe...
 
 See src/arch/x86_64.cpp for the register name list.
 
-## 10. `exit()`: Exit
+## 11. `system()`: System
+
+Syntax: `system(fmt)`
+
+This runs the provided command at the shell. For example:
+
+```
+# bpftrace -e 'kprobe:do_nanosleep { system("ps -p %d\n", pid); }'
+Attaching 1 probe...
+  PID TTY          TIME CMD
+ 1339 ?        00:00:15 iscsid
+  PID TTY          TIME CMD
+ 1339 ?        00:00:15 iscsid
+  PID TTY          TIME CMD
+ 1518 ?        00:01:07 irqbalance
+  PID TTY          TIME CMD
+ 1339 ?        00:00:15 iscsid
+^C
+```
+
+This can be useful to execute commands or a shell script when an instrumented event happens.
+
+## 12. `exit()`: Exit
 
 Syntax: `exit()`