01.03.2026

Compendium: A User-Friendly Syscall Tracer with HTML Reports

Compendium Syscall Tracer

Quick Reference:

# Install
cargo install compendium

# Basic tracing
compendium -- curl -s https://example.com

# Attach to running process
compendium --pid 1234

# Generate HTML report
compendium --report report.html -- ./my-app

# Full tracing with eBPF
sudo compendium --ebpf --faults --report trace.html -- ./my-app

If you've ever used strace to debug a Linux application, you know the pain: walls of cryptic syscall output, noise from system libraries, and no easy way to see the big picture. Enter Compendium, a Rust-based syscall tracer that filters the noise and generates interactive HTML reports.

Why Compendium Over strace?

Feature	strace	Compendium
Output readability	Raw syscalls	Filtered, human-readable
Noise filtering	Manual	Automatic (ignores /proc, .so files)
HTML reports	No	Yes, interactive timeline
Memory tracking	Basic	Heap + mmap with addresses
Network summary	No	TCP/UDP connections aggregated
eBPF support	No	Scheduler + block I/O latency

Installation

Compendium is written in Rust and available on crates.io:

# From crates.io
cargo install compendium

# From source
git clone https://github.com/louisboilard/compendium
cd compendium
cargo install --path .

Basic Usage

Trace any command by prefixing it with compendium --:

compendium -- curl -s https://example.com

Output:

compendium: tracing curl -s https://example.com
[+0.000s] ─── curl exec ───
[+0.002s] mmap 7f8a12345000-7f8a12347000 rw- 8.0 KB anon
[+0.003s] open /etc/resolv.conf (read)
[+0.015s] connect tcp4 → 93.184.216.34:443
[+0.156s] send 517 B
[+0.234s] recv 1.4 KB

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 FINAL: curl -s https://example.com (0.34s)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Memory:
   Heap: 132.0 KB
   Mmap: 8.5 MB (24 regions)
   Total: 8.6 MB
 I/O:
   Files read: 12.4 KB
   Files written: 0 B
   Net sent: 517 B
   Net received: 2.6 KB
 Network connections:
   tcp4 → 93.184.216.34:443
 Exit: 0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Notice how it shows exactly what matters: files opened, network connections, memory usage, and I/O stats. No noise from dynamic linker operations or /proc filesystem access.

Attach to Running Processes

Debug a production issue without restarting the process:

compendium --pid 1234

Press Ctrl+C to detach cleanly (the process continues running).

Interactive HTML Reports

The killer feature for SRE teams. Generate a self-contained HTML report:

compendium --report trace.html -- ./my-service

The report includes:

Timeline view: SVG swimlane visualization with one lane per process/thread
Event table: Virtual-scrolled list of all events with filtering
Category filters: Toggle file, network, memory, I/O, and process events
Zoom controls: Ctrl+scroll or +/- keys to focus on specific time ranges

This is invaluable for post-incident analysis. Share the HTML file with your team - no special tools needed.

Advanced Features

Page Fault Tracking

See actual memory growth as pages are touched:

# Requires elevated permissions
echo 0 | sudo tee /proc/sys/kernel/perf_event_paranoid
sudo compendium --faults -- ./memory-intensive-app

eBPF Tracing

Track scheduler latency and block I/O with kernel-level precision:

# Requires CAP_BPF or root, kernel 5.8+ with BTF
sudo compendium --ebpf -- dd if=/dev/zero of=/tmp/test bs=4K count=1000

This reveals:

Scheduler latency: Time between task wakeup and actual CPU scheduling
Block I/O latency: Disk request submission to completion time

Combined Tracing

For the full picture, combine all features:

sudo compendium --ebpf --faults --report full-trace.html -- ./my-app

How It Works

Compendium uses Linux ptrace to intercept syscalls at entry and exit. For each syscall:

Captures syscall number and arguments at entry
Captures return value at exit
Reads strings/buffers from tracee memory as needed
Tracks file descriptors to distinguish files from sockets
Outputs events in real-time with timestamps

For eBPF tracking, it loads pre-compiled BPF objects and attaches to kernel tracepoints (sched_wakeup, sched_switch, block_rq_issue, block_rq_complete).

Noise Filtering

By default, Compendium filters out:

System paths: /proc, /sys, /dev
Dynamic linker files: ld.so, ld-linux, .so files
Localhost connections: 127.0.0.1, 127.0.0.53

Use --verbose for raw tracing when you need everything.

CLI Reference

compendium [OPTIONS] -- <COMMAND>

Options:
  -p, --pid <PID>           Attach to existing PID
  -v, --verbose             Show raw syscalls
  --faults                  Track page faults (requires sudo)
  --ebpf                    Track scheduler/block I/O (requires root)
  -o, --output <FILE>       Write output to file
  --report <FILE>           Generate HTML report
  --max-report-events <N>   Max events in report (default: 75000)
  -h, --help                Print help

SRE Use Cases

Debugging slow startup: See exactly what files are being read and how long DNS resolution takes
Memory leak investigation: Track mmap regions and heap growth over time
Network debugging: Identify unexpected connections or excessive DNS lookups
I/O bottlenecks: Find which files are being read repeatedly
Post-incident analysis: Generate HTML reports to share with the team

Requirements

Linux x86_64
Rust toolchain (for installation)
For eBPF: Kernel 5.8+ with BTF support, CAP_BPF or root

strace - Traditional syscall tracer
perf - Linux performance analysis
bpftrace - eBPF tracing language

Conclusion

Compendium fills a gap in the Linux debugging toolkit. It takes the power of strace and makes it accessible with noise filtering, memory tracking, and beautiful HTML reports. For SRE teams debugging production issues, the ability to generate a shareable timeline view is invaluable.

Try it on your next debugging session. The HTML reports alone are worth the install.

Want to automate incident response when you find issues? Akmatori uses AI agents to analyze alerts, run diagnostics like Compendium, and resolve incidents automatically.

Akmatori team