How sunnygeem/cold-start-hot-passion works
This repository is a small eBPF-based observability prototype, split cleanly into a user-space Go loader and a kernel-space C program.
High-level architecture
There are three main layers:
1. User-space control plane (v1/main.go)
- Written in Go.
- Acts as the entrypoint for the tool.
- Uses cilium/ebpf as the main runtime/library for loading and interacting with eBPF artifacts.
- Responsible for starting the monitoring workflow, loading the compiled BPF program, and receiving data/events coming back from the kernel.
2. Kernel-space data plane (v1/monitor.c)
- Written in C as an eBPF program.
- Runs inside the Linux kernel context.
- Implements the actual monitoring logic, likely by attaching to kernel hooks such as tracepoints, kprobes, or similar eBPF attachment points.
- Produces telemetry or event records that are sent back to user space.
3. Shared headers (headers/)
- headers/common.h contains shared data structures and constants used by both sides.
- headers/bpf_helpers.h and headers/bpf_helper_defs.h provide the usual eBPF helper declarations and definitions needed to compile the kernel-side program.
- This shared boundary is important: it keeps the user-space and kernel-space code aligned on event formats and constants.
Data flow
The dominant flow is:
• Go application starts
• eBPF program is loaded into the kernel
• Kernel-side program observes an event source
• Kernel-side program emits records/events to user space
• Go code consumes and interprets those events
So the architectural boundary is the standard eBPF split:
• control and presentation in user space
• instrumentation and event generation in kernel space
Repository structure and responsibilities
• README.md
- Minimal project description and reference to cilium/ebpf.
- Indicates this is a toy/learning project rather than a production system.
• v1/
- Looks like a versioned implementation directory, suggesting this repo may evolve through multiple iterations.
- main.go is the orchestrator.
- monitor.c is the compiled eBPF component.
• headers/
- Shared interface layer between Go and C.
- Keeps ABI-like contracts stable across the language boundary.
Important architectural boundaries
1. Go ↔ eBPF boundary
- The most important boundary in the system.
- Go handles lifecycle, loading, and reading results.
- C/eBPF handles execution in kernel context and must obey eBPF verifier constraints.
2. Shared schema boundary
- common.h likely defines the event structure(s) exchanged between kernel and user space.
- This is critical for diagramming because it is the contract that makes the two halves interoperable.
3. Kernel execution boundary
- monitor.c runs under kernel restrictions, which means:
- no general-purpose runtime
- constrained memory usage
- verifier-checked control flow
- This shapes the design: the kernel side only collects and emits minimal structured data.
Technologies that materially affect the architecture
• Go: user-space orchestration and event consumption.
• C/eBPF: kernel-side instrumentation.
• cilium/ebpf: the library that bridges Go and eBPF program loading/interaction.
• Linux kernel eBPF subsystem: the runtime environment for monitor.c.
How to think about the diagram
A useful architecture diagram for this repo would show:
• A Go user-space process on one side.
• A Linux kernel eBPF program on the other side.
• A shared headers/ABI layer connecting the source code for both.
• A data/event channel from kernel back to Go.
• The cilium/ebpf library as the mechanism inside Go that loads and manages the BPF program.
This is not a multi-service system or a web application; it is a two-part monitoring pipeline with a strict user/kernel split.
Main entry points: monitor.c Monitor · main.go Main · common.h Common · bpf_helpers.h Helpers
Components 7
User space
Go control plane and eBPF loader
- Main · Starts the monitoring workflow and consumes events
v1/main.go - cilium/ebpf · Loads and manages the compiled eBPF program
Kernel space
eBPF monitoring program
- Monitor · Kernel-side instrumentation and event generation
v1/monitor.c - Linux kernel · Verifier-checked execution environment for the monitoring program
Shared interface
Headers and ABI contract
- Common · Event formats and constants shared by Go and C
headers/common.h - Helpers · eBPF helper declarations and definitions
headers/bpf_helpers.h - Helper defs · Low-level helper function definitions for BPF builds
headers/bpf_helper_defs.h
Connections 9
- Main → cilium/ebpf: loads via · User-space process uses the eBPF library to load and attach programs
- cilium/ebpf → Monitor: loads · The Go runtime loads the compiled kernel program
- Main → Common: uses schema · User-space code interprets exchanged event records using shared types
- Monitor → Common: writes schema · Kernel program emits records matching the shared contract
- Monitor → Helpers: includes · Kernel program relies on standard eBPF helper declarations
- Monitor → Helper defs: includes · Kernel program uses helper definitions during compilation
- Monitor → Linux kernel: runs in · The eBPF program executes inside the Linux kernel
- Monitor → Main: events to · Telemetry and notifications flow back to the Go process
- Main → Linux kernel: controls · User-space loader manages kernel attachment lifecycle