eBPF is an emerging Linux kernel technology that allows for user-supplied programs to run inside of the kernel. This enables a bunch of interesting usecases, particularly efficient CPU profiling of the whole Linux system.

Supported platforms

Spy NameTypeLinuxmacOSWindowsDocker


For this to work you'll need

  • a Linux machine with the kernel version >= 4.9.
  • BCC tools installed on the system you want to profile. Visit BCC documentation to find the best way of installing it on your system. There are prebuilt binaries available for most flavors of Linux.
  • pyroscope server and agent. Visit our Getting Started guide to learn about that.

Running eBPF profiler

export PYROSCOPE_APPLICATION_NAME=my.ebpf.program
export PYROSCOPE_SERVER_ADDRESS=http://address-of-pyroscope-server:4040/
export PYROSCOPE_SPY_NAME=ebpfspy
# to wrap an existing program and profile it
sudo -E pyroscope exec mongod
# to profile the whole system, pass -1 as pid
sudo -E pyroscope connect -pid -1

Dealing with [unknowns]

eBPF relies on having debugging symbols available for each program installed in your system. If you don't have those you'll see a lot of stacktraces full of [unknown]s. On most systems you can get debugging symbols for most packages with debuginfo-install command:

sudo debuginfo-install -y <pkg>

Future of our eBPF integration

One thing we're excited about at Pyroscope is eBPF portability efforts, particularly introduction of BTF (BPF Type Format) technology. You can read more about that here. When kernels with BTF support become more mainstream we're gonna embed libbpf directly into our go binary.