Repository files navigation

Linux Kernel eBPF Collectors

The respository has the following directory structure:

• artifacts: directory that will have the eBPF programs when the compilationprocess ends.
• co-re: contains all eBPF programs that utilize eBPF CO-RE (Compile Once -Run Everywhere) technology.
  • tests: contains test cases for our eBPF CO-RE programs.
• docs: contains an assortment of documentation related to this repository.
• includes: headers used throughout the project.
• kernel: contains all eBPF programs that don't utilize eBPF CO-REtechnology; these may be considered legacy more and more as time progressesand we shift fully to CO-RE.
• kernel-patches: contains patches needed to properly compile our legacykernel/ eBPF programs on some kernel versions.
• libbpf: this is a submodule'd fork ofnetdata/libbpf which is itself a fork ofthe officiallibbpf package, the user-space side of eBPF system calls.
• tools: scripts used to verify system status before installing eBPF code.

To compile the eBPF programs, it will be necessary to have the followingpackages:

• libelf headers
• LLVM/Clang; this is because GCC prior to 10.0 cannot compile eBPF code.
• Kernel headers

libbpf directory is included as a git submodule and it is necessary to fetch contents with the git command below:

git submodule update --init --recursive

Kernel headers can be extracted directly from the kernel source doing thefollowing steps (assumes your kernel source is accessible at/usr/src/linux):

cd /usr/src/linuxmake defconfigmake scriptsmake preparemake headers_install

In case you are using the kernel5.4 or newer, please comment out thefollowing line inside the filegenerated/autoconf.h:

#defineCONFIG_CC_HAS_ASM_INLINE 1

It's also possible that you'll need to change theMakefiles in thisrepository according your environment. The original files were adjusted tocompile on Slackware Linux Current.

Insidekernel/Makefile, you may need to change the following variables:

• KERNELSOURCE: Where is your kernel-source? This variable was set initiallyto work on Slackware, Fedora and Ubuntu.
• LINUXINCLUDE: Depending on the Linux distribution, it may be necessary toadd or remove directories from this variable.
• LLVM_INCLUDES: Depending on the kernel version, it may be necessary tochange this path.

There are two build environments that produce different variants of libc andthe Linux Kernel.

The build environments are:

• musl =>Dockerfile.musl (based on Alpine 3.11)
• glibc =>Dockerfile.glibc.generic (based on Ubuntu 20.04)

$ docker build -f Dockerfile.glibc.generic -t kernel-collector:glibc ./$ docker run --rm -v$PWD:/kernel-collector kernel-collector:glibc

$ docker build -f Dockerfile.musl -t kernel-collector:musl ./$ docker run --rm -v$PWD:/kernel-collector kernel-collector:musl

To build for a different Kernel version rather than the default just pass the--build-arg KERNEL_VERSION=<kernel_version> argument to thedocker build.

For example:

$ docker build -f Dockerfile.musl -t kernel-collector:musl_5_4 --build--arg KERNEL_VERSION=5.4.18 ./$ docker run --rm -v$PWD:/kernel-collector kernel-collector:musl_5_4

To build with debug symbols enabled, set the environment variableDEBUG to1when running the build image.

For example:

$ docker build -f Dockerfile.musl -t kernel-collector:musl ./$ docker run --rm -e DEBUG=1 -v$PWD:/kernel-collector kernel-collector:musl

This setsEXTRA_CFLAGS=-g before building.

After you've got yourkernel/Makefille properly setup, you can run thefollowing command to compile all the eBPF programs:

# build in parallel jobs equal to `nproc` (number of processors)$ make -j`nproc`

When compilation finishes, you will have a file inside theartifactsdirectory with contents like the following:

pnetdata_ebpf_process.<kernel version>.opnetdata_ebpf_socket.<kernel version>.ornetdata_ebpf_process.<kernel version>.ornetdata_ebpf_socket.<kernel version>.o...

p*.o: eBPF programs used with entry mode, this is the default mode.r*.o: eBPF programs used with return mode.

These files have to be copied to your plugins directory, which is usually at/usr/libexec/netdata/plugins.d/, for the collector to be able to access them.After this you can start the new collectorebpf_program.plugin.

To release a new version and create a Github Release:

1. Create a Git tag like so:

   $ TAG="v0.0.1"; git tag -a -s -m"Release${TAG}""${TAG}"&& git push origin"${TAG}"

   Replacev0.0.1 with the next desired tag. SemVer is not strictly beingfollowed here at this time so the specific tagged versions is not soimportant.

   This will kick off a Github Action Workflow that will Rebuild the NetdataeBPF Kernel Collector for all Kernel and LIBC variants, create a GithubRelease and upload all assets to the release to be consumed by anyone or theNetdata Installer.

2. Wait for the CD pipeline to finish in the Github Actions UI.

3. Review the Release, Updates Release Notes, etc in the Github Releases UI.

4. Push the "Publish Release" button in the Github Releases UI.

Netdata is open-source software and we are always open for contributions thatyou can give us.

If you want to contribute an eBPF program, then please be sure that yourprogram matches the following patterns:

• Your program must run on all kernels since at least kernel4.11.
• Write some code that's responsible to measure the latency of your program.
• We have the variable NETDATASEL, that selects where the functions will beattached. Be sure that inside your code0 is associatedkretprobe, and2 is assoacitedwithkprobe.