v0.34.2
This commit is contained in:
Mateusz Gruszczyński committed
1 parent
34fb534e02
commit
b2b5b45d8a
22 files changed
+2146
-107
No files matched your search
@@ -23,6 +23,7 @@ The current bundled `src/admin/openapi.json` declares these operations (among ot
|
||||
| `GET /api/logs` · `GET /api/live-logs` | Recent and streaming request logs. |
|
||||
| `GET /api/file-logs` · `GET /api/file-logs/query` | Stored-log exploration. |
|
||||
| `GET /api/traffic` · `GET /api/system-info` | Traffic and system observations. |
|
||||
| `GET /api/metrics/json` · `GET /api/metrics/summary` | Full JSON snapshot (includes all Prometheus samples and `summary`) or compact computed `summary` only, both pull-only. [Monitoring](MONITORING.md). |
|
||||
| `GET /api/docker` · `POST /api/docker/refresh` | Docker-agent observation and refresh. |
|
||||
| `GET /api/certificates` · `POST /api/certificates/upload` | Certificate inventory/import. |
|
||||
| `GET /api/acme` · `POST /api/acme/issue` · `POST /api/acme/renew` | Managed certificate jobs. |
|
||||
|
||||
@@ -42,6 +42,117 @@ scrape_configs:
|
||||
|
||||
When using a bearer token, configure Prometheus `authorization` or `bearer_token_file` securely rather than embedding a clear token in an exported dashboard. Review `grafana/README.md` and `grafana/rustproxy-overview.json` for chart examples; `nagios/README.md` contains external check scripts.
|
||||
|
||||
## JSON metrics API for external dashboards
|
||||
|
||||
RustProxy also offers a **plain, read-only JSON snapshot**. It does not use SSE,
|
||||
WebSockets or persistent subscriptions: clients poll using ordinary `GET` (for
|
||||
example, every 2–5 seconds).
|
||||
|
||||
| Endpoint | Where | Authentication |
|
||||
|---|---|---|
|
||||
| `GET /api/metrics/json` | Administration listener (default `127.0.0.1:9090`) | Admin session or a **General API** `ro`/`rw` Bearer token from **Settings → Security**, restricted by allowed CIDRs |
|
||||
| `GET /api/metrics/summary` | Administration listener, compact calculated metrics only | **Same** admin session/General API Bearer credentials and CIDR policy |
|
||||
| `GET /metrics.json` | Dedicated exporter (default `127.0.0.1:9191`, **only when Prometheus is enabled**) | Same allowed CIDRs and exporter Bearer token as `/metrics`; not an admin/API token |
|
||||
| `GET /metrics.summary.json` | Dedicated exporter, compact calculated metrics only | **Same** exporter Bearer token/CIDR policy, if enabled |
|
||||
|
||||
When the exporter `path` differs from `/metrics`, the JSON routes append
|
||||
`.json` and `.summary.json` to that path (e.g. `/private/stats` →
|
||||
`/private/stats.json` and `/private/stats.summary.json`). Exporter routes
|
||||
reject query strings. Every JSON response uses `application/json` and
|
||||
`Cache-Control: no-store`; do not expose these endpoints publicly.
|
||||
|
||||
For a dedicated integration, issue a General API token with **read-only**
|
||||
permission and a narrow `allowed_cidrs` set. Example from a permitted client:
|
||||
|
||||
```sh
|
||||
curl -fsS -H "Authorization: Bearer $RUSTPROXY_API_TOKEN" \
|
||||
http://127.0.0.1:9090/api/metrics/json | jq '{vhosts: .vhosts | {total,enabled,disabled}, requests: .requests.total, cpu: .system.cpu_percent, ram_bytes: .system.process_rss_bytes}'
|
||||
```
|
||||
|
||||
### Summary: ready for dashboard cards
|
||||
|
||||
For the shortest response, poll **`/api/metrics/summary`** (or the standalone
|
||||
exporter's `.summary.json` sibling) instead of loading every Prometheus sample.
|
||||
The full `/api/metrics/json` includes the **same calculated object** at `summary`.
|
||||
The response groups all values into `vhosts`, `backends`, `traffic`, `system`,
|
||||
`cache`, `web_server`, `streams` and `capacity`, plus a collection timestamp.
|
||||
|
||||
```sh
|
||||
curl -fsS -H "Authorization: Bearer $RUSTPROXY_API_TOKEN" \
|
||||
http://127.0.0.1:9090/api/metrics/summary | \
|
||||
jq '{working_vhosts: .vhosts.serving_estimate, backends: .backends.total, \
|
||||
backend_up: .backends.up, rps: .traffic.requests_per_second, \
|
||||
traffic_mb: .traffic.megabytes_total, cpu: .system.cpu_percent, \
|
||||
ram_percent: .system.memory_percent}'
|
||||
```
|
||||
|
||||
- `vhosts.enabled` is the configured on/off flag. `vhosts.serving_estimate`
|
||||
counts enabled vhosts using a ready backend pool or an embedded Web Server.
|
||||
It is **not** an HTTP probe or guarantee of reachability; redirect hosts,
|
||||
not-found hosts and Docker assignments are counted separately. Only enabled
|
||||
vhosts with a compiled pool are included in `backend_ready` / `backend_not_ready`.
|
||||
- `backends.total` counts **live compiled pool members including Docker**.
|
||||
`configured_static` counts saved static members. `up`, `down`, `checking`,
|
||||
`draining`, `disabled`, `unknown`, `pools_ready` and `active_exchanges`
|
||||
are independently calculated; `traffic_bytes_per_second` sums moving
|
||||
backend rates and **does not** represent all public HTTP traffic.
|
||||
- `traffic.requests_total`, `bytes_in_total`, `bytes_out_total` and `bytes_total`
|
||||
are cumulative process counters; `megabytes_total` uses decimal MB (10⁶ B).
|
||||
`requests_per_second`, `errors_per_second`, `bytes_in_per_second`,
|
||||
`bytes_out_per_second` and `bytes_per_second` are **rolling poll interval
|
||||
rates** computed on the server from a shared bounded sample (minimum 1 s,
|
||||
maximum 30 s between usable samples). An initial poll, restart, counter reset
|
||||
or gap longer than 30 s yields `null` until a second valid poll. Very rapid
|
||||
simultaneous polls reuse the latest completed interval. These are not
|
||||
guaranteed exact one-second rolling averages; poll every **2–5 seconds**.
|
||||
`requests_per_second_average` is a separate **uptime average**.
|
||||
- `traffic.error_percent` is lifetime errors divided by completed requests;
|
||||
`cache.hit_percent` is lifetime HOT/COLD hit ratio from cache metrics.
|
||||
Zero-denominator percentages are `null` unless a cache ratio has a defined
|
||||
default. The `traffic.network_rx_bytes_per_second` and
|
||||
`network_tx_bytes_per_second` fields are **host** interface rates, not
|
||||
RustProxy-exclusive transfer; backend rate is separate.
|
||||
- `system.cpu_percent`, `process_cpu_percent`, `memory_percent`, RAM and RSS
|
||||
reflect the last OS sample (`system.sampled_at_ms`). Unsupported values can
|
||||
be `null`. `web_server.requests_total` adds observed Web Server responses,
|
||||
while `streams.active_sessions` adds observed Layer-4 sessions.
|
||||
|
||||
The JSON is organized for simple chart consumption:
|
||||
|
||||
- `summary` contains the small, calculated metrics object described above.
|
||||
- `vhosts` includes `total`, `enabled`, `disabled`, backend readiness and an array of per-Vhost counters.
|
||||
- `requests` includes process-lifetime totals, active exchanges, errors, status
|
||||
classes, byte counters, latency, active connections and H1/H2/H3/WebSockets.
|
||||
- `system` includes sampled host/process CPU, memory, swap, process I/O/FDs, network interfaces and throughput.
|
||||
- `backends`, `web_server`, `streams`, `docker`, `cache`, `traffic`, `transform`,
|
||||
`logging` and `capacity` contain their corresponding operational summaries.
|
||||
- `prometheus.types` and `prometheus.samples` include **every numeric sample**
|
||||
exported by the existing Prometheus text renderer, with label pairs as JSON
|
||||
objects. Histogram buckets/counts/sums are included. The normal Prometheus
|
||||
collector switches still control this detailed section.
|
||||
|
||||
Example field access:
|
||||
|
||||
```js
|
||||
const snapshot = await (await fetch('/api/metrics/json')).json();
|
||||
const vhostsEnabled = snapshot.vhosts.enabled;
|
||||
const requestTotal = snapshot.requests.total;
|
||||
const cpuPercent = snapshot.system.cpu_percent; // can be null before sampling
|
||||
const samples = snapshot.prometheus.samples.rust_proxy_vhost_requests_total ?? [];
|
||||
// samples[0] -> { labels: { vhost: 'site1' }, value: 123 }
|
||||
```
|
||||
|
||||
`collected_at_ms` is the JSON snapshot time; `system.sampled_at_ms` is the
|
||||
last OS collector sample time (the OS collector runs in the background).
|
||||
Raw counters represent cumulative totals, **not instantaneous RPS**. Use the
|
||||
server-computed interval rates from `summary` or calculate
|
||||
`(new_total - old_total) / elapsed_seconds` from raw counters in the client;
|
||||
reset the baseline after counter decreases, process restart or config reset.
|
||||
Absent/unsupported OS values are `null`; non-finite Prometheus values are also
|
||||
represented as `null`. Traffic breakdowns are approximate and can lose samples
|
||||
under load. The JSON excludes raw request paths, client IP addresses and raw
|
||||
User-Agent values, matching the bounded-label privacy model of Prometheus.
|
||||
|
||||
## Metric privacy and limits
|
||||
|
||||
Prometheus series use bounded configured labels; arbitrary request URLs, raw client IPs, credentials, raw User-Agents and query strings are intentionally not exposed as unbounded labels. Dashboard traffic top lists can still contain sensitive operational metadata, so keep the panel authenticated.
|
||||
|
||||
+2
-2
@@ -14,7 +14,7 @@ Practical guides for **RustProxy 0.34.2**. This index and the listed pages are a
|
||||
- [Vhosts and backends](VHOSTS.md) — domains, listener bindings, balancing, health and redirects.
|
||||
- [Custom locations](CUSTOM_LOCATIONS.md) — path routing, rewrites, local responses and error fallbacks.
|
||||
- [Access and authentication](ACCESS.md) — ACL, country/DDNS, Basic Auth, Tinyauth and rate limits.
|
||||
- [Static Web Server](WEB_SERVER.md) — document roots, downloads, rules and file delivery.
|
||||
- [Static Web Server](WEB_SERVER.md) — document roots, downloads, rules, built-in error pages and file delivery.
|
||||
- [PHP-FPM](PHP_FPM.md) — PHP service profiles, security and application examples.
|
||||
- [Cache](CACHE.md) — HOT/COLD storage, privacy, TTL and invalidation.
|
||||
- [Response delivery](RESPONSE_DELIVERY.md) — compression, static transformations and response headers.
|
||||
@@ -27,7 +27,7 @@ Practical guides for **RustProxy 0.34.2**. This index and the listed pages are a
|
||||
- [Docker discovery](DOCKER_DISCOVERY.md) — agent installation, networking and generated Vhosts.
|
||||
- [Other integrations](INTEGRATIONS.md) — Tinyauth, NPM migration, OPNsense and monitoring tools.
|
||||
- [Dashboard](DASHBOARD.md) — metrics panels, presets and configuration history.
|
||||
- [Monitoring](MONITORING.md) — Prometheus, traffic, backend and cache observations.
|
||||
- [Monitoring](MONITORING.md) — Prometheus, full JSON and compact `summary` API, traffic, backend and cache observations.
|
||||
- [Logs](LOGS.md) — live logs, stored logs, error logs and searches.
|
||||
- [Backups and recovery](BACKUP.md) — encrypted backups, restore and Secret Store.
|
||||
- [Migration](MIGRATION.md) — managed upgrades and Nginx Proxy Manager import.
|
||||
|
||||
+3
-1
@@ -44,7 +44,9 @@ An optional bounded Apache-style `.htaccess` compatibility layer supports a **su
|
||||
|
||||
A Web Service may enable PHP via a shared PHP-FPM profile or its own configuration. PHP is executed by the FPM service, not RustProxy, and must not be exposed as a raw Internet port. Use dedicated pools for different applications. See [PHP-FPM](PHP_FPM.md).
|
||||
|
||||
Missing static files return normal **HTTP 404 Not Found**, unreadable/blocked paths **403 Forbidden**, unsupported static methods **405 Method Not Allowed** (with `Allow: GET, HEAD`), and internal failures **500 Internal Server Error**. Generated response bodies contain only the standard status, not a `RustProxy: Web Server ...` diagnostic. `HEAD` errors have no response body. Internal server errors can be diagnosed through service logs; generated responses are not cacheable by default.
|
||||
Missing static files return **HTTP 404 Not Found**, unreadable/blocked paths **403 Forbidden**, unsupported static methods **405 Method Not Allowed** (with `Allow: GET, HEAD`), and internal failures **500 Internal Server Error**. The built-in Web Server now uses the existing **application-style HTML error pages** for statuses with a bundled template (including 400, 403, 404, 500 and PHP-FPM gateway errors). Other generated error statuses, such as 405, use the shared styled HTML fallback. Neither internal filesystem paths nor `RustProxy: Web Server ...` diagnostics are included in the public body. Details for 5xx filesystem failures remain in server logs.
|
||||
|
||||
These generated HTML responses retain the actual HTTP status, `Content-Type: text/html; charset=utf-8`, `X-Content-Type-Options: nosniff` and `Cache-Control: no-store`; `HEAD` preserves the matching `Content-Length` but sends no body. Explicit application/origin responses are still passed through without forced replacement, subject to the Vhost error interception options below.
|
||||
|
||||
Vhosts can intercept selected application error bodies in **Pages** and return a configured HTML error page while preserving the status. Internal location `error_fallback` is different: it routes the error to a named internal handler. Error-page replacements are marked uncacheable. Origin-supplied and explicitly configured custom error bodies are preserved unless interception is enabled.
|
||||
|
||||
|
||||
Reference in new issue
Block a user