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.dendro until ctrl-c. The output must end in .dendro; any other output, a --format other than dendro, and --separate are refused. A rezolus 5.x recorder (5.27.0 or later) still writes .rez, parquet and raw.

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

-o, --output <PATH> Output path, ending in .dendro [default: rezolus.dendro]

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

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

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

-m, --metadata <KEY=VALUE> Metadata on every recording in the archive (repeatable)

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

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

-v, --verbose Increase verbosity (stackable)

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

$rezolus record

# Record 30s at 100ms intervals

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

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

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

# A Prometheus endpoint is scraped into the same kind of archive

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

Hindsight

$rezolus hindsight <CONFIG>

Rolling buffer kept as a .dendro archive. Send SIGHUP to write a snapshot. An output not ending in .dendro is refused at startup.

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, .dendro or .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]

--query-concurrency <N> Queries run at once (others wait) [default: half the CPUs, 2 to 8]

-v, --verbose Increase verbosity

# View a recording

$rezolus view output.parquet

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

$rezolus view out.dendro

# View live agent

$rezolus view http://localhost:4241

# Explore in the terminal, no browser

$rezolus view --tui out.dendro

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>

install [--scope user|project] [--dry-run] [--no-skill] [--allow-mutating] [--export-dir DIR] [--viewer-url URL]

Every <FILE> may be a .parquet, a .dendro or a .rez; the format is detected by content. With no subcommand, rezolus mcp runs as a stdio MCP server for an LLM client; In Rezolus 6.0 and later, --allow-mutating enables the mutating tool (remove_events), --export-dir DIR gives export_query a directory to write into, and --viewer-url URL lets viewer_link return full URLs; install registers it with Claude Code. See MCP Server.

# One-shot PromQL against a recording

$rezolus mcp query out.dendro 'sum(irate(cpu_cycles[1m]))'

# Sweep every metric for anomalies

$rezolus mcp detect-anomalies out.dendro

Recording Tools

$rezolus recording <SUBCOMMAND> [OPTIONS]

Offline operations on recordings — .dendro and .rez archives and .parquet files. 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 .dendro or .rez archive)

--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 recordings into one — multi-node rezolus, multi-instance services, a multi-recording .dendro or .rez, or compare-mode A/B bundles.

FILES... Inputs to merge (parquet, single-recording .rez, or .dendro into a .dendro output)

-o, --output <FILE> Output path; the extension picks the result (.parquet, .rez, .dendro, .parquet.ab.tar)

--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 .dendro or .rez. Useful before sharing a focused report.

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

--samplers <A,B,...> For .dendro and .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 a 5.x 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]

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.dendro"

listen = "0.0.0.0:4242" # optional HTTP API

← API Reference