Skip to content

bpftrace Reference

What this page covers

Look-up facts for bpftrace 0.27.x: release history, kernel/LLVM/library requirements, required kernel config, privileges, probe types, the standard library (builtins, functions, map value functions), config variables, environment variables, CLI flags, bundled tools, and packaging. Facts come from the upstream CHANGELOG.md, docs/language.md, docs/stdlib.md, docs/dependency_support.md, docs/release_process.md and the bpftrace(8) man page, checked 2026-09-25. For recipes see How-to Guides. For how the pieces fit together see Explanation.

Match the docs to your binary

The language changed a lot between 0.20 and 0.27. Distro packages often lag several minors behind. Run bpftrace --version and read the versioned docs for that release (bpftrace.org hosts per-release language and stdlib pages, for example docs/release_027/language).

Release History

bpftrace follows semantic versioning with 0.x minors. Dates are from the upstream CHANGELOG.md and were cross-checked against the bpftrace.org 0.26 and 0.27 release notes.

Version Date Headline changes
0.27.0 2026-09-10 str_concat(), container_of(), config builtin, reg("pc"), macro type-expression substitution; first static arm64 AppImage; release assets now suffixed by architecture; session probes fixed for kernel 7.0
0.26.1 2026-06-02 Fixes for session-probe retval/argN, self-probe listing, statement probes
0.26.0 2026-05-26 Off-cycle release. Imports (.bt, .h, .bpf.c) and the & address-of operator stabilized; dw_ustack() DWARF unwinding (x86_64, LLVM >= 21); uprobe source-location attach points; write_user() (needs --unsafe); signal_name(), leader_tid/leader_comm; breaking: pcomm now means the real parent, subtraction yields int64
0.25.1 2026-03-25 Crash and verifier fixes (strerror, invalid if), watchpoints attach to all threads
0.25.0 2026-03-13 Macros and map declarations stabilized; --probe-filter, --fmt, --traceable-functions; test and bench probes; records, find(), probetype, syscall_name(); capability check replaces root check; breaking: tracepoint args needs BTF, sarg removed, exit() banned in loops, GPL-compatible licenses only; while deprecated; LLVM 16/17 dropped
0.24.2 2025-12-12 Bug fixes (enum tracepoint args, BTF char arrays, printf ordering)
0.24.1 2025-10-03 Build fixes (gcc-16, Alpine)
0.24.0 2025-09-17 Hygienic macros and map declarations (unstable), tseries, booleans, duration literals, for ranges with break/continue, getopt(), blazesym symbolization, automatic kprobe session probes, fentry:bpf: for running BPF programs; breaking: most DWARF support dropped, rawtracepoints need BTF, BPF ring buffer required, attach failures are fatal by default, non-script output goes to stderr
0.23.0 2025-03-25 max_strlen default raised 64 -> 1024, LLVM 20, aarch64 AppImage from master; LLVM 14/15 dropped
0.22.0 2025-01-07 let declarations and block scoping, tuples as map keys, has_key(), --dry-run, self:signal: probes replace the SIGUSR1 map dump; pid/tid become uint32
0.21.0 2024-06-21 for loops over maps, missing_probes config, optional systemd support, LLVM 18
0.20.0 2024-01-22 fentry/fexit aliases for kfunc/kretfunc, new config = { ... } block syntax, kprobe:module:function, uprobe_multi

Release Cadence and Support

Item Fact
Cadence Two minor releases per year, about two weeks after each LLVM major release (LLVM ships in March and September)
Release branch Created about four weeks before release (release/0.Y.x), receives backported fixes
Patch releases As needed, at least one week apart
Support window Not published. Fixes land on the latest release branch; no LTS line (TBD, no upstream statement found)
Off-cycle releases 0.26.0 (2026-05) shipped outside the schedule because of fixes that were hard to backport

Requirements

Dependency Requirement (0.27.x) Notes
Linux kernel 6.1 minimum Policy: stable kernels plus the 4 most recent LTS kernels. 0.24.x and 0.25.x documented 5.15 as the minimum. Use an older bpftrace on older kernels
Kernel BTF CONFIG_DEBUG_INFO_BTF=y (4.18+); module BTF needs CONFIG_DEBUG_INFO_BTF_MODULES=y (5.11+) Required for fentry/fexit, rawtracepoint (since 0.24) and tracepoint args (since 0.25). Override the BTF file with BPFTRACE_BTF
BPF ring buffer BPF_MAP_TYPE_RINGBUF (kernel 5.8+) Required since 0.24.0
LLVM (dynamic link) 18 to 23 Policy: latest LLVM release plus 4 previous. 0.24 supported 16-21, 0.25/0.26 supported 18-22
LLVM (static build) One LLVM version only Source of truth is .github/include/static.sh
libbpf Vendored git submodule, linked statically by default -DUSE_SYSTEM_LIBBPF=On for distro builds; must be at or beyond the submodule commit
bcc (libbcc) Still REQUIRED at build time (find_package(LibBcc REQUIRED)) Residual use, for example the bpftrace-aotrt runtime build check and the uprobe refcount check reported by --info
libclang Required Parses C definitions, #include headers and imported .bpf.c files
blazesym Optional Enables address symbolization with file and line (show_debug_info)
C++ standard C++20 From CMakeLists.txt

Required Kernel Configuration

From docs/dependency_support.md. The scripts/check_kernel_features.sh script in the repo checks a host.

Option Why
CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y The bpf() syscall and BPF subsystem
CONFIG_BPF_JIT=y, CONFIG_HAVE_EBPF_JIT=y JIT compilation of loaded programs
CONFIG_BPF_EVENTS=y Attaching BPF to kprobes, uprobes and tracepoints
CONFIG_FTRACE_SYSCALLS=y syscalls:sys_enter_* / sys_exit_* tracepoints
CONFIG_FUNCTION_TRACER=y, CONFIG_HAVE_DYNAMIC_FTRACE=y, CONFIG_DYNAMIC_FTRACE=y Function tracing and available_filter_functions
CONFIG_HAVE_KPROBES=y, CONFIG_KPROBES=y, CONFIG_KPROBE_EVENTS=y kprobe / kretprobe
CONFIG_ARCH_SUPPORTS_UPROBES=y, CONFIG_UPROBES=y, CONFIG_UPROBE_EVENTS=y uprobe / uretprobe / usdt
CONFIG_DEBUG_FS=y Tracing filesystem access on kernels that expose it via debugfs

Privileges

Since 0.25.0 bpftrace checks for capabilities instead of requiring uid 0.

Capability Why bpftrace needs it
CAP_BPF Load programs and create maps (kernel 5.8+)
CAP_PERFMON Attach tracing programs (kprobes, uprobes, tracepoints, perf events)
CAP_DAC_READ_SEARCH Checked by bpftrace since 0.25
CAP_DAC_OVERRIDE Checked by bpftrace since 0.25
CAP_SYS_ADMIN Pre-5.8 kernels (outside the supported range for 0.27) and some attach paths

--unsafe is a separate opt-in for destructive helpers (system(), signal(), override(), write_user(), probing arbitrary files, probing functions reported as not traceable).

Supported Architectures

x86_64, arm64, arm, s390x, loongarch64, mips64, ppc64le, ppc64, riscv64 (docs/language.md). These are also the values of the compile-time arch builtin. Official static AppImage release assets exist for x86_64 and, since 0.27.0, arm64.

Probe Types

Full list from docs/language.md (0.27). Provider names are case-insensitive since 0.24, so BEGIN and begin are equivalent. Current docs use lowercase.

Probe Short Attach syntax Kernel mechanism Argument access
begin / end - begin, end bpftrace runtime -
self - self:signal:SIGUSR1 bpftrace runtime (signal to bpftrace) -
test - test:name (runs with --test) bpftrace runtime -
bench - bench:name (runs with --bench) bpftrace runtime -
kprobe / kretprobe k / kr kprobe[:module]:fn, fn+offset, kprobe:addr, kprobe@file:line[:col] kprobes, kprobe_multi and kprobe session links argN, retval
fentry / fexit f / fr fentry[:module]:fn, fentry:bpf[:prog_id]:prog_name BPF trampolines, needs BTF args.<name>, retval (in fexit)
rawtracepoint rt rawtracepoint[:module]:event raw tracepoints, needs BTF argN, args
tracepoint t tracepoint:subsys:event static kernel tracepoints args (needs BTF since 0.25)
uprobe / uretprobe u / ur uprobe:binary:func, func+offset, binary:offset, binary@file:line[:col] uprobes, uprobe_multi links argN, retval, args with DWARF
usdt U usdt:path:[namespace:]probe user static tracepoints (semaphores via uprobe refcount) argN (up to 255 since 0.24)
profile p profile:hz:99, profile:ms:10 perf events, fires on every CPU -
interval i interval:1s, interval:ms:100 perf events, fires on one CPU -
software s software:faults:100 perf software events -
hardware h hardware:cache-misses:1e6 PMC hardware events -
iter it iter:task, iter:task_file, iter:task_vma (optional :pin) BPF iterators (experimental) ctx
watchpoint w watchpoint:addr:len:mode hardware breakpoints -

Removed or renamed probe forms: kfunc/kretfunc are legacy aliases of fentry/fexit. Experimental watchpoint:func+arg and asyncwatchpoint were removed in 0.25.0.

Standard Library

Since 0.24 builtins, functions and macros are documented together in docs/stdlib.md as "helpers". Zero-argument helpers can be called with or without parentheses (pid equals pid()).

Common Builtins

Helper Returns
pid, tid Process and thread ID (uint32 since 0.22). pid(init) / tid(init) give the initial-namespace IDs
ppid, pcomm, leader_tid, leader_comm Parent and thread-group-leader identity (pcomm = real parent since 0.26)
uid, gid, username, cgroup, cgroup_path() Credentials and cgroup
comm Process name (also comm(pid) since 0.25)
cpu, ncpus, numaid CPU and NUMA placement
nsecs, elapsed, jiffies Time sources
kstack, ustack, dw_ustack() Kernel and user stacks (dw_ustack is unstable, x86_64, LLVM >= 21)
func, probe, probetype Current function, probe name and probe type
args, argN, retval, reg("pc") Probe arguments, return value, registers
curtask Pointer to the current struct task_struct
cpid, has_cpid PID of the -c child command
arch Compile-time architecture string (unreleased as of 0.27.0)

Common Functions

Function Purpose Notes
printf(), print(), errorf(), warnf() Output printf/print are async (handled in user space)
str(), buf(), path() Read strings, buffers, paths Sized by max_strlen unless a size is passed
strftime() Format a timestamp async
ksym(), usym() Symbolize addresses async
kaddr(), uaddr() Resolve a symbol to an address kaddr is compile time
ntop(), pton(), macaddr(), socket_cookie() Networking helpers pton is compile time
strcontains(), strncmp(), str_concat(), strerror(), signal_name(), syscall_name() String helpers str_concat since 0.27
getopt() Named script arguments passed after -- Since 0.24
clear(), zero(), exit() Reset maps, stop tracing async
delete(), has_key(), find(), len() Map access find since 0.25
container_of(), offsetof(), sizeof(), typeof() Type helpers container_of since 0.27
system(), signal(), override(), write_user() Destructive actions Need --unsafe

Map Value Functions

Map value functions can only be assigned to a map or map key. count, sum, avg, min, max and stats use per-CPU storage.

Function Signature Output
count() count_t count() Event count
sum() sum_t sum(int64 n) Running sum
avg() avg_t avg(int64 n) Running average (count and total kept, divided in user space)
min() / max() min_t min(int64 n) / max_t max(int64 n) Extremes
stats() stats_t stats(int64 n) Count, average and total (fields .count, .total, .avg accessible in the unreleased branch)
hist() hist_t hist(int64 n[, int k]) Log2 histogram, 2^k buckets per power of 2, 0 <= k <= 5
lhist() lhist_t lhist(int64 n, int64 min, int64 max, int64 step) Linear histogram with under/overflow buckets
tseries() tseries(int64 n, int64 interval_ns, int64 num_intervals[, string agg]) Time series, agg is avg, max, min or sum (unstable, unstable_tseries)

Invocation Modes

Mode Meaning Examples
Synchronous Runs in the BPF program in kernel context reg(), str(), ntop()
Asynchronous Event sent to user space and handled later by the bpftrace process printf(), print(), clear(), exit()
Compile-time Value fixed before programs run kaddr(), cgroupid(), offsetof()

Map Declaration Types

let @name = <type>(max_entries); before any probe. The changelog marks map declarations stable since 0.25.0, although docs/language.md still carries an "experimental" warning.

Declaration BPF map type
hash(n) BPF_MAP_TYPE_HASH
lruhash(n) BPF_MAP_TYPE_LRU_HASH
percpuhash(n) BPF_MAP_TYPE_PERCPU_HASH
percpulruhash(n) BPF_MAP_TYPE_LRU_PERCPU_HASH

Undeclared maps use max_map_keys (default 4096) entries.

Config Variables

Set in a config = { ... } block at the top of a script, or with the BPFTRACE_<NAME> environment variable (environment wins).

Variable Default Purpose
max_strlen 1024 Size of values from str(), buf(), path() (was 64 before 0.23)
max_map_keys 4096 Entries per undeclared map
max_probes 1024 Maximum attached probes
max_bpf_progs 1024 Maximum generated BPF programs
max_cat_bytes 10240 Bytes read by cat()
missing_probes error error, warn or ignore probes that fail to attach
on_stack_limit 32 Objects larger than this (bytes) move off the 512-byte BPF stack
perf_rb_pages Based on system memory (64 to 4096 pages) Ring/perf buffer size
stack_mode bpftrace bpftrace, perf, raw, build_id (ustack only)
print_maps_on_exit true Print non-empty maps when bpftrace exits
license "GPL" BPF program license; only GPL-compatible strings accepted since 0.25
cache_user_symbols PER_PID (or PER_PROGRAM with ASLR off or -c) User symbol cache scope
lazy_symbolication false Symbolize user addresses on demand
cpp_demangle true Demangle C++ symbols in stacks
show_debug_info true when built with blazesym Add file and line to stacks
str_trunc_trailer .. Suffix for truncated strings
log_size 1000000 Verifier log buffer size (bytes)
unstable_tseries, unstable_dw_ustack warn Feature flags: error, warn, enable

Environment Variables

Variable Purpose
BPFTRACE_BTF Path to a BTF file (useful on kernels without /sys/kernel/btf/vmlinux)
BPFTRACE_KERNEL_SOURCE / BPFTRACE_KERNEL_BUILD Kernel header location (default /lib/modules/$(uname -r))
BPFTRACE_VMLINUX vmlinux path for kprobe offset resolution
BPFTRACE_COLOR auto, always, never for log colors
CPATH, C_INCLUDE_PATH Honored by libclang for header search

CLI Options

From bpftrace --help and bpftrace(8) on the master branch (2026-09).

Option Purpose
-e 'program' Run an inline program
-l [search\|file], -lv List probes (with -v: argument types, struct layouts)
-p PID, -c CMD Target a process or spawn a child (cpid)
-o FILE, -f text\|json, -B line\|full\|none Output file, format (NDJSON), buffering
-q, -v, -k, --no-warnings Quiet, verbose, probe-read error warnings, suppress warnings
-I DIR, --include FILE C header search and forced includes
--info Kernel and build feature report
--dry-run Load and attach, then exit (since 0.22)
-d STAGE Debug output: ast, types, codegen, codegen-opt, libbpf, verifier, all
--emit-elf FILE, --emit-llvm FILE Dump the BPF ELF or LLVM IR
--unsafe Allow destructive helpers
--no-feature F[,F] Disable uprobe_multi, kprobe_multi, kprobe_session
--probe-filter REGEX Only load probes whose name matches (since 0.25)
--traceable-functions FILE Replace available_filter_functions (since 0.25)
--debuginfo DIR[:DIR] DWARF search path
--usdt-file-activation Activate USDT semaphores by file path
--test, --bench, --fmt Run test: probes, run bench: probes, format a script
--aot FILE Undocumented: emit an ahead-of-time artifact for the version-locked bpftrace-aotrt runtime

Bundled Tools

The repo tools/ directory ships 38 maintained scripts (0.27 list). Community tools moved to the separate bpftrace/user-tools repo. Versioned copies live on release/0.Y.x branches.

Area Tools
Block I/O biolatency.bt, biosnoop.bt, biostacks.bt, bitesize.bt, mdflush.bt
CPU and scheduler cpuwalk.bt, runqlat.bt, runqlen.bt, loads.bt
Processes and signals execsnoop.bt, pidpersec.bt, threadsnoop.bt, killsnoop.bt, naptime.bt, oomkill.bt
Files and VFS opensnoop.bt, statsnoop.bt, syncsnoop.bt, dcsnoop.bt, vfscount.bt, vfsstat.bt, writeback.bt, xfsdist.bt, swapin.bt
Networking tcpaccept.bt, tcpconnect.bt, tcpdrop.bt, tcplife.bt, tcpretrans.bt, tcpsynbl.bt, gethostlatency.bt, undump.bt
Security and TLS capable.bt, setuids.bt, ssllatency.bt, sslsnoop.bt, bashreadline.bt
Syscalls syscount.bt

Packaging

Platform Install command Notes
Debian / Ubuntu sudo apt install bpftrace LTS releases lag upstream; check bpftrace --version
Fedora / CentOS Stream 9-10 sudo dnf install bpftrace CentOS ships it in CRB
Alpine sudo apk add bpftrace
Arch Linux sudo pacman -S bpftrace extra repository
Gentoo sudo emerge -av bpftrace dev-util/bpftrace
NixOS / nixpkgs nix-shell -p bpftrace A nixpkgs update PR to 0.27.0 was opened in September 2026
openSUSE Tumbleweed sudo zypper install bpftrace
Any Linux (x86_64, arm64) Static AppImage from GitHub Releases, or nightly from CI Assets suffixed by architecture since 0.27.0

Breaking Changes Checklist

Quick scan when upgrading old scripts. See the upstream migration guide.

  • 0.22: scratch variables are block scoped. Declare with let $x; before an if.
  • 0.22: delete(@m, key) takes the map and key separately; multi-key delete removed.
  • 0.22: pid/tid are uint32. Cast before mixing with 64-bit values.
  • 0.22: SIGUSR1 no longer dumps maps. Add a self:signal:SIGUSR1 { print(@m); } probe.
  • 0.24: any attach failure is an error. Set missing_probes = "warn" for best-effort wildcards.
  • 0.24: strcontains() and has_key() return bool; non-script messages go to stderr.
  • 0.25: tracepoint args needs BTF (or BPFTRACE_BTF=<file>).
  • 0.25: sarg removed, exit() not allowed in loops, while deprecated (use for ($i : 0..N)).
  • 0.26: pcomm is the real parent's comm; subtraction results are signed int64.

Sources