RustProxy/docs/DASHBOARD.md

# Administration dashboard and preferences

The authenticated panel is the primary way to manage RustProxy. Pages cover **Overview**, **Vhosts**, **Web Server**, **Certificates**, **Docker vhosts**, **Streams**, **Traffic**, **Cache**, **Logs**, **Settings** and **Documentation**. Availability of individual cards depends on enabled features and the account's display preferences.

## Stylesheet updates

The panel and login page load one versioned stylesheet embedded in the Rust
binary. Source styles are split into eight modules and assembled during the
build. Rebuild the binary to apply CSS changes; copying individual CSS files to
an installed server does not update the panel. The authenticated documentation
page has its own stylesheet.

## Overview cards and layouts

The Overview contains live counters, charts and optional backend, cache, PHP, Docker and Stream cards. Under **Settings → Appearance → Dashboard layout** or the Overview editor, configure visibility, order, card width, density and the number of history samples. A hidden card stops consuming its optional browser-side visualization work but does not turn off its underlying proxy feature.

Quick-health tiles shown by default since 0.35.2:

| Tile | Shows |
|---|---|
| **Healthy backends** | Monitored backend members passing health checks as `up / total`, with the names of failing members. |
| **Error share** | Percentage of HTTP requests that ended with an error during the last sampling interval. |
| **Rejected by limits / s** | Requests and connections refused by `--max-connections` / `--max-inflight`; sustained values mean the limits are too low for the load. |
| **Nearest certificate expiry** | Days until the earliest installed certificate expires; the bar is full at 90 days or more. |

Existing layouts receive these tiles at the end of the Overview; hide or move them in the layout editor.

The unlocked Overview layout exposes a single **Save and lock** action (plus Cancel), removing the redundant lock-and-save button.

**Dashboard Presets** supports up to **16 named layouts per administrator**. Save, load, rename, overwrite and delete presets; a factory layout can be restored. Presets preserve the dashboard arrangement, not the live traffic values. Interface theme, scale and other display settings are also account-scoped and do not alter proxy routing or rewrite shared configuration.

## Editing configuration safely

1. Open the relevant workspace and inspect existing state before editing.
2. Change a logically related group of settings and review the editor's effective-preview/status where available.
3. Save against the expected current configuration revision. A stale edit should be reloaded instead of silently overwriting a newer change.
4. Confirm whether the saved setting is active immediately or requires a process restart (notably listener binds and administration HTTPS).
5. Check the live page and request logs after sending test traffic.

Unfinished editors may be minimized into a draft dock; this is a UI convenience and **not** a durable change or backup until saved.

## History and restore

**Configuration history** stores retained validated snapshots. Restoring a snapshot creates a new configuration revision. It does not restore every filesystem file, external certificate, Secret Store key or accumulated cache/log history. For disaster recovery, use a full encrypted backup; see [Backup](BACKUP.md).

## Optional X/Y scales

Under **Settings → Appearance → Charts**, turn on **Show X/Y scales on charts**. It is **off by default**, stored per administrator through `chart_axes: true|false` in `/api/preferences`, and can be reset with **Reset section** or **Reset appearance**. No routing or persistent metric collection changes are required. The optional labels cover sampled SVG line charts in Overview (including backend, cache, Web Server, Stream and optional extra panels), Vhosts, Docker Vhosts, Streams, Web Server live metrics, Cache and Transform activity. Donuts, progress meters and categorical breakdowns have no X/Y sample axes.

- **Y:** `0` through the exact range used to plot the series, using suitable units such as `%`, `ms`, `B`, `B/s` or `/s`. Existing auto-ranging, fixed 0–100% scales and adaptive Vhost/Docker percentile scales are **not recalculated or replaced**. If an isolated Vhost peak is clipped, its actual maximum remains in the legend and the scale annotation identifies the clipped range. On HTTP and WebSocket protocol mini charts where each line is independently normalized, separate Y ranges for H1/H2/H3 are shown rather than an incorrect shared axis.
- **X:** numbers **1 ... N** identify samples in the displayed history, not elapsed seconds or minutes. Sampling can pause and Vhost/Docker/Stream lifetime histories can compact older readings into buckets. The X axis never pretends that sample spacing is uniform time.
- Labels are HTML overlays/footers rather than SVG text so they remain legible with `preserveAspectRatio="none"`. The original SVG path geometry, visible data, styling and refresh rates are unchanged. Switching axes off unwraps the existing SVGs; charts return to their previous appearance without restarting the panel.

If axis labels look crowded in a small card or on mobile, disable the setting; the default presentation is unchanged.

## Interpreting charts

- The **Cache hit ratio** donut shows cumulative `HIT / (HIT + MISS)`: BYPASS and requests outside cache are deliberately excluded from its denominator.
- The **Cache outcomes** compact horizontal 100% bar is **hidden by default**; enable it in **Settings → Appearance → Dashboard layout** or the Overview layout editor. It summarizes **cumulative request counters since the current service process started**, not recent polling intervals. The upper-right number shows the total HTTP requests since service start (full description in its tooltip and accessible label); the legend shows counts and percentages for HIT, MISS, BYPASS and OTHER. The percentages use all HTTP requests as the denominator. BYPASS includes requests where the cache path was considered but disabled/skipped (including globally disabled cache); OTHER covers requests without a cache decision, e.g. early rejected or redirect paths. These are request counts, not bytes; service restarts reset them. Values appear immediately with the first HTTP request; refreshing or pausing the browser does not reset totals. If independently counted cache outcomes exceed the request counter (e.g. while snapshots are inconsistent or a request incurs multiple cache events), the summary shows unavailable rather than fabricating OTHER or a normalized 100% breakdown. The separate recent cache trend chart remains unchanged.


- Live views are process/sampling-based and can show no-data when an integration has not reported yet.
- Per-backend protocol badges can distinguish configured HTTP mode from the protocol actually observed in connection traffic.
- Response-header timing excludes the full streamed body duration. HTTP server/client percentages refer to the specified layer.
- A data sampling gap, a reset after restart and a true zero are not always equivalent.

See [Monitoring](MONITORING.md) for metric details and [Configuration](CONFIGURATION.md) for persistent service settings.