See previous requirements, and specific targets in the sections that follow (Ubuntu, Docker).
```
git clone https://github.com/ajor/bpftrace
git clone https://github.com/iovisor/bpftrace
mkdir -p bpftrace/build
cd bpftrace/build
cmake -DCMAKE_BUILD_TYPE=Debug ../
...
...
@@ -53,6 +46,40 @@ By default bpftrace will be built as a dynamically linked executable. If a stati
The latest versions of BCC and Google Test will be downloaded on each build. To speed up builds and only download their sources on the first run, use the CMake option `-DOFFLINE_BUILDS:BOOL=ON`.
To test that the build works, you can try running the test suite, and a one-liner:
```
./tests/bpftrace_test
./src/bpftrace -e 'kprobe:do_nanosleep { printf("sleep by %s\n", comm); }'
```
## Ubuntu
The llvm/clang packages that are currently available for Ubuntu have an issue, so we'll use the ones from llvm.org for now. The build instructions are:
```
cat <<EOF | sudo tee -a /etc/apt/sources.list
# from https://apt.llvm.org/:
deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial main
deb-src http://apt.llvm.org/xenial/ llvm-toolchain-xenial main
# 5.0
deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-5.0 main
deb-src http://apt.llvm.org/xenial/ llvm-toolchain-xenial-5.0 main
# 6.0
deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-6.0 main
deb-src http://apt.llvm.org/xenial/ llvm-toolchain-xenial-6.0 main
BPFtrace is a high-level tracing language for Linux enhanced Berkeley Packet Filter (eBPF) available in recent Linux kernels (4.x). BPFtrace uses LLVM as a backend to compile scripts to BPF-bytecode and makes use of [BCC](https://github.com/iovisor/bcc) for interacting with the Linux BPF system, as well as existing Linux tracing capabilities: kernel dynamic tracing (kprobes), user-level dynamic tracing (uprobes), and tracepoints. The BPFtrace language is inspired by awk and C, and predecessor tracers such as DTrace and SystemTap.
BPFtrace is a high-level tracing language for Linux enhanced Berkeley Packet Filter (eBPF) available in recent Linux kernels (4.x). BPFtrace uses LLVM as a backend to compile scripts to BPF-bytecode and makes use of [BCC](https://github.com/iovisor/bcc) for interacting with the Linux BPF system, as well as existing Linux tracing capabilities: kernel dynamic tracing (kprobes), user-level dynamic tracing (uprobes), and tracepoints. The BPFtrace language is inspired by awk and C, and predecessor tracers such as DTrace and SystemTap. BPFtrace was created by [Alastair Robertson](https://github.com/ajor).
For instructions on building BPFtrace, see [INSTALL.md](INSTALL.md). There is also a [Reference Guide](docs/reference_guide.md) and [One-Liner Tutorial](docs/tutorial_one_liners.md).
...
...
@@ -222,6 +222,7 @@ Variables:
-`arg0`, `arg1`, ... etc. - Arguments to the function being traced
-`retval` - Return value from function being traced
-`func` - Name of the function currently being traced
-`name` - Full name of the probe
-`curtask` - Current task_struct as a u64.
-`rand` - Random number of type u32.
...
...
@@ -241,6 +242,7 @@ Functions:
-`clear(@x)` - Delet all key/values from a map
-`sym(void *p)` - Resolve kernel address
-`usym(void *p)` - Resolve user space address (incomplete)
-`kaddr(char *name)` - Resolve kernel symbol name
-`reg(char *name)` - Returns the value stored in the named register
This is printing the `usbcore_name` string from drivers/usb/core/usb.c:
```
const char *usbcore_name = "usbcore";
```
## 9. `reg()`: Registers
Syntax: `reg(char *name)`
...
...
@@ -856,7 +912,7 @@ Attaching 1 probe...
See src/arch/x86_64.cpp for the register name list.
## 9. `exit()`: Exit
## 10. `exit()`: Exit
Syntax: `exit()`
...
...
@@ -870,6 +926,31 @@ Attaching 2 probes...
# Map Functions
Maps are special BPF data types that can be used to store counts, statistics, and histograms. They are also used for some variable types as discussed in the previous section, whenever `@` is used: [globals](#21-global), [per thread variables](#22-per-thread), and [associative arrays](#3--associative-arrays).
When bpftrace exits, all maps are printed. For example (the `count()` function is covered in the sections that follow):
The map was printed after the Ctrl-C to end the program. If you use maps that you do not wish to be automatically printed on exit, you can add an END block that clears the maps. For example:
```
END
{
clear(@start);
}
```
## 1. Builtins
-`count()` - Count the number of times this function is called
...
...
@@ -1245,6 +1326,38 @@ Histograms can also be printed on-demand, using the <tt>print()</tt> function. E
[...]
</pre>
# Advanced Tools
bpftrace can be used to create some powerful one-liners and some simple tools. For complex tools, which may involve command line options, positional parameters, argument processing, and customized output, consider switching to [bcc](https://github.com/iovisor/bcc). bcc provides Python (and other) front-ends, enabling usage of all the other Python libraries (including argparse), as well as a direct control of the kernel BPF program. The down side is that bcc is much more verbose and laborious to program. Together, bpftrace and bcc are complimentary.
An expected development path would be exploration with bpftrace one-liners, then and ad hoc scripting with bpftrace, then finally, when needed, advanced tooling with bcc.
As an example of bpftrace vs bcc differences, the bpftrace xfsdist.bt tool also exists in bcc as xfsdist.py. Both measure the same functions and produce the same summary of information. However, the bcc version supports various arguments:
This teaches you bpftrace for Linux in 12 easy lessons, where each lesson is a one-liner you can try running. This series of one-liners introduces concepts which are summarized as bullet points. For a full reference to bpftrace, see docs/reference_guide.md.
This teaches you bpftrace for Linux in 12 easy lessons, where each lesson is a one-liner you can try running. This series of one-liners introduces concepts which are summarized as bullet points. For a full reference to bpftrace, see the [Reference Guide](reference_guide.md)
Contributed by Brendan Gregg, Netflix (2018), based on his FreeBSD [DTrace Tutorial](https://wiki.freebsd.org/DTrace/Tutorial).
...
...
@@ -278,5 +278,4 @@ Summarize kernel blk_account_io_start() calls with a histogram of the I/O size.
- kprobe: As mentioned earlier, this is the kernel dynamic tracing probe type, which traces the entry of kernel functions (use kretprobe to trace their returns).
- ((struct request *)arg0)->__data_len: this casts arg0 as struct request *, then dereferences the __data_len field.
At this point you understand much of bpftrace, and can begin to use and write powerful one-liners. See the reference guide for more capabilities.
At this point you understand much of bpftrace, and can begin to use and write powerful one-liners. See the [Reference Guide](reference_guide.md) for more capabilities.
