eBPF Tracing Demo

This project demonstrates modern kernel tracing techniques using eBPF and Go at Riptides Labs.
It traces file creation events in the Linux kernel and exports them as Prometheus metrics via OpenTelemetry.

If you’re interested in how kernel-level telemetry can power observability, we’ve written a series of blog posts detailing how we built it from the ground up:

• From Breakpoints to Tracepoints: An Introduction to Linux Kernel Tracing
• From Tracepoints to Metrics: A journey from kernel to user-space
• Linux kernel module telemetry: beyond the usual suspects
• From Tracepoints to Prometheus: The journey of a kernel event to observability

A Cleaner, Faster, Safer Future for Non-Human Identity

---

Architecture Overview

Component Flow:

+-------------------------------+
|  Kernel Module (filewatcher)  |  (kretprobe on do_filp_open)
+-------------------------------+
              |
              v
 +----------------------------+
 |     Custom Tracepoint      |
 |  filewatcher/file_created  |
 +----------------------------+
              |
              v
      +----------------+
      |  eBPF Program  |  (attached to tracepoint)
      +----------------+
              |
              v
       +--------------+
       |  Ringbuffer  |
       +--------------+
              |
              v
    +---------------------+
    |  User-space Go App  |
    |    (ebpftracer)     |
    +---------------------+
              |
              v
+-------------------------------+
|  Prometheus Metrics Exporter  |
|      (OpenTelemetry)          |
+-------------------------------+
              |
              v
+------------------------------+
|       Metrics Backend        |
|  (e.g., Prometheus/Grafana)  |
+------------------------------+

Flow:

1. Kernel Module: Uses a kretprobe to instrument the do_filp_open kernel function and emits a custom tracepoint event (filewatcher/file_created).
2. eBPF Program: Attaches to the tracepoint, processes events, and writes them to a ring buffer.
3. User-space Go App: Loads the eBPF program, reads events from the ring buffer and exports them as Prometheus metrics using OpenTelemetry.
4. Metrics Backend: (Not included in this demo) Prometheus or another backend scrapes the metrics endpoint.

---

Prerequisites

• Linux kernel 6.11 (tested with Lima VM and Ubuntu)
• Go 1.24+
• GNU Make

Note:
If using a different kernel version, verify the do_filp_open function signature in the kernel module.
Mismatches may cause kernel crashes.

---

Quick Start

Environment Setup

make setup

Installs required packages and tools

---

(Optional) Dev Environment Setup

make setup-dev-env

Fetches and builds kernel source into ./linux

---

Build Everything

make

Generates Go bindings, builds the kernel module, and prepares the eBPF program.

---

Load the Kernel Module

make insmod

---

Run the eBPF Tracer Application

make run-ebpftracer

---

Generate File Creation Events

Create files on the system (e.g., touch /tmp/testfile) to trigger events.

---

View Metrics

curl localhost:8080/metrics | grep file_created

You should see Prometheus metrics for file creation events.

---

To Unload the Kernel Module

make rmmod

---

Notes

• The demo is designed for educational and experimental use.
• For production or other kernel versions, review and adapt the kernel module as needed.
• Metrics backend (e.g., Prometheus, Grafana) is not included in this repository.

---

License

SPDX-License-Identifier: MIT OR GPL-2.0-only
Copyright (c) 2025 Riptides Labs, Inc.

---