CLI & Configuration

Commands, flags, and TOML configuration reference.

Commands

Agent default mode

$sudo rezolus <CONFIG>

Collect metrics via eBPF. Requires root. Listens on 0.0.0.0:4241.

Exporter

$rezolus exporter <CONFIG>

Pull from agent, expose Prometheus metrics on :4242.

Recorder

$rezolus record [OPTIONS] [-- <COMMAND>...]

With no arguments at all this records the local agent (http://localhost:4241) into rezolus.rez until ctrl-c. The output extension picks the format, so --format is rarely needed.

--url <URL> Endpoint to record [default: http://localhost:4241]

-o, --output <PATH> Output path; .rez | .parquet | .raw picks the format [default: rezolus.rez]

-i, --interval <INTERVAL> Collection interval [default: 1s]

-d, --duration <DURATION> Record for a fixed window, then stop

-f, --format <FORMAT> rez|parquet|raw — only needed when the path cannot say

-l, --label <KEY=VALUE> Tag a .rez recording (repeatable); source/host auto-filled

-m, --metadata <KEY=VALUE> File-level metadata, any format (repeatable)

--config <FILE> TOML config for multi-endpoint recording

--endpoint <URL> Endpoint with options (repeatable), url[,source=][,role=][,protocol=]

--separate Write per-endpoint files instead of one combined

-v, --verbose Increase verbosity (stackable)

# Record the local agent until ctrl-c → rezolus.rez

$rezolus record

# Record 30s at 100ms intervals

$rezolus record -o run.rez -i 100ms -d 30s

# Record only while a benchmark runs (perf-record style)

$rezolus record -o bench.rez -- ./bench.sh --iters 100

# A Prometheus source needs parquet

$rezolus record --url http://host:9090/metrics -o svc.parquet -d 5m

Hindsight

$rezolus hindsight <CONFIG>

Rolling ring buffer. Send SIGHUP to trigger snapshot.

Status

$rezolus status [OPTIONS] [ENDPOINT]

Ask a running agent how it is doing: version, uptime, and a per-sampler health rollup. With no argument it asks the agent on this machine.

ENDPOINT Agent to ask [default: http://localhost:4241]; a bare host or host:port is fine

--json Emit the raw /status JSON

Exit status: 0 when nothing is wrong, 1 when any sampler is degraded, failed or pmu-limited — so it works as a health check or readiness probe.

# Is the agent on this machine healthy?

$rezolus status

# Another host, written the short way

$rezolus status web-01

# Use it as a gate in a script

$rezolus status || echo "agent is unhealthy"

Viewer

$rezolus view [OPTIONS] [INPUT] [EXPERIMENT]

INPUT First capture: parquet, .rez archive, agent URL, or alias=parquet

EXPERIMENT Optional second capture for A/B comparison

-l, --listen <ADDR> Viewer listen address (e.g. 127.0.0.1:8080)

--templates <DIR> Directory of service-extension template JSON

--category <NAME> Activate category mode (e.g. inference-library)

--proxy-allow <PATTERN> Whitelist a host pattern for URL proxy (repeatable)

--proxy-allow-any Disable proxy allowlist entirely (trust-everyone mode)

--tui Terminal UI instead of a browser (needs a file or agent URL)

--cache-size-mb <MB> Row-group buffer cache size [default: 500]

-v, --verbose Increase verbosity

# View a recording

$rezolus view output.parquet

# View a .rez archive (a 2-recording .rez renders as A/B)

$rezolus view out.rez

# View live agent

$rezolus view http://localhost:4241

# Explore in the terminal, no browser

$rezolus view --tui out.rez

MCP Server

$rezolus mcp [SUBCOMMAND]

analyze-correlation <FILE> <Q1> <Q2>

describe-recording <FILE>

describe-metrics <FILE>

detect-anomalies <FILE> [QUERY]

query <FILE> <QUERY>

extract-features <FILE>

Every <FILE> may be a .parquet or a .rez; the format is detected by content. With no subcommand, rezolus mcp runs as a stdio MCP server for an LLM client.

# One-shot PromQL against a recording

$rezolus mcp query out.rez 'sum(rate(cpu_cycles[1m]))'

# Sweep every metric for anomalies

$rezolus mcp detect-anomalies out.rez

Recording Tools

$rezolus recording <SUBCOMMAND> [OPTIONS]

Offline operations on recordings — both .parquet files and .rez archives. Inspect metadata, trim what you do not need, embed service KPI definitions, merge multi-source captures, or convert older formats. rezolus parquet … still works as an alias.

`metadata`

Show file-level + column metadata for a recording.

-i, --input <FILE> Recording to inspect (.parquet, or a .rez manifest)

--schema Show only column-level metadata

--file Show only file-level metadata

--geometry Show only table shape + row group layout

--field <KEY> Print one file-level metadata key

--json Emit JSON (for scripting)

`annotate`

Embed service-extension KPI queries (and related metadata) into a recording so the viewer can render them as charts.

FILE Parquet to annotate (overwritten in place unless ‐‐output)

--queries <JSON> Custom service-extension JSON (overrides templates)

--templates <DIR> Template directory to resolve KPIs from

--source <NAME> Source tag to match against template members

--node <NAME> Node name, read by combine for multi-node merges

--filter Trim columns to only those referenced by KPIs

--systeminfo <JSON> Embed/override the recorded systeminfo

--add-events <JSON> Append events to the file

--event <SPEC> Single event spec (repeatable)

--clear-events Drop all existing events

--overwrite Allow overwriting existing annotations

--undo Remove previously-applied annotations

`combine`

Merge multiple parquet files into one — multi-node rezolus, multi-instance services, or compare-mode A/B bundles.

FILES... Inputs to merge (parquet, or single-recording .rez)

-o, --output <FILE> Output parquet path

--pinned <NAME> Default rezolus node to display

--ab <B=SRC> <E=SRC> Bundle as A/B compare tarball — one flag, both values: --ab baseline=… experiment=…

--category <NAME> Tag the bundle with a category template

--bypass-time-check Skip timestamp alignment validation

`filter`

Shrink a recording to what it needs — parquet columns referenced by its service-extension KPIs, or whole samplers of a .rez. Useful before sharing a focused report.

FILE Recording to filter (.parquet, or .rez with --samplers)

--samplers <A,B,...> For .rez: samplers to KEEP (required there, ignored for parquet)

--queries <JSON> Custom KPI JSON (overrides embedded/template)

--templates <DIR> Template directory to resolve KPIs from

-o, --output <FILE> Output path (defaults to in-place overwrite)

`convert`

Turn a raw msgpack recording (from record -o out.raw) into parquet. Plain or zstd input, detected by content.

FILE Raw recording to convert

-o, --output <PATH> Output parquet path (default: input with .parquet)

--interval <DURATION> Override the inferred sampling interval

--systeminfo <PATH> Stamp in a systeminfo blob the raw stream never carried

--descriptions <PATH> Stamp in metric help text (only settable here)

-m, --metadata <KEY=VALUE> Tag the output (repeatable)

--force Overwrite an existing output

`upgrade`

Rewrite a v1/v2 (tar) .rez as the current v3 (SQLite) container. Segment data is carried across byte-for-byte. A v3 input is refused rather than copied.

FILE The .rez archive to upgrade

-o, --output <REZ> Write here instead of replacing in place

# Inspect

$rezolus recording metadata -i out.rez

# Annotate with KPIs from a template directory

$rezolus recording annotate recording.parquet --templates ./templates

# Combine two captures as an A/B bundle

$rezolus recording combine before.parquet after.parquet \

--ab baseline=before experiment=after \

-o compare.parquet.ab.tar

# Assemble two single-recording .rez into one A/B archive

$rezolus recording combine baseline.rez experiment.rez -o ab.rez

Configuration

Each mode uses a TOML config file. Examples are in the config/ directory.

Agent

config/agent.toml

# General settings

[general]

listen = "0.0.0.0:4241"

# Logging

[log]

level = "info" # error | warn | info | debug | trace

# Scheduler tuning

[scheduler]

policy = "normal" # normal | round_robin | fifo

# Default for all samplers

[defaults]

enabled = true

# Per-sampler overrides

[samplers.cpu_usage]

enabled = true

[samplers.scheduler_runqueue]

enabled = true

Exporter

config/exporter.toml

[general]

listen = "0.0.0.0:4242"

source = "http://127.0.0.1:4241"

[prometheus]

histogram = "summary" # summary | histogram

Hindsight

config/hindsight.toml

[general]

interval = "1s"

duration = "1h"

source = "http://127.0.0.1:4241"

output = "/var/lib/rezolus/hindsight.parquet"

listen = "0.0.0.0:4242" # optional HTTP API

← API Reference