bpftrace — High-Level Tracing Language for Linux eBPF

Introduction

bpftrace is a high-level tracing language for Linux that makes eBPF accessible through concise one-liners and short scripts. Inspired by awk and DTrace, it lets you probe kernel functions, tracepoints, and user-space programs with minimal effort. Created by Alastair Robertson and maintained by the bpftrace community, it is the go-to tool for ad-hoc performance investigation on Linux.

What bpftrace Does

• Traces kernel functions (kprobes), user-space functions (uprobes), and tracepoints
• Aggregates data into histograms, counts, and statistics with built-in map types
• Prints stack traces, function arguments, and return values in real time
• Supports one-liners for quick debugging and multi-line scripts for complex analysis
• Compiles scripts to eBPF bytecode at runtime using LLVM

Architecture Overview

bpftrace parses its awk-like scripting language into an AST, then compiles it via LLVM into eBPF bytecode. The bytecode is loaded into the kernel's eBPF virtual machine, which verifies safety before attaching to the specified probe points. Data flows from kernel probes through eBPF maps (hash maps, histograms, stacks) back to user space where bpftrace formats and displays results. The entire lifecycle is managed automatically when the script exits.

Self-Hosting & Configuration

• Install via package manager: apt install bpftrace (Ubuntu 20.04+) or dnf install bpftrace (Fedora)
• Requires Linux kernel 4.9+ with BTF (BPF Type Format) support for best results
• Run as root or with CAP_BPF and CAP_PERFMON capabilities
• No configuration files or daemons needed; scripts run standalone
• Use bpftrace -l to list available tracepoints, kprobes, and uprobes on the system

Key Features

• One-liner friendly: solve performance questions in a single command
• Built-in variables: comm (process name), pid, tid, nsecs, kstack, ustack
• Map aggregations: count(), sum(), avg(), hist(), lhist() for real-time statistics
• BTF support: access kernel struct fields by name without manual offset calculations
• Wildcard probes: attach to multiple functions with patterns like kprobe:tcp_*

Comparison with Similar Tools

• BCC — Python-based eBPF toolkit; bpftrace is faster for ad-hoc one-liners
• perf — Sampling profiler; bpftrace does event-driven tracing with richer aggregation
• SystemTap — Requires kernel modules; bpftrace uses in-kernel eBPF for safety
• DTrace — bpftrace's spiritual ancestor; DTrace on Linux is less mature
• ftrace — Kernel built-in tracer; bpftrace provides a friendlier scripting interface

FAQ

Q: How is bpftrace different from BCC? A: bpftrace uses a concise scripting language ideal for one-liners and quick investigations. BCC uses Python for more complex programs that need custom data structures or long-running agents.

Q: Does bpftrace work in containers? A: Yes, with privileged mode or appropriate capabilities. The host kernel must support eBPF and the container needs access to kernel headers or BTF data.

Q: What is BTF and why does it matter? A: BTF (BPF Type Format) embeds kernel type information so bpftrace can access struct fields by name. Without BTF you need kernel headers installed; with BTF, scripts are more portable.

Q: Can bpftrace trace user-space applications? A: Yes. Use uprobes to trace functions in any ELF binary, and USDT probes for applications that define static tracepoints (like Python, Ruby, or Node.js).

Sources

• https://github.com/bpftrace/bpftrace
• https://bpftrace.org/docs