benchmarking - SKILL.md Agent Skill

name: benchmarking description: Guide for building, running, and analyzing Nanvix performance benchmarks. Use this when asked about benchmark setup, execution, or interpretation.

Benchmarking Nanvix

Use this skill when the user asks about running, creating, or analyzing performance benchmarks in Nanvix.

Benchmark Tool

Nanvix includes nanvix-bench (src/utils/nanvix-bench/) for measuring system performance. Benchmarks require a release build with panic-level logging.

Building for Benchmarks

# Standard benchmarks.
./z build -- all RELEASE=yes LOG_LEVEL=panic

# Echo-breakdown benchmark (requires message timestamping).
./z build -- all RELEASE=yes LOG_LEVEL=panic TIMESTAMP_MSG=yes

Available Benchmarks

Benchmark	Description
`boot-time`	Start a user VM (no linuxd)
`cold-start`	Start linuxd + VM + HTTP echo
`cold-start-l2`	`cold-start` with linuxd in L2 VM
`cold-start-uvm`	`cold-start` reusing linuxd
`concurrent`	`cold-start` with many VMs alive
`concurrent-l2`	`concurrent` with linuxd in L2 VM
`echo-breakdown`	HTTP echo step-by-step breakdown
`echo-breakdown-l2`	`echo-breakdown` with linuxd in L2 VM
`round-trip-latency`	Latency vs. echo payload size
`warm-start`	Fixed-size HTTP echo latency
`warm-start-l2`	`warm-start` with linuxd in L2 VM
`warm-start-vmm`	`warm-start` without linuxd

Running Benchmarks

# Basic usage.
./bin/nanvix-bench.elf -benchmark cold-start
./bin/nanvix-bench.elf -benchmark warm-start
./bin/nanvix-bench.elf -benchmark echo-breakdown

# See all options.
./bin/nanvix-bench.elf -help

Core Pinning (Recommended)

For best performance, pin components to different CPU dies. Create a JSON config:

{
    "client_core_str": "0-9",
    "linuxd_core_str": "10-14",
    "nanovm_core_str": "15-19"
}

Then pass it to the benchmark:

./bin/nanvix-bench.elf \
    -benchmark <benchmark> \
    -hwloc <path_to_config.json>

High-Iteration Runs

For benchmarks with many iterations, increase system limits:

ulimit -u 65536    # Max user processes.
ulimit -n 65536    # Max open files.

Benchmark Applications

Source code for benchmark programs:

Benchmark App	Path	Lang
`echo-rust-nostd`	`src/benchmarks/echo-rust-nostd/`	Rust
`noop-rust-nostd`	`src/benchmarks/noop-rust-nostd/`	Rust

Analyzing Results

Benchmark results can be visualized with the plotting script:

python3 scripts/plot-performance.py

Additional analysis can be done with the automation script:

python3 scripts/benchmark.py

Benchmarking on Windows

On Windows, nanvix-bench runs in standalone mode (no HTTP, no linuxd). The standalone cold-start benchmark spawns a fresh nanvixd process per iteration in interactive mode and measures the time from process spawn to the first echo round-trip.

Building

.\z.ps1 build -- all RELEASE=yes LOG_LEVEL=panic

Available Benchmarks

Benchmark	Description
`boot-time`	Start a user VM (no nanvixd)
`cold-start`	Spawn nanvixd + VM + echo round-trip (standalone mode)
`snapshot-restore`	Measure snapshot restore latency vs boot-time
`warm-start-vmm`	Raw round-trip latency inside the user VM

Running

# Using z.ps1.
.\z.ps1 bench -- -benchmark cold-start -iterations 10

# Or directly.
.\bin\nanvix-bench.exe -benchmark cold-start -iterations 10
.\bin\nanvix-bench.exe -benchmark boot-time -iterations 100
.\bin\nanvix-bench.exe -help

Note: HTTP-based benchmarks (warm-start, round-trip-latency, concurrent, L2 variants, and echo-breakdown) are Linux-only.