Upgrading to 6.0
What a Rezolus 5.x setup does differently under 6.0, and what to run instead.
6.0 is not released yet.
- 6.0 writes
.dendroarchives only. Asking for.rez, parquet or raw output is refused. - 6.0 opens
.dendroarchives only. A 5.x.rez,.parquetor.parquet.ab.taris converted withrezolus recording upgrade FILE. A.dendrowritten by 5.x opens as it is. - 6.0 records an agent from 5.21.0 or later, over its
/metrics/streamroute. An older agent is refused. - 5.x cannot open a
.dendrothat 6.0 writes.
You record with rezolus record
The output must end in .dendro. Without -o, record writes rezolus.dendro, where 5.x wrote rezolus.rez. Any other output is refused with exit code 2 before an endpoint is contacted, and the message names a 5.x recorder (5.27.0 or later), which still writes the old formats.
rezolus record -o run.rezrezolus record -o run.dendro| 5.x | 6.0 |
|---|---|
record -o run.rez, -o run.parquet, -o run.raw | record -o run.dendro |
record --format parquet (or rez, raw) | Leave out --format. --format dendro is the only value accepted. |
record --separate --endpoint A --endpoint B | record --endpoint A --endpoint B -o run.dendro: one archive, with each endpoint as its own recording. |
record --stream -o run.rez | record -o run.dendro. Every agent is recorded over its stream; --stream is an unknown argument (exit 2). |
--endpoint URL,source=NAME | --endpoint URL,alias=NAME. source= is still accepted and read as alias=, with a note on stderr. |
--metadata producer_epoch=VALUE (or producer_epochs=) | Refused (exit 2). The recorder writes the producer epoch itself; use another key. |
output, format, separate = true in a --config file | The same rules apply: output must end in .dendro, and format other than dendro and separate = true are refused (exit 2). |
A recording's name now lives in its alias label. A recording carries a source label only when its producer declares one. A KPI template or saved query that selects source="NAME" for a name you gave with source=NAME now selects nothing; select alias="NAME" instead.
rezolus record --endpoint http://127.0.0.1:4241,source=web -o s.dendroYou run hindsight
The packaged /etc/rezolus/hindsight.toml changes its output from /var/lib/rezolus/rezolus.rez to /var/lib/rezolus/rezolus.dendro. A SIGHUP capture is written beside it as rezolus-<timestamp>.dendro.
- If you never edited the file, the package upgrade replaces it and hindsight writes to the new path.
- If you edited it, dpkg asks which version to keep (and keeps yours under
--force-confold). rpm keeps yours and writes the new one beside it ashindsight.toml.rpmnew. - A kept file whose
outputdoes not end in.dendrois refused at startup with exit code 1, and the service does not run until you change it. - The files 5.x wrote stay where they are. 6.0 writes
rezolus.dendroandrezolus-<timestamp>.dendro, so anything that reads/var/lib/rezolus/rezolus.rezor globsrezolus-*.rezfinds no dump written after the upgrade. Point it at the.dendronames.
rezolus hindsight /etc/rezolus/hindsight.tomlsudo sed -i 's#^output = .*#output = "/var/lib/rezolus/rezolus.dendro"#' /etc/rezolus/hindsight.tomlsudo systemctl restart rezolus-hindsightHindsight reads the agent's /metrics/stream, so the agent it points at must be 5.21.0 or later. An older agent, or a rezolus exporter endpoint, is refused at startup with exit code 1. Existing .rez dumps are converted as described under You have .rez or parquet files.
GET /dumpon hindsight's HTTP endpoint returns a.dendroarchive (dump.dendro), where 5.x returned a.rez.- Hindsight's
GET /statusno longer hasfailed_scrapesorscrapes_failing_since. Hindsight no longer scrapes; a dropped stream is reconnected after one interval.
You have .rez or parquet files
rezolus view, rezolus mcp, the static-site viewer and every rezolus recording subcommand except upgrade refuse a .rez archive (v1, v2 or v3), a .parquet file and a .parquet.ab.tar A/B tarball, and print the command that converts the file. The exit code is 1, except for recording check, which exits 2. Nothing converts a file when it is opened.
rezolus view old.rezrezolus recording upgrade FILE writes FILE's name with a .dendro extension next to it, and leaves the input unchanged. -o names the output instead. It refuses to replace an existing file.
rezolus recording upgrade old.rezrezolus recording upgrade capture.parquet -o capture.dendrofor f in *.rez *.parquet *.parquet.ab.tar; do [ -e "$f" ] || continue; rezolus recording upgrade "$f"; done- A
.parquet.ab.tarbecomes one.dendrowith two recordings labelledarm=baselineandarm=experiment, which the viewer opens as the comparison.x.parquet.ab.tarbecomesx.dendro. The tarball's aliases and category are not carried over. - A combined parquet written by 5.x
recording combine, or by a 5.x recorder given several endpoints, becomes one recording per input. - In 5.x,
recording upgrade old.rezrewrote a v1 or v2.rezin place as v3, and refused a v3 file ("already a v3 (SQLite) archive", exit 1). In 6.0 the same command converts any.rezversion and writesold.dendrobeside it.--to v3is refused (exit 1);--to dendrois accepted and gives the same result as leaving it out. - A
.dendrowritten by 5.x opens in 6.0 as it is.recording upgradeon it exits 1 with "already a dendro archive; there is nothing to upgrade".
You run agents older than 5.21.0
6.0 records a Rezolus agent only from its /metrics/stream route, which agents serve from 5.21.0 with snapshot_format = "v3" (the default). record, hindsight and the live viewer (rezolus view http://host:4241) refuse an older agent, a snapshot_format = "v2" agent, and a proxy that does not route /metrics/stream. Hindsight and the live viewer also refuse a rezolus exporter endpoint (exit 1).
- At startup,
recordexits 1 and writes nothing. - An agent that comes up during the run, or that answers a reconnect with a refusal, is left out of the recording. The other endpoints are recorded, the archive is finalized, and the run names the agent it left out without failing.
rezolus record --url http://old-host:4241 -o run.dendroEither upgrade the agent to 5.21.0 or later, or record it with a 5.x recorder (5.27.0 or later) and convert the result with 6.0:
rezolus record --url http://old-host:4241 -o run.rezrezolus recording upgrade run.rezYou read 6.0 recordings with 5.x
A .dendro written by 6.0 uses archive schema version 5. That includes record and hindsight output, Save as Report (named <recording>-report.dendro by default, or <baseline>_vs_<experiment>.dendro in a comparison) and the live viewer's Save (rezolus-capture.dendro by default).
rezolus mcp describe-recording run.dendroEvery 5.x release from 5.23.0 opens .dendro schema version 4 only and refuses the file with this message. Releases before 5.23.0 do not open .dendro files at all. No command converts a 6.0 archive to an older format, so upgrade every reader (people, scripts and pipelines) to 6.0 before relying on 6.0 recordings.
Scripts and integrations
- File names: change
*.rezand*.parquetto*.dendroin output paths, globs and artifact collection. - Parquet consumers: a
.dendrois not a parquet file, and 6.0 has no parquet export. Read values withrezolus mcp query FILE 'PROMQL', or keep a 5.x recorder for that pipeline. - Exit codes:
recordrefuses a removed output or flag with exit code 2 (a usage error). A command given a.rezor parquet input exits 1, exceptrecording check, which exits 2. - A Prometheus
_secondshistogram is stored in seconds, as the exporter serves it; 5.x stored its buckets in nanoseconds.histogram_quantileover a 6.0 recording reads seconds, so arecording checkthreshold on it is in seconds (0.25, not250000000). Charts read the unit from the recording and draw either as times. A comparison or combined archive holding a 5.x and a 6.0 recording of one_secondshistogram reads one in nanoseconds and the other in seconds, so its charts and ratios are off by 1e9; compare recordings made by the same major version. rate(x[range])now returns the average rate over[t - range, t]. 5.x ignored the range and returned the per-step rate, the same asirate. A saved query, KPI template orrecording checkwritten for the per-step rate should useirate(x[...]), orrate(x[s])wheresis the step. Gauges,irateandrate(x[s])(withsthe step) return the same values as 5.x at every timestamp 5.x returned. 6.0 may also return a point at the recording's first or last tick.=~and!~are anchored regular expressions, as in Prometheus. 5.x read them as lists of literal alternatives separated by|. Escape a.,+,(,[or\that is meant literally.rezolus mcp query,describe-metrics,detect-anomaliesandanalyze-correlationon an archive with several recordings read them together and exit 0. 5.x exited 1 and listed the recordings. An A/B archive (recordings that carryarm) still exits 1 and needs--recording arm=baselineor--recording arm=experiment.- A query written for one host can now match series from every host, or nothing. Over two hosts,
sum(irate(cpu_usage[5m])) / cpu_coresanswers "No series matched", becausecpu_coreshas one series per host. Usesum by (host) (irate(cpu_usage[5m])) / on (host) cpu_cores, a matcher such ascpu_cores{host="web-01"}, or--recording host=web-01. rezolus mcp queryon a metric the recording has, with a selector that matches no series, prints "No series matched." and exits 0. 5.x printed "Metric not found" and exited 1.- Every series read from a
.dendrocarries its recording's labels:host,source,endpoint,alias, anyrecord --label, and__producer__andarmwhere the recording has them. A series' own label under one of those keys is renamedexported_<key>, so a matcher on the series' own value needs theexported_name. - An archive made by
recording combineopens as an A/B comparison only when its recordings carry anarmlabel. Givecombinethe arms explicitly:rezolus recording combine baseline.dendro experiment.dendro --ab baseline=baseline.dendro experiment=experiment.dendro -o ab.dendro. To open an older combined archive as a comparison, userezolus view ab.dendro --baseline host=A --experiment host=B. When its two recordings have identical labels (two runs combined on one host), no selector can name either one, andviewexits 1 with "matched 2 recordings". Label them by position instead:rezolus recording combine ab.dendro --ab baseline=0 experiment=1 -o ab2.dendro. recording filter x.dendro -o y.dendrorefuses to replace an existingy.dendro(exit 1). 5.x overwrote it.- The agent's
/statusno longer hasindex_resyncs. rezolus-capture(the script and the Docker image) writes onecapture.dendroin--output-dirin place ofcapture.parquetand the per-endpoint parquet files.--source rezolusis refused.- Tools that read the agent's
/metrics/streamdirectly see a new content type,application/vnd.metriken.replication.v1+dendro, andx-metriken-*headers in place ofx-rezolus-*. Every 5.xrecord --streamrefuses a 6.0 agent's stream; drop--stream, and the 5.x recorder scrapes the agent instead. rezolus view a.dendro b.dendroopensb.dendroas the experiment of a comparison. 5.x ignored a second file after a.rezor.dendro, with a warning.
Agent configuration and metrics
- Three pairs of samplers are merged.
[samplers.scheduler_runqueue]and[samplers.cpu_migrations]are now[samplers.scheduler];[samplers.blockio_requests]and[samplers.blockio_latency]are[samplers.blockio];[samplers.syscall_counts]and[samplers.syscall_latency]are[samplers.syscall]. An old section name is read as the new one with a warning. Metric names are unchanged, but thesamplerlabel,rezolus statusandrezolus_bpf_run_timeuse the new names. hw_sensorsis on by default.[samplers.hw_sensors] enabled = falseturns it off. It no longer readsnvmeordrivetemphwmon chips;drivehealthreports drive temperature. It no longer publishes the ACPIProcessorcooling devices (one per logical CPU). Each channel gainsdeviceandnamelabels.tcp_connect_latencyhas anoutcomelabel (established,refused,timeout,error,aborted). A query without anoutcomematcher merges every outcome, timeouts included; add{outcome="established"}for the 5.x meaning. The exporter's percentiles are per outcome.task_cpu_usageleaves out threads younger thantask_min_lifetime(default"1s"). Set"0s"for the 5.x behaviour.- Setting
task_attribution = truealso turns onprocess_attributionunless it is set. Setprocess_attribution = falsein[samplers.cpu_usage]for the 5.x behaviour. memory_slabinfopublishesmemory_slab_cache_bytesfor every slab cache (up to 1024).caches = "fixed"in[samplers.memory_slabinfo]keeps the 5.x set of eight. Bothmemory_slab_cache_*metrics gain anidlabel, so a Prometheus server sees new series for every cache.ext4_journalreports in nanoseconds instead of jiffies.phase="wait"andphase="request_delay"are removed. Its values are not comparable with 5.x recordings.- On macOS,
cpu_usageis one series per CPU with anidlabel, and thenicestate is gone (niced time counts asuser).
Removed flags
| 5.x | 6.0 result | Instead |
|---|---|---|
record --format rez|parquet|raw | exit 2 | Leave it out; output is .dendro. |
record --separate | exit 2 | One archive with a recording per endpoint. |
record --stream | exit 2 (unknown argument) | Leave it out; agents are always streamed. |
recording upgrade --to v3 | exit 1 | recording upgrade FILE |
recording combine -o x.parquet, -o x.rez, -o x.parquet.ab.tar | exit 1 | -o x.dendro; add --ab baseline=A experiment=B for a comparison. |
recording combine --pinned, --category, --bypass-time-check | exit 1 (--category without --ab: exit 2, a usage error in 5.x too) | Leave them out. |
recording annotate --source, --node, --filter | exit 1 | Name a recording when it is recorded (--endpoint URL,alias=NAME or --label); shrink one with recording filter. |
recording filter --queries, --templates | exit 2 (unknown argument) | recording filter --samplers or --metrics. |
recording metadata --schema, --file, --geometry, --field | exit 2 (unknown argument) | recording metadata -i FILE (add --json for machine-readable output). |
recording filter, annotate, check --annotate editing a .rez or parquet in place | exit 1 (check: exit 2) | Convert with recording upgrade, then edit the .dendro in place or write a copy with -o. |
recording convert to parquet | refused | recording convert FILE.raw writes a .dendro. |
| Viewer Time selector (Aligned/Raw) | removed | Open a chart on its own (the open-in-new-tab link) and use SHOW SAMPLES. |