bpftrace: High-level tracing language for Linux
bpftrace [OPTIONS] FILENAME
bpftrace [OPTIONS] -e 'program'
What it does
bpftrace compiles a short program (probe /filter/ { action }) into eBPF, attaches it and runs until the program calls exit() or you press Ctrl+C, then prints its maps. Probes: tracepoint:, kprobe:/kretprobe:, fentry:/fexit:, uprobe:/uretprobe:, usdt:, profile:hz:N, interval:s:N, software:, hardware:, begin, end. Runs as root.
Options you will use
-e 'program'- execute this program.
-l [search]- list probes matching the search (wildcards): -l 'tracepoint:syscalls:open'.
-lv- list probes with their arguments (args.NAME).
-p PID- enable USDT probes on this PID; pid filters still need /pid == N/.
-c 'CMD'- run CMD and trace it, then exit.
-o file- write the output to a file.
-q- keep messages quiet ("Attached N probes" goes away).
-f FORMAT- output format: text or json.
--dry-run- check and compile the program but do not run it.
-V, --version- bpftrace version.
-h, --help- show the help.
Examples
$ sudo bpftrace -e 'tracepoint:syscalls:sys_enter_openat { @[comm, str(args.filename)] = count(); }'files opened, by process and path
$ sudo bpftrace -e 'tracepoint:syscalls:sys_exit_read /args.ret > 0/ { @[comm] = hist(args.ret); }'read sizes per process
$ sudo bpftrace -e 'profile:hz:99 { @[comm] = count(); }'which processes are on CPU
$ sudo bpftrace -l 'tracepoint:sched:*'list scheduler tracepoints
Gotchas
- Maps (@name) are printed at exit and on Ctrl+C. count(), sum(), avg(), min(), max(), hist(), lhist() aggregate in the kernel.
- str(args.filename) copies a user-space string; without str() you get the pointer.
- kprobe function names change between kernel versions; prefer tracepoints.
- Errors point at the program: stdin:LINE:COLUMN, with the line and a caret.
Taught in
On the blog
Try bpftrace in a real terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.