DOKK / manpages / debian 11 / bpftrace / bpftrace.8.en
BPFTRACE(8) System Manager's Manual BPFTRACE(8)

bpftrace - the eBPF tracing language & frontend

bpftrace [OPTIONS] FILE
bpftrace [OPTIONS] -e 'program code'

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
  • BCC for interacting with the Linux BPF system

As well as the existing Linux tracing capabilities:

kernel userland
static tracepoints USDT* probes
dynamic kprobes uprobes

*USDT = user-level statically defined tracing

The bpftrace language is inspired by awk and C, and predecessor tracers such as DTrace and SystemTap.

See EXAMPLES and ONELINERS if you are impatient.
See PROBE TYPES and BUILTINS (variables/functions) for the bpftrace language elements.

List probes.
Execute PROGRAM.
Enable USDT probes on PID. Will terminate bpftrace on PID termination. Note this is not a global PID filter on probes.
Helper to run CMD. Equivalent to manually running CMD and then giving passing the PID to -p. This is useful to ensure you've traced at least the duration CMD's execution.
Enable unsafe builtin functions. By default, bpftrace runs in safe mode. Safe mode ensure programs cannot modify system state. Unsafe builtin functions are marked as such in BUILTINS (functions).
Force BTF data processing if it's available. By default it's enabled only if the user does not specify any types/includes.
Verbose messages.
Debug info on dry run.
Verbose debug info on dry run.

List probes containing "sleep".
Trace processes calling sleep.
run "sleep 5" in a new process and then trace processes calling sleep.
Count syscalls by process name.

For brevity, just the the actual BPF code is shown below.
Usage: bpftrace -e 'bpf-code'

tracepoint:syscalls:sys_enter_execve { join(args->argv); }
tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }
tracepoint:raw_syscalls:sys_enter { @[comm] = count(); }
tracepoint:syscalls:sys_enter_* { @[probe] = count(); }
tracepoint:raw_syscalls:sys_enter { @[pid, comm] = count(); }
tracepoint:syscalls:sys_exit_read /args->ret/ { @[comm] = sum(args->ret); }
tracepoint:syscalls:sys_exit_read { @[comm] = hist(args->ret); }
tracepoint:block:block_rq_issue { printf("%d %s %d\n", pid, comm, args->bytes); }
software:major-faults:1 { @[comm] = count(); }
software:faults:1 { @[comm] = count(); }
profile:hz:99 /pid == 189/ { @[ustack] = count(); }

Attach a bpftrace script to a kernel function, to be executed when that function is called:

kprobe:vfs_read { ... }

Attach script to a userland function:

uprobe:/bin/bash:readline { ... }

Attach script to a statically defined tracepoint in the kernel:

tracepoint:sched:sched_switch { ... }

Tracepoints are guaranteed to be stable between kernel versions, unlike kprobes.

Attach script to kernel software events, executing once every provided count or use a default:

software:faults:100 software:faults:

Attach script to hardware events (PMCs), executing once every provided count or use a default:

hardware:cache-references:1000000 hardware:cache-references:

Run the script on all CPUs at specified time intervals:

profile:hz:99 { ... }

profile:s:1 { ... }

profile:ms:20 { ... }

profile:us:1500 { ... }

Run the script once per interval, for printing interval output:

interval:s:1 { ... }

interval:ms:20 { ... }

A single probe can be attached to multiple events:

kprobe:vfs_read,kprobe:vfs_write { ... }

Some probe types allow wildcards to be used when attaching a probe:

kprobe:vfs_* { ... }

Define conditions for which a probe should be executed:

kprobe:sys_open / uid == 0 / { ... }

The following variables and functions are available for use in bpftrace scripts:

Process ID (kernel tgid)
Thread ID (kernel pid)
Cgroup ID of the current process
User ID
Group ID
Nanosecond timestamp
Processor ID
Process name
Kernel stack trace
User stack trace
Arguments to the function being traced
Return value from function being traced
Name of the function currently being traced
Full name of the probe
Current task_struct as a u64.
Random number of type u32.

Produce a log2 histogram of values of n
Produce a linear histogram of values of n
Count the number of times this function is called
Sum this value
Record the minimum value seen
Record the maximum value seen
Average this value
Return the count, average, and total for this value
Delete the map element passed in as an argument
Returns the string pointed to by s
Print formatted to stdout
Print a map, with optional top entry count and divisor
Delete all key/values from a map
Resolve kernel address
Resolve user space address
Resolve kernel symbol name
Resolve user space symbol name
Returns the value stored in the named register
Prints the string array
Print the current time
Print file content
Convert IP address data to text
Execute shell command
Quit bpftrace
Kernel stack trace
User stack trace

The official documentation can be found here:
https://github.com/iovisor/bpftrace/blob/master/docs

The first official talk by Alastair on bpftrace happened at the Tracing Summit in Edinburgh, Oct 25th 2018.

Created by Alastair Robertson.
Manpage by Stephan Schuberth.

man -k bcc, after having installed the bpfcc-tools package under Ubuntu.

Prior to contributing new tools, read the official checklist at:
https://github.com/iovisor/bpftrace/blob/master/CONTRIBUTING-TOOLS.md

October 2018