Investigating a Rezolus recording

The rezolus MCP server opens a recording file and answers about it. Every tool that reads a recording takes parquet_file, the path to a .parquet, .rez or .dendro file (the name is historical; the format is detected by content). A .rez is Rezolus's archive, which can hold several recordings; a .dendro is the newer archive container and reads the same way. viewer_link reads no recording and takes no path. Ask the person for the file if you were not given one; rezolus record -o out.dendro writes one.

Workflow

1. describe_recording first. It says what the file holds: source, agent version, time range, duration, and, for a multi-recording .rez, the list of recordings with the recording selector that picks each.
2. describe_metrics before any query. Metric names, types and labels come from the recording, not from memory. A counter is queried with irate(name[1m]) (the per-step rate; rate(name[5m]) is the average over five minutes), a gauge directly, a histogram with histogram_quantile(0.99, name).
3. extract_features for the overview: per-metric stats, noise class, anomalies, regime shifts, uncertainty, correlations, resource rankings. Read it before forming hypotheses; it needs at least 10 s of data.
4. query, detect_anomalies, analyze_correlation to test specific hypotheses. detect_anomalies and a check need ONE series: aggregate with sum() / avg() or add label matchers.
5. Write back what you found (below), and hand the person a link.

Rules that hold on every recording:

• A missing metric is not zero. A sampler that was off or a kernel without the hook leaves the metric absent; say so rather than reading it as idle.
• irate() and rate() values carry an uncertainty band [lo, hi] from the acquisition window: in query JSON it is the bands (and intervals) list aligned with values. A difference inside the band is not a difference. A recording with no acquisition windows (for example a parquet combined into a .rez) has no band, which says nothing about its precision.
• Correlation does not establish causation. Report it as co-movement.
• On a multi-recording archive of one run, the tools read every recording together unless a recording selector (e.g. {"source": "redis"}) names one: each series carries its recording's labels, so sum by (host) answers per host and {host="web-01"} selects one. extract_features needs a selector, and so does every tool on a comparison (recordings carrying arm). Matching none or several is an error that lists the candidates; it never guesses. run_checks without a selector evaluates every recording and gives each its own verdicts.

Writing back

• add_event marks an instant or a range (duration) in the recording; the viewer draws it on the timeline. Give a kind (finding, spike, incident, deploy), a one-line description, and put the evidence (the query, the numbers) in details. source defaults to mcp, so your marks can be filtered or removed as a group. timestamp is RFC 3339 or Unix seconds as a JSON number (never a digit-only string). The reply carries the event id; adding an event with an id already present changes nothing, so retrying is safe (a kind=check event is the exception: it replaces a stored check event with the same id).
• run_checks evaluates the recording's KPI checks (or a ServiceExtension object you pass as queries) and returns each verdict with its violation windows; annotate: true writes them as events.
• export_query writes a range query as CSV or parquet (long form: series, timestamp, value, lo, hi) for analysis outside PromQL. It works only when the server was started with --export-dir. filename is a bare name (no directories) and an existing file is never overwritten; step defaults to 1 s; results over a million rows are refused, so raise step or aggregate; a heatmap is refused, so export histogram_quantile(...) of it.
• viewer_link builds a link into a running rezolus view: a section (cpu, memory, ..., or service/<name>), optional chart_id, from/to, and the rest of the view state. With viewer_url (or a server started with --viewer-url) it is a full URL; otherwise append the returned query and fragment to the viewer's address.
• remove_events exists only when the server was started with --allow-mutating. It removes by ids, kind and/or source; an empty filter is refused.

Reporting

Lead with the finding and the instant it happened, then the evidence (metric, query, values with their bands), then what you wrote back (event ids) and the link. State what could not be measured.