.
.TH "BPFTRACE" "8" "October 2018"
.
.SH "NAME"
\fBbpftrace\fR \- the eBPF tracing language & frontend
.
.SH "SYNOPSIS"
bpftrace [\fIOPTIONS\fR] \fIFILE\fR
.
.br
bpftrace [\fIOPTIONS\fR] \-e 'program code'
.
.SH "DESCRIPTION"
bpftrace is a high\-level tracing language for Linux enhanced Berkeley Packet Filter (eBPF) available in recent Linux kernels (4\.x)\.
.
.P
bpftrace uses:
.
.IP "\(bu" 4
\fILLVM\fR as a backend to compile scripts to BPF\-bytecode
.
.IP "\(bu" 4
\fIBCC\fR for interacting with the Linux BPF system
.
.IP "" 0
.
.P
As well as the existing Linux tracing capabilities:
.
.TS
tab(@) allbox;
ccc.
       @kernel@userland
 static@\fItracepoints@USDT\fR* probes
 dynamic@\fIkprobes@uprobes\fR
.TE
.
.P
.
*USDT = user-level statically defined tracing
.
.P
The bpftrace language is inspired by awk and C, and predecessor tracers such as DTrace and SystemTap\.
.
.P
See \fBEXAMPLES\fR and \fBONELINERS\fR if you are impatient\.
.
.br
See \fBPROBE TYPES\fR and \fBBUILTINS (variables/functions)\fR for the bpftrace language elements\.
.
.SH "OPTIONS"
.
.TP
\fB\-l [searchterm]\fR
List probes.
.
.TP
\fB\-e 'PROGRAM'\fR
Execute PROGRAM.
.
.TP
\fB\-p PID\fR
Enable USDT probes on PID. Will terminate bpftrace on PID termination. Note this is not a global PID filter on probes.
.
.TP
\fB\-c CMD\fR
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.
.
.TP
\fB\--unsafe\fR
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 \fBBUILTINS (functions)\fR.
.
.TP
\fB\--btf\fR
Force BTF data processing if it's available. By default it's enabled only if the user does not specify any types/includes.
.
.TP
\fB\-v\fR
Verbose messages.
.
.TP
\fB\-d\fR
Debug info on dry run.
.
.TP
\fB\-dd\fR
Verbose debug info on dry run.
.
.SH "EXAMPLES"
.
.TP
\fBbpftrace \-l '*sleep*'\fR
List probes containing "sleep".
.
.TP
\fBbpftrace \-e 'kprobe:do_nanosleep { printf("PID %d sleeping\en", pid); }'\fR
Trace processes calling sleep.
.
.TP
\fBbpftrace \-c 'sleep 5' \-e 'kprobe:do_nanosleep { printf("PID %d sleeping\en", pid); }'\fR
run "sleep 5" in a new process and then trace processes calling sleep.
.
.TP
\fBbpftrace \-e 'tracepoint:raw_syscalls:sys_enter { @[comm]=count(); }'\fR
Count syscalls by process name.
.
.SH "ONELINERS"
For brevity, just the the actual BPF code is shown below\.
.
.br
Usage: \fBbpftrace \-e 'bpf\-code'\fR
.
.TP
New processes with arguments:
\fBtracepoint:syscalls:sys_enter_execve { join(args\->argv); }\fR
.
.TP
Files opened by process:
\fBtracepoint:syscalls:sys_enter_open { printf("%s %s\en", comm, str(args\->filename)); }\fR
.
.TP
Syscall count by program:
\fBtracepoint:raw_syscalls:sys_enter { @[comm] = count(); }\fR
.
.TP
Syscall count by syscall:
\fBtracepoint:syscalls:sys_enter_* { @[probe] = count(); }\fR
.
.TP
Syscall count by process:
\fBtracepoint:raw_syscalls:sys_enter { @[pid, comm] = count(); }\fR
.
.TP
Read bytes by process:
\fBtracepoint:syscalls:sys_exit_read /args\->ret/ { @[comm] = sum(args\->ret); }\fR
.
.TP
Read size distribution by process:
\fBtracepoint:syscalls:sys_exit_read { @[comm] = hist(args\->ret); }\fR
.
.TP
Disk size by process:
\fBtracepoint:block:block_rq_issue { printf("%d %s %d\en", pid, comm, args\->bytes); }\fR
.
.TP
Pages paged in by process:
\fBsoftware:major\-faults:1 { @[comm] = count(); }\fR
.
.TP
Page faults by process:
\fBsoftware:faults:1 { @[comm] = count(); }\fR
.
.TP
Profile user\-level stacks at 99 Hertz, for PID 189:
\fBprofile:hz:99 /pid == 189/ { @[ustack] = count(); }\fR
.
.SH "PROBE TYPES"
.
.SS "KPROBES"
Attach a bpftrace script to a kernel function, to be executed when that function is called:
.
.P
\fBkprobe:vfs_read { \.\.\. }\fR
.
.SS "UPROBES"
Attach script to a userland function:
.
.P
\fBuprobe:/bin/bash:readline { \.\.\. }\fR
.
.SS "TRACEPOINTS"
Attach script to a statically defined tracepoint in the kernel:
.
.P
\fBtracepoint:sched:sched_switch { \.\.\. }\fR
.
.P
Tracepoints are guaranteed to be stable between kernel versions, unlike kprobes\.
.
.SS "SOFTWARE"
Attach script to kernel software events, executing once every provided count or use a default:
.
.P
\fBsoftware:faults:100\fR \fBsoftware:faults:\fR
.
.SS "HARDWARE"
Attach script to hardware events (PMCs), executing once every provided count or use a default:
.
.P
\fBhardware:cache\-references:1000000\fR \fBhardware:cache\-references:\fR
.
.SS "PROFILE"
Run the script on all CPUs at specified time intervals:
.
.P
\fBprofile:hz:99 { \.\.\. }\fR
.
.P
\fBprofile:s:1 { \.\.\. }\fR
.
.P
\fBprofile:ms:20 { \.\.\. }\fR
.
.P
\fBprofile:us:1500 { \.\.\. }\fR
.
.SS "INTERVAL"
Run the script once per interval, for printing interval output:
.
.P
\fBinterval:s:1 { \.\.\. }\fR
.
.P
\fBinterval:ms:20 { \.\.\. }\fR
.
.SS "MULTIPLE ATTACHMENT POINTS"
A single probe can be attached to multiple events:
.
.P
\fBkprobe:vfs_read,kprobe:vfs_write { \.\.\. }\fR
.
.SS "WILDCARDS"
Some probe types allow wildcards to be used when attaching a probe:
.
.P
\fBkprobe:vfs_* { \.\.\. }\fR
.
.SS "PREDICATES"
Define conditions for which a probe should be executed:
.
.P
\fBkprobe:sys_open / uid == 0 / { \.\.\. }\fR
.
.SH "BUILTINS"
The following variables and functions are available for use in bpftrace scripts:
.
.SS "VARIABLES"
.
.TP
\fBpid\fR
Process ID (kernel tgid)
.
.TP
\fBtid\fR
Thread ID (kernel pid)
.
.TP
\fBcgroup\fR
Cgroup ID of the current process
.
.TP
\fBuid\fR
User ID
.
.TP
\fBgid\fR
Group ID
.
.TP
\fBnsecs\fR
Nanosecond timestamp
.
.TP
\fBcpu\fR
Processor ID
.
.TP
\fBcomm\fR
Process name
.
.TP
\fBkstack\fR
Kernel stack trace
.
.TP
\fBustack\fR
User stack trace
.
.TP
\fBarg0\fR, \fBarg1\fR, \.\.\. etc\.
Arguments to the function being traced
.
.TP
\fBretval\fR
Return value from function being traced
.
.TP
\fBfunc\fR
Name of the function currently being traced
.
.TP
\fBprobe\fR
Full name of the probe
.
.TP
\fBcurtask\fR
Current task_struct as a u64\.
.
.TP
\fBrand\fR
Random number of type u32\.
.
.SS "FUNCTIONS"
.
.TP
\fBhist(int n)\fR
Produce a log2 histogram of values of \fBn\fR
.
.TP
\fBlhist(int n, int min, int max, int step)\fR
Produce a linear histogram of values of \fBn\fR
.
.TP
\fBcount()\fR
Count the number of times this function is called
.
.TP
\fBsum(int n)\fR
Sum this value
.
.TP
\fBmin(int n)\fR
Record the minimum value seen
.
.TP
\fBmax(int n)\fR
Record the maximum value seen
.
.TP
\fBavg(int n)\fR
Average this value
.
.TP
\fBstats(int n)\fR
Return the count, average, and total for this value
.
.TP
\fBdelete(@x)\fR
Delete the map element passed in as an argument
.
.TP
\fBstr(char *s)\fR
Returns the string pointed to by \fBs\fR
.
.TP
\fBprintf(char *fmt, \.\.\.)\fR
Print formatted to stdout
.
.TP
\fBprint(@x[, int top [, int div]])\fR
Print a map, with optional top entry count and divisor
.
.TP
\fBclear(@x)\fR
Delete all key/values from a map
.
.TP
\fBksym(void *p)\fR
Resolve kernel address
.
.TP
\fBusym(void *p)\fR
Resolve user space address
.
.TP
\fBkaddr(char *name)\fR
Resolve kernel symbol name
.
.TP
\fBuaddr(char *name)\fR
Resolve user space symbol name
.
.TP
\fBreg(char *name)\fR
Returns the value stored in the named register
.
.TP
\fBjoin(char *arr[])\fR
Prints the string array
.
.TP
\fBtime(char *fmt)\fR
Print the current time
.
.TP
\fBcat(char *filename)\fR
Print file content
.
.TP
\fBntop([int af, ]int|char[4|16] addr)\fR
Convert IP address data to text
.
.TP
\fBsystem(char *fmt)\fR (unsafe)
Execute shell command
.
.TP
\fBexit()\fR
Quit bpftrace
.
.TP
\fBkstack([StackMode mode, ][int level])\fR
Kernel stack trace
.
.TP
\fBustack([StackMode mode, ][int level])\fR
User stack trace
.
.SH "FURTHER READING"
The official documentation can be found here:
.
.br
https://github\.com/iovisor/bpftrace/blob/master/docs
.
.SH "HISTORY"
The first official talk by Alastair on bpftrace happened at the Tracing Summit in Edinburgh, Oct 25th 2018\.
.
.SH "AUTHOR"
Created by Alastair Robertson\.
.
.br
Manpage by Stephan Schuberth\.
.
.SH "SEE ALSO"
\fBman \-k bcc\fR, after having installed the \fIbpfcc\-tools\fR package under Ubuntu\.
.
.SH "CONTRIBUTING"
Prior to contributing new tools, read the official checklist at:
.
.br
https://github\.com/iovisor/bpftrace/blob/master/CONTRIBUTING\-TOOLS\.md