Background
During review of #873, both @brayniac and @thinkingfish noted that rezolus's design philosophy for sampler development isn't currently captured in a discoverable doc (CLAUDE.md, CONTRIBUTING.md, or similar). Without it, contributors — and AI assistants like Claude Code — propose approaches that conflict with the project's intentions, costing review cycles.
"If it's currently lacking in the CLAUDE.md or other doc sources, we should try to spell out some stronger guidelines about the approach we're taking overall and why. It seems that Claude doesn't quite understand the motivations - for example: avoid bpf hashmaps, try to use BPF instead of procfs or sysfs reads, etc. I feel like our intentions in the approach are what make Rezolus special."
— @brayniac on #873
"Overall I think it'll be great to have a skill or guiding doc about the tradeoff and methodology of Rezolus sampler dev."
— @thinkingfish on #873
What this issue is asking for
A guiding document covering rezolus's sampler-development methodology — the why behind the design choices, not just a tutorial on how to add a sampler.
Principles that surfaced explicitly in #873 review (non-exhaustive — others likely exist):
- Prefer BPF instrumentation over procfs / sysfs reads when possible.
- Avoid runtime BPF hashmaps; prefer fixed-cardinality per-CPU array maps with cacheline-aligned banks.
- Consolidate probes at the same tracepoint rather than attaching multiple BPF programs at the same hook — pay the entry/exit cost once.
- Use static
LazyCounter declarations per label combination (avoid macro-generated declarations) to keep symbols greppable; trade source verbosity for hot-path speed and discoverability.
Why this matters
These principles together are what differentiates rezolus from other systems-telemetry agents (low overhead, predictable cost, BPF-native). Capturing them lets new contributors and tooling produce PRs that are aligned by default rather than discovered through review.
Out of scope
The document should describe principles and the reasoning behind them. Specific implementation prescriptions for individual feature requests (e.g., which tracepoint to use for hardirq instrumentation) are better discussed in the issues for those features.
Related
Background
During review of #873, both @brayniac and @thinkingfish noted that rezolus's design philosophy for sampler development isn't currently captured in a discoverable doc (CLAUDE.md, CONTRIBUTING.md, or similar). Without it, contributors — and AI assistants like Claude Code — propose approaches that conflict with the project's intentions, costing review cycles.
What this issue is asking for
A guiding document covering rezolus's sampler-development methodology — the why behind the design choices, not just a tutorial on how to add a sampler.
Principles that surfaced explicitly in #873 review (non-exhaustive — others likely exist):
LazyCounterdeclarations per label combination (avoid macro-generated declarations) to keep symbols greppable; trade source verbosity for hot-path speed and discoverability.Why this matters
These principles together are what differentiates rezolus from other systems-telemetry agents (low overhead, predictable cost, BPF-native). Capturing them lets new contributors and tooling produce PRs that are aligned by default rather than discovered through review.
Out of scope
The document should describe principles and the reasoning behind them. Specific implementation prescriptions for individual feature requests (e.g., which tracepoint to use for hardirq instrumentation) are better discussed in the issues for those features.
Related
docs/TODOs.md— feature wishlist that was rewritten to be why/what only after review feedback in feat: Exceptions dashboard + blockio errors/requeues sampler #873; the sampler-dev doc would inform the how decisions when those TODOs are picked up