Dashboards

The Proxima Console frontend provides interactive metric dashboards at three levels: per-host, per-environment, and per-client.

Host Metrics Dashboard

Accessed from the host detail page. Shows all metrics collected from a single host.

Panels

The dashboard automatically discovers available metrics and renders them in organized sections:

Section	Metrics	Chart Type
CPU	cpu_usage_ratio, cpu_iowait_ratio, load averages	Area chart
Memory	memory_used_ratio, memory_used_bytes, memory_available_bytes, swap	Area chart
Disk	disk_used_bytes / disk_total_bytes per mount now; disk_used_ratio (per partition) over time	Per-mount meters; the line chart behind Show history (see Disk space)
Disk I/O	disk_read_bytes_total, disk_written_bytes_total (per device, derivative)	Multi-series line chart
Network	network_receive_bytes_total, network_transmit_bytes_total (aggregated, derivative)	Area chart

Features

• Time picker — one shared MetricsToolbar on every metrics view (host, environment, client and integration dashboards, and the process and container drill-downs): [Add note] [⚙] ‹ [range · start → end] › [Compare: …] [⟳ 1m ▾] [Reset zoom]. It wraps at phone width. See Time picker below.
• Crosshair synchronization — Hovering on one chart shows a vertical crosshair on all sibling charts at the same timestamp. Uses a shared CrosshairContext with 60ms throttle (Grafana EventBus pattern). Each chart publishes its hover timestamp; other charts draw a ReferenceLine at that exact time on their numeric time axis, so charts sampled at different steps still line up and no line is broken by the crosshair.
• Drag-to-zoom — Click and drag on any chart to zoom into a specific time range. A ReferenceArea overlay provides visual feedback during the drag. The zoom is committed to the shared DashboardTimeRangeContext, so all charts on the dashboard zoom together. A "Reset Zoom" button returns to the relative time range. Zoom bounds are persisted to the URL (?from=...&to=...).
• Polling pause on zoom — Auto-refresh is disabled when the dashboard is in a zoomed (absolute time range) state: nothing new can arrive in a window that has already ended, and the zoom is never moved by a refetch.
• Series toggle — Click a legend item to isolate (solo) that series. Ctrl/Meta/Shift+click toggles individual series visibility without affecting others. A "Reset View" button restores all series. Toggle state persists in localStorage.
• Auto-refresh with a sliding window — Charts refresh on an interval set by the refresh= URL parameter: off, 30s, 1m (default), 5m or 15m. A relative range really slides: on every tick "Last 1 hour" is re-resolved against the current time, so it keeps ending at now instead of repeating the window that was resolved when the page opened. Refresh pauses while zoomed (absolute range), while the note composer is open, while the browser tab is hidden (it catches up at once when the tab becomes visible again), and when set to off. Between ticks every panel queries exactly the same window, and a chart keeps its previous data on screen while the next window loads instead of flashing to a skeleton.
• Adaptive formatting — Values are formatted contextually:
  • Percentages: 45.2%
  • Bytes: 1.5 GB, 256 MB
  • Throughput: 12.3 MB/s
  • Bit rates: 95.4 Mb/s
• Gap detection — When data points are missing (gap > 2x expected interval), the chart disconnects the line to avoid misleading interpolation
• Docker container labels — Multi-series charts for Docker metrics extract container_name=... from label keys for readable legend entries instead of showing raw label strings
• Summary tiles — The row above the host, environment, project and integration charts shows one tile per headline metric: the current value with its unit, a sparkline of the range, and the peak. A tile past its warning or critical threshold says so with an icon and a word, not only a colour. On a host with several mounts, the Disk tile shows the fullest mount that has reported in the last 15 minutes and names it ("/data · peak 93.0% at 14:30"); it used to show whichever mount the API listed first. Integration tiles take a warning or critical tone only from a threshold you have set for that metric in the Customize panel. None is invented for them. On the environment and project dashboards each tile shows the worst host instead — see Environment / Project Dashboards.

Disk space

The Disk section answers "how full is each mount right now?" with one horizontal meter per mount instead of a line chart:

• Order and limit: fullest first. Eight rows show, then a +N more button.
• Each row: the short mount name (/, /data; the full series key is in the tooltip), the fill, and "425.0 GB of 500.0 GB".
• Threshold ticks: at your disk warning and critical thresholds from the Customize panel (default 70% / 90%), not a fixed 85%.
• Over a threshold: the row adds an icon and the words Above warning or Above critical. The fill itself stays the same blue, so status is never carried by colour alone.
• Screen readers: each meter is announced as a meter ("/data 85% used, 425.0 GB of 500.0 GB").

Which mounts appear:

• Always the current state. The meters read the last 15 minutes, whatever range the dashboard shows. On an absolute or zoomed range they stop refreshing, like the rest of the page.
• Hidden: a mount with no reading in the last 15 minutes (unmounted since), or one reporting a total of 0.
• Host disks only. Mounts under a container runtime's or the kubelet's directory (/var/lib/kubelet/, /var/lib/docker/, /var/lib/containerd/, /var/lib/rancher/), under /run/ or /snap/, the pseudo-filesystems /proc, /sys and /dev, and overlay, tmpfs, squashfs and nsfs filesystems are pod volumes and runtime internals, not the host's disks: they are left out and never read. A disk mounted at /var/lib/docker or /var/lib/kubelet is the host's own and stays. The Topology Traffic tab's Disk row uses the same rule. The Show history chart is not filtered: it still draws every mount the agent reports.
• Refresh failures: if a refresh fails, the last values stay on screen with "Couldn't refresh — showing last known values". If some mounts could not be read, the section says so.

Show history reveals the usage line chart. Your choice is remembered in this browser, for every host. The data comes from the existing host metric endpoints, so there is no new API.

Chart style

All metric charts follow the charts standard:

• Header value — single-series charts show the latest value top-right with average and peak for the range underneath.
• Colours — up to five series get distinct, colour-blind-safe colours that stay fixed when you hide others; any further series are drawn in grey and remain in the legend and tooltip.
• Thresholds — dashed lines labelled with their value ("70% warning"). When a hovered value is over a threshold, the tooltip says "Above warning" or "Above critical" with an icon.
• Legend — click a series to show only it (click it again to show all); Ctrl/⌘/Shift-click to toggle one series.
• End labels — charts with two to four series label each line at its last point with its name and latest value.
• Exact time — the time axis is numeric (epoch ms), so a marker sits at its real timestamp (14:17 on an hourly chart is drawn between 14:00 and 15:00, not snapped to a row) and never inserts a row into the data.
• Gaps — when an agent stops reporting, the line breaks instead of bridging the missing period. Markers never break a line.
• Marker rail — notes, alert windows, deploys, config changes and agent-offline events on a strip above the plot, each opening a card. An alert's symbol and firing band take its severity: red for P1/P2, amber for P3, grey for P4/P5 and unknown. For ranges over 30 days, no notes or markers are drawn, and the toolbar says "Notes and markers show for ranges up to 30 days" (the notes and markers APIs cap a window at 30 days). See Chart Notes & Markers.

Time picker

One time control per page, the same everywhere: host, environment, client and integration dashboards, and the process and container drill-downs (which share the host Metrics tab's URL, so a range chosen on one follows you to the other). Monitor pages keep their own look-back selector (their API is look-back only), and list filters on Alerts / Changes / Topology are not chart ranges.

• Range button — the preset's name plus the resolved window in your local time (Last 1 hour · 24 Sep 14:00 → 15:00; the times hide on narrow screens). ‹ / › shift the window by half its length.
• Popover — Absolute From/To fields (prefilled with the window you are looking at), Recently used ranges, and a search box that also accepts an expression (now-2d, or A to B) and applies it on Enter. Presets come in two groups: Relative (Last 15 minutes … Last 30 days) and Calendar (Today so far, Yesterday, This week, Previous week). A line states your browser's time zone; calendar ranges (now/d, now/w) start at 00:00 UTC.
• Compare — Compare: Off / Previous period / Yesterday / Last week, the vs= URL parameter (see Time Comparison). Overlaid on single-series charts only.
• Refresh — ⟳ refreshes now: it re-resolves a relative window (so "Last 1 hour" ends at the new now) and simply refetches an absolute one. The menu next to it sets the interval (Off / 30s / 1m / 5m / 15m, the refresh= URL parameter, default 1m). It pauses while zoomed, while a note is being written, and while the tab is hidden, and the button says · paused when an interval is set but not running.
• Reset zoom — back to the relative range after a drag-zoom.
• Keyboard — T opens the picker, [ / ] shift the window, Z zooms out ×2 around the centre (never past now), Esc resets the zoom. Shortcuts are ignored while typing in a field, with a modifier key held, and while a note or menu is open.

Environment / Project Dashboards

Accessed from the environment detail page, or from the Metrics tab on the client (project) detail page. Nothing on either dashboard is an average across hosts: every chart draws one line per host, and every summary tile names one host. (Until this release both showed metrics averaged across all hosts; that view is gone, because an average hides the one host that is in trouble.)

• Charts: one chart per metric, one line per host — the Per host rules below (top five hosts by peak coloured, the rest grey; worst mount for a ratio, sum across devices otherwise; one shared time grid).
• Summary tiles — worst host: each tile shows the current value of the worst host and names it, e.g. 91.0 % with web-03 · peak 93.0% at 14:30 underneath; the sparkline is that host's line. "Worst" is the highest latest value — every tile metric (CPU, Memory, Disk used, Load Avg) is worse when higher, so there is no lower-is-worse rule. Load Avg is the raw 1-minute load, not divided by cores. The Disk tile uses each host's fullest mount and names it too (db-02 · /data · peak …). A host whose last point is older than 15 minutes before the end of the range cannot be the worst "now" (unless no host is that recent). The tiles follow the host and environment filters. A tile with no data reads —.
• Host filter (toolbar, both dashboards): a searchable multi-select of hosts; on the project dashboard each host shows its environment. All hosts (empty) draws every host with the top five by peak coloured. Picking hosts draws exactly those, coloured in the order you picked them (the first five take the five colours; a sixth and later are grey, with a note). A clear (×) button resets it. The selection is in the URL as ?hosts=id1,id2, so a link shares the view. Only the selected hosts are fetched.
• Environment filter (project dashboard only, shown when you can read more than one environment): All environments, or one environment. Only environments where you hold metrics:read are listed. In the URL as ?env=<id>; a link to an environment you cannot read opens as All environments. Changing it drops selected hosts that are not in the new environment.
• Time compare is not offered here: it overlays single-series charts, and every chart here has a line per host.
• 100-host cap: at most 100 hosts are fetched and drawn. The server enforces it: with more in scope and no host filter, it returns only the 100 busiest — the 100 with the highest CPU usage peak over the selected range — and says so (truncated, hosts_total); the dashboard then shows "Showing the 100 busiest hosts (highest CPU peak in this window) of N — filter by environment or host". Selecting more than 100 hosts draws the first 100 picked and says "Showing the first 100 of the N selected hosts".
• Stale links: host IDs in ?hosts= that are no longer in scope (a deleted host, another environment's host) are dropped from the URL once the host lists load, and the filter's label counts only real hosts.
• Data: one request per metric for the whole scope, GET /api/v1/clients/{id}/metrics/{metric}/hosts (see API Endpoints Used), never one per host.

Project Metrics tab. The tab sits after Environments.

• Who sees it: anyone who holds metrics:read for the whole client, or for at least one of this client's environments. This mirrors the backend check on /clients/{id}/metrics*. A grant on another client's environment does not count. A viewer with access to some environments only sees those environments' hosts — the backend confines the data to them.
• Deep links: without that permission the tab is not shown, and a ?tab=metrics link opens Environments instead.
• View modes: the project dashboard is always per host; it has no heatmap.

Integration Metrics

When a host has integration collectors configured (e.g., PostgreSQL), an additional Integrations tab appears on the host detail page.

• If multiple collectors of the same type exist, a picker allows selecting which collector's metrics to display
• Integration metrics are identified by the collector=<name> prefix in their labels_key
• Crosshair sync and drag-to-zoom work the same as on the host dashboard (shared DashboardProvider)
• See PostgreSQL Integration, Nginx Integration, and Docker Integration for available metrics

Dashboard Customization Slider

A collapsible right-side panel (280px) for customizing metric dashboards. Toggle it via the gear button in the metrics toolbar. The slider is available on Host, Environment, Client, and Integration metrics pages.

Opening the Slider

• Click the Settings (gear) button in the MetricsToolbar
• The slider appears on the right and the charts area shrinks to accommodate it
• State (open/closed and section expand state) is persisted in localStorage

Configurable Panels

• Toggle visibility of metric chart groups and summary cards
• Reorder panels with up/down buttons
• Preferences are saved per page, keyed by dashboard-prefs:<pageKey>
• Reset to Default restores the original panel configuration

Threshold Lines

• Horizontal dashed lines on charts indicate warning (amber) and critical (red) levels
• Configurable per-metric via number inputs — displayed as percentages, stored internally as 0-1 ratio values
• Defaults: CPU, Memory, and Disk at 70% warning / 90% critical

Host Comparison (Host page only)

• Overlay up to 2 other hosts' metrics as dashed lines on each chart
• URL-shareable via ?compare=host-id-1,host-id-2
• Each comparison host uses a distinct color (copper, then teal) against the current host's blue. Only three colours stay distinguishable for colour-blind users, which is why the limit is 2; an older link that lists 3 hosts opens with the first 2.

Environment View Modes (Environment page only)

Two modes, switched with the Per host / Heatmap control in the dashboard toolbar (next to the host filter and the time picker; it wraps onto its own line on a narrow screen). The mode is in the URL as ?view=heatmap (Per host is the default and is left out). There is no averaged mode any more: an old link with ?view=averaged opens Per host.

• Per host (default) — every host drawn as a separate line, one chart per metric (network inbound and outbound, disk read and write, and load 1/5/15 min each get their own chart, titled by that metric):
  • Colours: the five hosts with the highest peak over the selected range get the five chart colours, in hostname order, so a host keeps its colour while the top five stay the same. Every further host is drawn thinner in grey, still in the legend and tooltip, and a note under the chart says "+K more hosts (muted)". Colours are never repeated. The top five are chosen separately for each chart, so a host can have one colour on CPU and another on Memory; on one chart a host keeps its colour as long as the top five stay the same.
  • Several series per host: where a metric has one series per mount, device or interface, each host still draws one line. For a ratio (disk usage per mount) it is the host's worst mount — the highest latest value, the same rule the heatmap uses. For throughput and counts (disk read/write bytes and operations per device, network per interface) it is the sum across the host's devices — the host's total — so the line does not jump when a different device becomes the busiest. A step where only some devices reported sums those; a step with none is a gap.
  • Alignment: each host's samples are placed on one shared time grid at the chart's step, so the lines are continuous even though hosts report a few seconds apart. A host with no data for a step shows a gap there; gaps are never bridged.
• Heatmap — a grid with one cell per host, shaded on a single-hue blue ramp (light = low, dark = high, eight steps). Colour shows the amount, never a status:
  • Threshold outline: a cell at or above your warning threshold for the selected metric gets a dark outline, and its label says "at or above warning (70%)". The threshold is the one from the Customize panel, not a fixed value. With no warning set, there is no outline.
  • Metrics: CPU, Memory, Disk and Inodes (the inode used ratio, disk_inodes_used_ratio). Inodes are fetched only while the heatmap is shown, since they are not a dashboard panel. The Customize panel has no inodes threshold (it lists thresholds for the CPU, Memory and Disk panels), so inode cells carry no outline.
  • Disk and Inodes: the cell shows the host's fullest mount.
  • Hosts: the heatmap shows the hosts the host filter selects (all hosts when it is empty).
  • Charts in heatmap mode: the same per-host charts as Per host, below the grid.
  • Highlighting a host: click a cell to highlight that host (click again to clear). The host then always takes one of the five colours on the charts below — if it is not among the five busiest, it replaces the one with the lowest peak — so you can pick it out against the others. (It used to be drawn beside an averaged "Environment" line, which no longer exists.) With a host filter set, the filter's own colour order applies instead.
  • No data: a host with no data is hatched.
  • Legend: the ramp from 0% to 100%, plus the outline swatch.

Event Markers

Drawn on the marker rail above each chart, at their exact time — see Chart Notes & Markers. Toggles under Events in the Customize panel: Alerts (on by default — fire-time symbol plus a shaded firing window), Deploys (off — ArgoCD sync / sync failed, GitHub release, GitLab tag; from GET /api/v1/chart-markers), Config changes (off — agent file changes) and Agent offline (on) — the last two from GET /api/v1/events/timeline. Console's own audit events (config pushed, credential updated…) are no longer drawn; they live on the Changes page. Client dashboards show notes, alerts and deploys only (the events timeline has no client filter).

Time Comparison

• Set by the vs= URL parameter (so a comparison survives reloads and can be shared as a link): off (default), prev — the period immediately before the current window, the same length ("previous period"), 1d — the same window a day earlier ("yesterday"), or 7d — a week earlier ("last week"). compare= is not used for this: it belongs to host comparison.
• Current period renders as a solid line; the comparison renders as a faded dashed line on single-series charts, labelled with the words above
• The comparison window slides with the current one on every refresh tick
• Available on host and integration dashboards. The environment and project dashboards do not offer it (every chart there has a line per host). It is no longer a Customize-panel section, and the old per-browser "Show previous period" setting is ignored

Custom Panels

Two modes for adding user-defined panels:

• Metric Picker — search the available metrics for a host or environment and add them as new chart panels
• Expression Editor — enter arbitrary MetricsQL expressions with custom labels

Custom panel queries are proxied through the backend via POST /api/v1/metrics/query, which applies tenant-scoped filtering before forwarding to VictoriaMetrics.

Notes

Notes are scoped to a host, an environment (shown on every host in it) or a client, can be a point or a range, and are edited only by their author. Add one by double-clicking a chart, pressing N over it, or with Add note in the toolbar. Creating needs annotations:write. Full rules: Chart Notes & Markers.

Feature Availability by Page

Feature	Host	Environment	Client	Integration
Panel Toggle/Reorder	✓	✓	✓	✓
Thresholds	✓	✓	✓	✓
Host Comparison	✓	-	-	-
View Modes	-	✓ (Per host / Heatmap)	- (always per host)	-
Host Filter	-	✓	✓ (+ environment filter)	-
Event Markers	✓	✓	✓ (notes, alerts, deploys)	✓
Time Compare	✓	-	-	✓
Custom Panels	✓	✓	✓	✓
Notes	✓	✓	✓	✓

Dashboard Context

HostMetricsPanel, IntegrationMetricsPanel, and AggregateMetricsPanel all wrap their content with a DashboardProvider that provides two shared React contexts:

• DashboardTimeRangeContext — Manages the time range as string expressions (from/to — e.g. "now-3h" / "now" for relative, ISO strings for absolute). Computes rangeHours (for step calculation), startMs/endMs (the resolved window in epoch ms, re-resolved on every refresh tick for a relative range), startISO/endISO (the same window as ISO strings), and isZoomed (true when both bounds are absolute). Carries refresh / setRefresh and refreshIntervalMs (false when refresh is off, zoomed, or the tab is hidden), tick() (re-resolve now immediately — a manual refresh), and vs / setVs with compareOffsetMs (prev → the window length, 1d → 86 400 000, 7d → 604 800 000, off → null). Provides setTimeRange, shiftRange, zoomTo, resetZoom. The state is persisted to URL search params (?from=...&to=...&refresh=...&vs=...); an invalid refresh or vs falls back to its default, and a default value is left out of the URL. now/d-style rounding stays in UTC.
• CrosshairContext — Manages the shared hover timestamp and panel ID. Charts publish their hover position; sibling charts consume it to render synchronized crosshair lines.

The host and integration dashboard hooks (useMetricDashboard, useIntegrationMetricDashboard) accept options.startISO, options.endISO, and options.refetchInterval; panels pass the context's refreshIntervalMs (as do useCustomMetric and useEventsTimeline). Because every query key carries the window, a tick produces a new key and therefore a fetch; keepPreviousWindow (lib/window-placeholder.ts) keeps the previous response as placeholder data only when nothing but the window changed, so a chart never shows another host's or environment's data under a new heading. The environment and project dashboards use useHostSeriesMetrics (below), whose per-metric queries use cachedPreviousWindow for the same purpose.

Data Fetching

The useMetricDashboard hook implements a two-phase fetch strategy:

1. Discovery — Call GET /hosts/:id/metrics to find all available metric names, intersect with configured METRIC_GROUPS
2. Parallel fetch — For each metric, discover series (via GET /hosts/:id/metrics/:name/series) and fetch data for each labels_key in parallel

Network metrics skip series discovery and fetch aggregated data directly (backend aggregates across interfaces when labels_key is empty).

The environment and project dashboards use useHostSeriesMetrics instead:

1. Hosts in scope — GET /environments/:id/hosts (every page) for each environment in scope: the environment itself, or the project's environments the viewer can read (narrowed by the environment filter).
2. One request per metric — GET /clients/:id/metrics/:name/hosts with environment_id (the environment dashboard, or the environment filter) and host_ids (the host filter, if any). The response has one series per host and labels_key; the page folds each host's series into one line as above. With no host filter the server caps at 100 hosts itself (the same CPU-peak ranking for every metric of one window); when a response says truncated, the page draws the hosts the server returned and shows the notice with its hosts_total.

API Endpoints Used

Dashboard Level	List Metrics	Query Data	List Series
Host	GET /hosts/:id/metrics	GET /hosts/:id/metrics/:name	GET /hosts/:id/metrics/:name/series
Environment	GET /environments/:id/metrics	GET /environments/:id/metrics/:name	GET /environments/:id/metrics/:name/series
Client	GET /clients/:id/metrics	GET /clients/:id/metrics/:name	GET /clients/:id/metrics/:name/series
Environment / project dashboards (per host)	—	GET /clients/:id/metrics/:name/hosts	—

All data endpoints accept start, end, and derivative; the aggregate ones also labels_key. The environment and client aggregate endpoints (avg() across hosts) are no longer used by the dashboards; they remain for API and custom-panel callers.

GET /api/v1/clients/{id}/metrics/{metricName}/hosts returns {series: [{host_id, labels_key, data: [...]}], truncated, hosts_total} — one series per host and labels_key (mount, interface), in one VictoriaMetrics query (sum by (host_id, labels_key), or max by over a computed ratio). Never an average.

Server-side cap: with neither host_ids nor top, the server first ranks every host in scope by CPU usage peak over the window (one instant query, one row per host) and, past 100, queries only the 100 busiest — truncated: true, hosts_total = hosts ranked. A failed ranking fails the request; it never falls back to an uncapped query. Hosts that report no CPU metrics are not counted by the ranking. host_ids above 100 is a 400, not a silent truncation: the caller named those hosts, so dropping some would return a different answer than it asked for.

Query parameters:

Parameter	Meaning
environment_id	One environment of the client. Must belong to the client (else 404) and be readable by the caller (else 403).
host_ids	Comma-separated host UUIDs, at most 100.
top	1–100: keep the N series with the highest peak over the window (topk_max). It ranks series, not hosts: on a multi-series metric (disk mounts, interfaces) one host can take several places. Meant for a one-series-per-host metric such as cpu_usage_ratio, where it ranks hosts.

Authorization: metrics:read in any scope to reach the handler, then metrics:read on the client (a client-wide grant, or a grant on one of this client's environments). Every environment of the client is read only for a caller holding metrics:read client-wide (super-admin included); anyone else gets exactly the environments of this client it can read, and none is a 403 — the environment resolution refuses on its own, not only because the check before it did. A client with more than 1,000 environments is queried for the first 1,000 and a WARN is logged. The query always carries an environment_id matcher — for a client-wide caller, every environment of the client — so a host_ids filter cannot reach another client's hosts even on single-node VictoriaMetrics, where the tenant path does not separate clients.