KernelTrace 1.0.0

KernelTrace

In-process eBPF kernel tracing for .NET

KernelTrace bridges Linux eBPF and the .NET managed runtime. Attach to kernel tracepoints, kprobes, and uprobes, stream type-safe events through a lock-free ring buffer — all from within your own process, with zero sidecars or agents.

Why KernelTrace?

Kernel observability for .NET has historically meant spawning external processes (bpftrace, perf, BCC) and parsing their text output, or writing C/Python BPF glue code. KernelTrace removes the indirection entirely.

Features

Quick Start

Prerequisites

• Linux kernel 5.8+ with CONFIG_DEBUG_INFO_BTF=y
• CAP_BPF + CAP_PERFMON (or root) — see Privileges below
• libbpf 1.0+ (apt install libbpf-dev)

Install

dotnet add package KernelTrace

Stream network connection events

using KernelTrace.Events;
using KernelTrace.Probes;
using KernelTrace.Sessions;
using System.Runtime.InteropServices;

// Define the event struct — layout is auto-generated by the source generator
// from the struct definition in network_monitor.bpf.c.
[KernelEvent("sock_connect_event")]
[StructLayout(LayoutKind.Sequential, Pack = 1)]
public unsafe partial struct SocketConnectEvent
{
    public ulong  TimestampNs;
    public uint   Pid;
    public uint   Tgid;
    public uint   Uid;
    public uint   SrcIp;
    public uint   DstIp;
    public ushort SrcPort;
    public ushort DstPort;
    public fixed byte Comm[16];
    public byte   Family;
}

// Ctrl+C handling
using var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; cts.Cancel(); };

// Create a session — both enter and exit tracepoints are required:
// the BPF program records the entry timestamp and emits the event on exit.
await using var session = await KernelTraceSession.CreateAsync(new SessionOptions
{
    ProbePath = "/usr/share/kerneltrace/probes/network_monitor.bpf.o",
    Probes    =
    [
        new TracepointSpec { Category = "syscalls", Name = "sys_enter_connect" },
        new TracepointSpec { Category = "syscalls", Name = "sys_exit_connect"  },
    ],
});

// Stream events — cancel on Ctrl+C
try
{
    await foreach (var ev in session.ReadAsync<SocketConnectEvent>(cts.Token))
    {
        Console.WriteLine($"PID={ev.Tgid}  dst={ev.DstIp}:{ev.DstPort}  comm={new string((sbyte*)ev.Comm)}");
    }
}
catch (OperationCanceledException) { }

Privileges

KernelTrace loads eBPF programs into the kernel, which always requires elevated capabilities regardless of how many or how few processes you trace.

Required Linux capabilities

CAP_SYS_ADMIN (root) is an alternative that implies both, but is far broader than needed.

Recommended: setcap instead of sudo

Grant the two narrow capabilities to your binary once; afterwards it runs as a normal user:

sudo setcap cap_bpf,cap_perfmon+ep ./YourApp
# or, for the .NET host when running with dotnet-run:
sudo setcap cap_bpf,cap_perfmon+ep $(which dotnet)

This is the recommended production deployment model. The process retains no other elevated privileges — no filesystem root, no CAP_NET_ADMIN, no CAP_SYS_PTRACE.

Does CurrentProcessOnly remove the need for privileges?

No. SessionOptions.CurrentProcessOnly = true installs an eBPF filter that drops kernel events from all other processes before they reach the ring buffer. It reduces CPU overhead and ring-buffer pressure, but the eBPF program must still be loaded and attached, which requires CAP_BPF + CAP_PERFMON regardless of scope.

Packages

Architecture Overview

Kernel                                   .NET Process
─────────────────────────────────────────────────────────────────
  BPF program (clang-compiled)
        │ bpf_ringbuf_submit
        ▼
  BPF_MAP_TYPE_RINGBUF (mmap'd)
        │ lock-free consumer
        ▼
  RingBufferReader ──► Channel<RingBufferRecord> ──► IAsyncEnumerable<T>
                   └──────────────────────────────► ProcessAsync<T> (zero-copy)

A dedicated polling thread (ThreadPriority.AboveNormal) polls the ring buffer via epoll_wait, drains records into a bounded channel, and updates metrics counters — all without touching the thread pool.

→ Full architecture documentation

Samples

→ Samples documentation

Documentation

• Getting Started
• Architecture
• Probe Reference
• Samples
• API Reference

Building the native library

Using the helper scripts (recommended)

Two scripts in native/scripts/ cover the full local build workflow:

# 1. Generate vmlinux.h — required once per kernel version (file is gitignored)
bash native/scripts/gen-vmlinux.sh

# 2. Build libkerneltrace.so + *.bpf.o and install into runtimes/<RID>/native/
bash native/scripts/build-and-install.sh

build-and-install.sh auto-detects the host architecture and libc variant:

The output lands in runtimes/<RID>/native/ — exactly where the .NET SDK native-asset resolver and dotnet pack expect it, so no extra configuration is needed.

→ Full walkthrough in docs/getting-started.md — Building from source

Manual cmake build

For fine-grained control or to skip probe compilation:

cd native
cmake -B build -DCMAKE_BUILD_TYPE=Release   # KERNELTRACE_BUILD_PROBES=ON by default
cmake --build build -j$(nproc)              # builds libkerneltrace.so + all .bpf.o probes
sudo cmake --install build                   # installs into /usr/local

To skip eBPF probe compilation (no clang required):

cmake -B build -DCMAKE_BUILD_TYPE=Release -DKERNELTRACE_BUILD_PROBES=OFF
cmake --build build -j$(nproc)

The build system detects the host architecture (CMAKE_SYSTEM_PROCESSOR) and sets the appropriate BPF target-arch define and multiarch include path automatically. arm64, armv7, riscv64, s390x, and x86_64 are supported. On musl-based systems (Alpine) the multiarch subdirectory is absent and the build falls back to /usr/include seamlessly.

Testing

dotnet test tests/KernelTrace.Tests/            # core unit tests
dotnet test tests/KernelTrace.Generators.Tests/ # Roslyn generator tests

Tests run on any OS (Linux/macOS/Windows) using FakeNativeInterop and FakeRingBuffer — no kernel access required.

Benchmarks

cd benchmarks/KernelTrace.Benchmarks
dotnet run -c Release -- --filter '*'

Sample results on a 3.6 GHz Zen 3 core:

Requirements

• Linux kernel ≥ 5.8 with CONFIG_DEBUG_INFO_BTF=y
• .NET 8, 9, or 10 (multi-targeted)
• libbpf ≥ 1.0
• clang ≥ 14 (for compiling custom probes)
• CAP_BPF + CAP_PERFMON at runtime (see Privileges)

License

MIT