Anatomy of a bpftrace One-Liner

01 The shape: when / if / do

Last lesson you followed an eBPF program from your one-liner all the way into the kernel and back. Now we slow down and read the one-liner itself. The good news for an app developer: there's almost nothing to memorize. A bpftrace program is always the same tiny shape, repeated.

probe /filter/ { action }
  ▲          ▲           ▲
  WHEN       IF          DO

Source: bpftrace language reference — "each action block consists of three parts: an optional name, an optional predicate, and an action."

02 Dissecting the Lesson 1 one-liner

Here is the exact one-liner from Lesson 1 — the one that prints every file every process opens. Let's pull it apart completely. By the end of this section you'll be able to read it out loud as plain English.

sudo bpftrace -e 'tracepoint:syscalls:sys_enter_openat' /* no filter */ '{ printf("%s opened %s\n", comm, str(args->filename)); }'

Said as English: “Every time any process enters the openat syscall, print the process name and the filename it's opening.” That maps exactly onto WHEN / (no IF) / DO. Here is the same program laid out as three labeled zones:

Everything else in this lesson is just zooming into each of those three zones, plus the small vocabulary (comm, args, str()) that lives inside them.

03 The probe — and the type:target name

A probe names the event. Every probe name is a colon-separated string that starts with a probe type (which kind of event) followed by a target (which specific one):

tracepoint:syscalls:sys_enter_openat
    ▲            ▲              ▲
   type      category       the event
 (what kind)         (the specific target)

The first segment — tracepoint here — is the type. It answers “what category of hook is this?” The rest is the target: the exact event of that type. A few you'll meet:

Source: bpftrace language reference — probe naming (provider/type then colon-separated target).

04 The filter (predicate) — the “IF”

A probe like tracepoint:syscalls:sys_enter_openat fires for every process on the box — that can be a firehose. The filter (officially the predicate) is a condition wrapped in slashes that runs before the action and decides whether to bother:

tracepoint:syscalls:sys_enter_openat /comm == "bash"/ { printf("%s\n", str(args->filename)); }
                                      ▲ only when this is true does the action run

The expression inside the slashes is ordinary boolean logic over the builtins you'll meet next. Common shapes:

• /pid == 1234/ — only this one process
• /comm == "bash"/ — only processes named bash (string literals use double quotes)
• /uid == 0/ — only things running as root
• /pid != 4242 && uid > 1000/ — combine with &&, ||, !

Source: bpftrace language reference — predicate example /comm == "bash"/.

05 The action block & printf

The action is the code in { … }. For tracing, by far the most common action is printf — and it works just like C's (or Python's f-strings, or Go's fmt.Printf): a format string with % placeholders, followed by the values to fill them in, left to right.

printf("%-6d %-16s opened %s\n", pid, comm, str(args->filename));
         │    │     │            │    │           │
         %d ← pid  │            │    comm        str(...) ← filename
              %s ← (none here; %s slots fill in order)

The placeholders you'll use 95% of the time:

Source: bpftrace stdlib — printf "behaves similar to printf() found in C."

06 The builtins you'll use constantly

Inside a filter or action, you don't have to fetch data — bpftrace hands you a set of builtin variables describing “who/what/when” for the event that just fired. These are the words that make one-liners short. Memorize the top handful; the rest you'll look up.

Source: bpftrace stdlib — builtin variables reference.

07 Functions — printf, str(), and a peek at aggregation

Builtins are nouns; functions are verbs you call inside the action. You've met printf. The other one you'll reach for immediately is str().

str() — turn a pointer into readable text

Many event arguments aren't strings — they're pointers to where a string lives in memory (that's how the kernel passes a filename). str() safely reads the bytes at that address up to the terminating NUL and gives you back actual text:

str(args->filename)   // pointer → "/etc/passwd"

A peek at count() and hist()

Printing is great for “show me each event.” But for “how often” or “what's the distribution,” you summarize instead with aggregation functions stored in @ maps:

# count opens per process name
sudo bpftrace -e 'tracepoint:syscalls:sys_enter_openat' '{ @[comm] = count(); }'

# histogram of read() sizes
sudo bpftrace -e 'tracepoint:syscalls:sys_exit_read' '{ @bytes = hist(args->ret); }'

Source: bpftrace one-liner tutorial — str(), count(), hist().

08 Running it: one-liners, scripts, listing, BEGIN/END

-e one-liners vs .bt script files

Two ways to run the exact same program. For something throwaway, pass it inline with -e. When it grows past a line or two — multiple probes, comments — put it in a .bt file and run that:

# inline, throwaway
sudo bpftrace -e 'tracepoint:syscalls:sys_enter_openat { printf("%s %s\n", comm, str(args->filename)); }'

# saved as opensnoop.bt, then run the file
sudo bpftrace opensnoop.bt

Finding probes with -l

You rarely know a probe's exact name by heart. -l lists probes, and * is a wildcard — so it doubles as search. This is how you discover what you can hook:

# every syscall-entry tracepoint
sudo bpftrace -l 'tracepoint:syscalls:sys_enter_*'

# anything mentioning "open"
sudo bpftrace -l '*open*'

The special BEGIN and END probes

Two probes don't correspond to a kernel event at all. BEGIN fires once, before tracing starts; END fires once, after you hit Ctrl-C. Perfect for a header line or a closing summary:

sudo bpftrace -e 'BEGIN { printf("Tracing opens... Ctrl-C to end.\n"); }
tracepoint:syscalls:sys_enter_openat { @[comm] = count(); }
END { printf("done\n"); }'

Source: bpftrace one-liner tutorial — listing with -l, BEGIN { printf(...) }.

09 Check yourself

10 Flashcards