Ebpf Go

Overview

Build, debug, and ship eBPF programs written in C and loaded/controlled from Go.

Assume Linux. If working from macOS/Windows, run and test eBPF in a Linux VM/container with a recent kernel.

Workflow Decision Tree

1. •

   Identify the goal:

   • •Observability / tracing: syscalls, kernel functions, user-space functions → tracepoint/kprobe/uprobe
   • •Networking: packets / sockets, filtering/redirect/shaping → XDP/TC/cgroup/socket
2. •

   Decide portability:

   • •Need “build once, run many kernels” → use CO-RE with BTF + vmlinux.h
   • •Single known kernel → non-CO-RE builds may be acceptable (still prefer CO-RE)
3. •

   Decide data path from BPF → Go:

   • •High-rate events → ringbuf (preferred) or perf event
   • •State / counters → maps (hash/LRU/percpu/array) polled from Go
   • •Configuration → maps updated from Go

If you need details for a decision point, load the relevant reference file from references/.

Track-Specific Guidance

After you pick a goal, load exactly one of these first:

• •Observability / tracing: references/tracing.md
• •Networking (XDP / TC): references/networking-xdp-tc.md

Standard Workflow (C + bpf2go + Go)

Follow this shape unless there’s a strong reason not to:

1. •

   Create a minimal project layout

   • •Put BPF C sources under bpf/ (e.g., bpf/prog.bpf.c)
   • •Generate Go bindings via //go:generate + bpf2go
   • •Keep runtime code under cmd/<tool>/ or internal/
   • •For a concrete layout, read references/project-layout.md
2. •

   Implement the BPF program

   • •Keep it verifier-friendly: bounded loops, simple control flow, careful pointer arithmetic
   • •Prefer CO-RE (vmlinux.h, BPF_CORE_READ, bpf_core_read*) when touching kernel structs
   • •Choose maps and event mechanism early (ringbuf/perf/maps)
   • •For toolchain and CO-RE specifics, read references/toolchain-and-core.md
3. •

   Generate Go bindings

   • •Use bpf2go to compile the C to BPF bytecode and generate Go types/loaders
   • •Keep compilation flags consistent across environments
4. •

   Load and verify

   • •Raise memlock/rlimits (commonly via rlimit.RemoveMemlock())
   • •Load the CollectionSpec, apply any rewrites, then NewCollection()
   • •When load fails, capture verifier logs and consult references/troubleshooting.md
5. •

   Attach

   • •Use github.com/cilium/ebpf/link to attach to the chosen hook
   • •Pin if needed; always close links on shutdown
   • •For hook-specific guidance, read references/program-types-and-attach.md
6. •

   Read events / interact with maps

   • •ringbuf: decode event structs and handle backpressure
   • •perf: handle lost samples; tune buffer sizes
   • •maps: prefer per-cpu for hot counters; avoid frequent full scans
   • •For Go-side patterns, read references/go-integration-patterns.md
7. •

   Harden & ship

   • •Use capabilities carefully (often CAP_BPF/CAP_PERFMON/CAP_SYS_ADMIN depending on kernel)
   • •Include a fallback path or clear error messages for kernels lacking features
   • •Provide “dry run”/self-check output (kernel + feature probe)

Debugging Checklist (Fast)

• •Confirm environment: Linux kernel, BTF present at /sys/kernel/btf/vmlinux, correct arch.
• •Confirm toolchain: clang can target BPF, bpftool present for diagnostics.
• •For load errors:
  • •Turn on verifier logs (cilium/ebpf supports ebpf.CollectionOptions{Programs: ebpf.ProgramOptions{LogLevel, LogSize}} patterns).
  • •Inspect dmesg for verifier output.
• •For attach errors:
  • •Confirm the attach point exists (interface, tracepoint name, symbol present).
  • •Verify permissions/capabilities and mount settings.
• •For “it loads but does nothing”:
  • •Add minimal counters in a map to prove execution.
  • •Validate event struct layout/alignment between C and Go.

References (Load On Demand)

• •references/toolchain-and-core.md: clang/bpf2go, CO-RE/BTF, vmlinux.h generation.
• •references/program-types-and-attach.md: which hook to choose + how to attach from Go.
• •references/go-integration-patterns.md: maps/events patterns, lifecycle, performance.
• •references/troubleshooting.md: common errors, verifier failures, kernel feature probes.
• •references/project-layout.md: recommended repo layout and go:generate conventions.
• •references/tracing.md: tracing/observability patterns and practical heuristics.
• •references/networking-xdp-tc.md: XDP/TC decision guidance, map patterns, debugging cues.