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] <URL> <OUTPUT>

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

-d, --duration <DURATION> Collection duration

-f, --format <FORMAT> parquet|raw [default: parquet]

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

--endpoint <URL> Additional endpoint (repeatable)

--metadata <KEY=VALUE> Custom metadata (repeatable)

--node <NAME> Node name attached to rezolus data

--instance <NAME> Instance name attached to service data

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

-v, --verbose Increase verbosity (stackable)

# Record 30s at 100ms intervals

$rezolus record -i 100ms -d 30s http://localhost:4241 output.parquet

Hindsight

$rezolus hindsight <CONFIG>

Rolling ring buffer. Send SIGHUP to trigger snapshot.

Viewer

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

INPUT First capture (parquet path, 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)

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

-v, --verbose Increase verbosity

# View a recording

$rezolus view output.parquet

# View live agent

$rezolus view http://localhost:4241

MCP Server

$rezolus mcp [SUBCOMMAND]

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

describe-recording <FILE>

describe-metrics <FILE>

detect-anomalies <FILE> [QUERY]

query <FILE> <QUERY>

Parquet Tools

$rezolus parquet <SUBCOMMAND> [OPTIONS]

File-level operations on rezolus recordings — inspect metadata, trim columns, embed service KPI definitions, or merge multi-source captures.

`metadata`

Show file-level + column metadata for a recording.

-i, --input <FILE> Input parquet file

--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 attached to rezolus columns

--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... Parquet inputs to merge

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

--pinned <NAME> Default rezolus node to display

--ab <LABEL=SRC> Bundle as A/B compare tarball (repeatable: baseline=… experiment=…)

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

--bypass-time-check Skip timestamp alignment validation

`filter`

Project a recording down to only the columns referenced by its service-extension KPIs — useful before sharing a focused report.

FILE Parquet to filter

--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)

# Inspect

$rezolus parquet metadata -i recording.parquet --json

# Annotate with KPIs from a template directory

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

# Combine two captures as an A/B bundle

$rezolus parquet combine before.parquet after.parquet \

--ab baseline=before --ab experiment=after \

-o compare.parquet.ab.tar

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