Switch collector transport to ringbuf

[Agent-Hellboy]

Closed in favor of #5, which uses the clearer ringbuf-transport-batching-improvements branch name.

Summary by CodeRabbit

• New Features

  • Event capture now uses a ring-buffer transport for improved throughput and reliability.
  • Capture loss is tracked and reflected in event records.
  • Larger diff windows can now identify changes after high-volume activity.

• Bug Fixes

  • Prevented already-buffered events from being omitted during flushes.
  • Improved modified-file detection for rename and related operations.

• Documentation

  • Expanded documentation for generated artifacts, capture transport, and event-loss behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 44ba0a9d-7bbb-492b-ae9b-d8109ff5f48e

📥 Commits

Reviewing files that changed from the base of the PR and between 4a936cc and 987a006.

⛔ Files ignored due to path filters (1)

• internal/ebpf/collector_bpfel.o is excluded by !**/*.o

📒 Files selected for processing (16)

• AGENTS.md
• README.md
• docs/README.md
• docs/abi/capture.md
• docs/architecture.md
• docs/generated.md
• docs/recording.md
• internal/daemon/flush.go
• internal/daemon/service.go
• internal/daemon/service_test.go
• internal/diff/engine.go
• internal/diff/engine_test.go
• internal/ebpf/collector.bpf.c
• internal/ebpf/collector_bpfel.go
• internal/ebpf/collector_linux.go
• internal/ebpf/headers/bpf_helpers.h

---

📝 Walkthrough

Walkthrough

The PR switches eBPF event delivery from perf events to a ring buffer with explicit drop accounting, improves daemon buffering and flush draining, expands diff event coverage, and documents generated artifacts, workflows, and updated transport semantics.

Changes

Runtime and documentation updates

Layer / File(s)	Summary
Ring-buffer event transport internal/ebpf/*	The eBPF collector reserves and submits ring-buffer events, counts reservation failures, replaces scratch-map wiring with ringbuf_drops, and reads per-CPU drop totals in userspace.
Buffered ingestion and flush draining internal/daemon/flush.go, internal/daemon/service.go, internal/daemon/service_test.go	Default batch and buffer sizes increase, and flushes drain ready events before persistence, including a test for buffered bursts.
Expanded diff event coverage internal/diff/engine.go, internal/diff/engine_test.go	Diff queries increase to 50,000 events and file changes use a consistently resolved non-empty path, with coverage for noisy prefixes.
Generated artifact and transport documentation AGENTS.md, README.md, docs/README.md, docs/abi/capture.md, docs/architecture.md, docs/generated.md, docs/recording.md	Documentation describes generated outputs and workflows, ring-buffer ABI contracts, drop accounting, and updated loss terminology.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Kernel as eBPF collector
  participant Ringbuf as events ring buffer
  participant Reader as Linux collector
  participant Ingest as daemon ingest
  participant Store as event store
  Kernel->>Ringbuf: reserve and submit event
  Kernel->>Kernel: count failed reservations
  Reader->>Ringbuf: read event
  Reader->>Reader: sample ringbuf_drops
  Reader->>Ingest: emit event and drop delta
  Ingest->>Store: flush persisted batch

Loading

Possibly related PRs

• Agent-Hellboy/ltm#3: Adds the ABI-generated kernel event header and bpf2go wiring used by the eBPF collector.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch abi-contract-codegen

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 987a0069d8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Flush pending ringbuf drops before shutdown

When overload happens near the end of a recording, fewer than 256 records may be read after failed bpf_ringbuf_reserve calls, so this periodic-only sampling leaves the latest ringbuf_drops delta in the kernel map. If ltm stop then closes the reader, the loop returns without converting that delta into any event's DroppedBefore, and SUM(dropped_before) underreports drops for that recording; sample the counter on shutdown or reduce this delayed attribution so final drops are not lost.

Useful? React with 👍 / 👎.