iovisor/bpftrace iovisor/bpftrace

  • Stars
    star
    7,587
  • Rank 5,064 (Top 0.1 %)
  • Language
    C++
  • License
    Apache License 2.0
  • Created about 6 years ago
  • Updated 10 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
iovisor/bpftrace
github

iovisor

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

High-level tracing language for Linux eBPF

bpftrace

Build Status IRC#bpftrace CodeQL

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 and makes use of BCC for interacting with the Linux BPF system, as well as existing Linux tracing capabilities: kernel dynamic tracing (kprobes), user-level dynamic tracing (uprobes), and tracepoints. The bpftrace language is inspired by awk and C, and predecessor tracers such as DTrace and SystemTap. bpftrace was created by Alastair Robertson.

To learn more about bpftrace, see the Manual the Reference Guide and One-Liner Tutorial.

We are also holding regular office hours open to the public.

One-Liners

The following one-liners demonstrate different capabilities:

# Files opened by process
bpftrace -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'

# Syscall count by program
bpftrace -e 'tracepoint:raw_syscalls:sys_enter { @[comm] = count(); }'

# Read bytes by process:
bpftrace -e 'tracepoint:syscalls:sys_exit_read /args->ret/ { @[comm] = sum(args->ret); }'

# Read size distribution by process:
bpftrace -e 'tracepoint:syscalls:sys_exit_read { @[comm] = hist(args->ret); }'

# Show per-second syscall rates:
bpftrace -e 'tracepoint:raw_syscalls:sys_enter { @ = count(); } interval:s:1 { print(@); clear(@); }'

# Trace disk size by process
bpftrace -e 'tracepoint:block:block_rq_issue { printf("%d %s %d\n", pid, comm, args->bytes); }'

# Count page faults by process
bpftrace -e 'software:faults:1 { @[comm] = count(); }'

# Count LLC cache misses by process name and PID (uses PMCs):
bpftrace -e 'hardware:cache-misses:1000000 { @[comm, pid] = count(); }'

# Profile user-level stacks at 99 Hertz, for PID 189:
bpftrace -e 'profile:hz:99 /pid == 189/ { @[ustack] = count(); }'

# Files opened, for processes in the root cgroup-v2
bpftrace -e 'tracepoint:syscalls:sys_enter_openat /cgroup == cgroupid("/sys/fs/cgroup/unified/mycg")/ { printf("%s\n", str(args->filename)); }'

More powerful scripts can easily be constructed. See Tools for examples.

Install

For build and install instructions, see INSTALL.md.

Tools

bpftrace contains various tools, which also serve as examples of programming in the bpftrace language.

For more eBPF observability tools, see bcc tools.

Probe types

See the Reference Guide for more detail.

Support

For additional help / discussion, please use our discussions page.

Contributing

Development

Docker

For build & test directly in docker

$ ./build.sh

For build in docker then test directly on host

$ ./build-static.sh
$ ./build-static/src/bpftrace
$ ./build-static/tests/bpftrace_test

Vagrant

For development and testing a Vagrantfile is available.

Make sure you have the vbguest plugin installed, it is required to correctly install the shared file system driver on the ubuntu boxes:

$ vagrant plugin install vagrant-vbguest

Start VM:

$ vagrant status
$ vagrant up $YOUR_CHOICE
$ vagrant ssh $YOUR_CHOICE

Nix

There is experimental support for building and testing with Nix flakes. The quickstart follows but more detailed documentation can be found in nix.md.

First, install nix: https://nixos.org/download.html. Then enable Nix flake support:

$ mkdir -p ~/.config/nix
$ echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Now build and run:

$ nix build
$ sudo ./result/bin/bpftrace --info

The above steps are theoretically guaranteed to work on any linux x86-64/arm system.

License

Copyright 2019 Alastair Robertson

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

More Repositories

1

bcc

BCC - Tools for BPF-based Linux IO analysis, networking, monitoring, and more
C
20,381
star
2

gobpf

Go bindings for creating BPF programs.
C
2,139
star
3

kubectl-trace

Schedule bpftrace programs on your kubernetes cluster using the kubectl
Go
2,038
star
4

bpf-docs

Presentations and docs
943
star
5

bpf-fuzzer

fuzzing framework based on libfuzzer and clang sanitizer
C
163
star
6

iovisor-ovn

IOVisor OVN integration
Go
67
star
7

iomodules

IOModule manager and plugins
Go
38
star
8

iovisor.github.io

Repo for GitHub Pages
HTML
2
star