148 lines
7.5 KiB
Markdown
148 lines
7.5 KiB
Markdown
# Dedicated Prometheus endpoint
|
|
|
|
RustProxy exposes Prometheus text exposition 0.0.4 on a dedicated read-only
|
|
listener. It is independent from administrator browser sessions and does not
|
|
export request paths, query strings, cookies, credentials, backend URLs or ACME
|
|
account secrets.
|
|
|
|
## Configuration
|
|
|
|
```json
|
|
{
|
|
"prometheus": {
|
|
"enabled": false,
|
|
"listen": "127.0.0.1:9191",
|
|
"path": "/metrics",
|
|
"allowed_cidrs": ["127.0.0.0/8", "::1/128"],
|
|
"bearer_token_env": null,
|
|
"allow_trusted_network_without_token": false,
|
|
"include_system": true,
|
|
"include_vhosts": true,
|
|
"include_backends": true,
|
|
"include_docker_vhosts": true,
|
|
"include_cache_domains": true,
|
|
"include_streams": true,
|
|
"include_logging": true
|
|
}
|
|
}
|
|
```
|
|
|
|
The listener is plain HTTP. Keep it on loopback, a private monitoring network or
|
|
behind a protected tunnel. `allowed_cidrs` is always evaluated against the actual
|
|
transport peer (`PeerAddr`); `Forwarded` and `X-Forwarded-For` never grant metrics
|
|
access.
|
|
|
|
### Bearer token
|
|
|
|
Set `bearer_token_env` to an environment-variable name such as
|
|
`RUST_PROXY_METRICS_TOKEN`. RustProxy stores only the variable name. The value must
|
|
contain 32..4096 printable non-whitespace ASCII characters and must be present at
|
|
startup.
|
|
|
|
### Trusted network without a token
|
|
|
|
`allow_trusted_network_without_token=true` explicitly allows a peer already matched
|
|
by `allowed_cidrs` to scrape without a bearer token. This can be used for a private
|
|
Prometheus VLAN. An explicit IPv4/IPv6 `/0` is rejected in this mode. Keep the CIDR
|
|
list narrow; enabling this option is an authentication decision, not a forwarded-IP
|
|
feature.
|
|
|
|
A non-loopback exporter requires either a bearer-token variable or this explicit
|
|
trusted-network bypass. Changing enabled/listen/token-variable requires restart;
|
|
path, CIDRs, collector switches and the trusted-network bypass apply live.
|
|
|
|
Only `GET` on the exact configured path without a query string is accepted. A
|
|
wrong path is `404`, wrong method `405`, disallowed peer `403`, invalid/missing
|
|
required bearer `401`, and exporter concurrency exhaustion `429`.
|
|
|
|
## Coverage audit in 0.19.1
|
|
|
|
The exporter represents all scalar fields currently sampled by `diagnostics::View` when available. The per-interface `network_interfaces` list added in 0.18.6 is intentionally dashboard-only so kernel-created interface names cannot create an uncontrolled Prometheus label set. RustProxy also exports the bounded operational data already available from traffic metrics, cache, vhosts, backend pools, streams, logging, GeoIP and ACME renewal observations.
|
|
|
|
| Area | Exported diagnostics |
|
|
|---|---|
|
|
| Global traffic | requests/completions/active/rejects/errors, status classes, request/response bytes, exchange lifetime, accepted/active/rejected connections |
|
|
| Protocols | HTTP/1.1, HTTP/2 and HTTP/3 requests, H2/H3 connections/rejects, TLS connections/handshake failures, WebSocket tunnels/bytes/errors/lifetime, compression counters |
|
|
| Admin | request/status counters and time to control-plane response headers |
|
|
| Process/host | diagnostic source, runtime platform info, sampled timestamp, system/process CPU, logical CPUs, RAM total/used, system swap total/used, system uptime, RSS total/anon/file/shmem, virtual memory/limit, VmData, process swap, FDs/limit, threads, process start time, load 1/5/15, network totals/rates, process disk I/O, cgroup memory current/max |
|
|
| GeoIP | loaded state plus IPv4/IPv6 range counts |
|
|
| Cache | hot entries/bytes, global hit ratio and counters, cold entries/bytes and movement/error counters, fill bytes, cold queue bytes/items, active cold read/write bytes, combined transient bytes, configured-domain hot/cold occupancy, hit ratio and decision data |
|
|
| Vhosts | desired enable/domain/path/cache settings, per-vhost traffic/status/error/byte counters and cumulative exchange-duration histogram |
|
|
| Redirect/404 hosts | desired enable state, domain/rule counts and local-response status |
|
|
| Backends | pool readiness/policy info, bounded backend status, health/drain/backup, active work and configured request-concurrency/queue limits, requests/errors/bytes, weight, separate active/passive failure state, active/passive successes and health-failure totals, unconditional HTTP-5xx/timeout/connect/I/O/slow-response observation counters, DNS/TLS/header-timeout/read-timeout/send-timeout diagnostics, capacity rejection/queue-timeout counters, plus `passive_http_5xx_total`, `passive_timeouts_total`, `passive_connect_errors_total`, `passive_io_errors_total` and `passive_slow_total` aliases, health transitions, last status, current/EWMA latency, last-probe/failure/ejection/recovery timestamps, traffic rate, and retry attempt/success totals for ordinary vhosts |
|
|
| Docker vhosts | separate `rust_proxy_docker_vhost_*` and `rust_proxy_docker_backend_*` families: configured agents/assignments/domains, vhost traffic/status/duration plus backend readiness, health, requests/errors/bytes, latency/EWMA, separate active/passive failure state, unconditional observation counters and matching passive-health aliases, transitions and probe results |
|
|
| Streams | desired enable state, active/session/reject/error counters, bytes/packets and max connections |
|
|
| Logging | structured sink queue capacity, sent/error/drop counters plus the global live-log contention drop counter |
|
|
| TLS/ACME | configured certificate count, auto-renew flag, bounded issuer metadata, latest ACME job state, renewal check/expiry timestamps, failure count and status |
|
|
| Inventory | listeners/protocol flags, vhost/redirect/404/stream/ACL counts, request capacity and available permits, config revision and restart-required state |
|
|
|
|
Values unavailable on the running OS are omitted rather than fabricated. Series
|
|
labels are bounded by configured IDs/domains, finite states and fixed protocol/status
|
|
families. Per-request URLs and arbitrary Host input are never labels.
|
|
|
|
This is complete for **currently implemented bounded diagnostic views**. It does
|
|
not intentionally expose secrets, raw configuration documents, access-log entries
|
|
or unbounded per-request values merely to make them visible to Prometheus.
|
|
|
|
## Prometheus examples
|
|
|
|
Loopback/private CIDR scrape without a token when the explicit trusted option is
|
|
used:
|
|
|
|
```yaml
|
|
scrape_configs:
|
|
- job_name: rustproxy
|
|
scrape_interval: 15s
|
|
metrics_path: /metrics
|
|
static_configs:
|
|
- targets: ['127.0.0.1:9191']
|
|
```
|
|
|
|
With bearer authentication:
|
|
|
|
```yaml
|
|
authorization:
|
|
type: Bearer
|
|
credentials_file: /etc/prometheus/secrets/rustproxy-token
|
|
```
|
|
|
|
Vhost rate:
|
|
|
|
```promql
|
|
sum by (vhost) (rate(rust_proxy_vhost_requests_total[5m]))
|
|
```
|
|
|
|
Vhost p95 exchange lifetime:
|
|
|
|
```promql
|
|
histogram_quantile(0.95,
|
|
sum by (vhost, le) (rate(rust_proxy_vhost_exchange_duration_seconds_bucket[5m])))
|
|
```
|
|
|
|
Docker-vhost request rate (kept separate from ordinary vhosts):
|
|
|
|
```promql
|
|
sum by (agent, vhost, service) (rate(rust_proxy_docker_vhost_requests_total[5m]))
|
|
```
|
|
|
|
Docker backend availability and latency:
|
|
|
|
```promql
|
|
rust_proxy_docker_backend_up
|
|
rust_proxy_docker_backend_ewma_latency_seconds
|
|
```
|
|
|
|
Certificate expiry window:
|
|
|
|
```promql
|
|
rust_proxy_certificate_renewal_not_after_timestamp_seconds - time()
|
|
```
|
|
|
|
The supplied dashboard is `grafana/rustproxy-overview.json`; Debian packages also
|
|
install it under `/usr/share/rustproxy/grafana/`. Its dedicated **Docker vhosts** row
|
|
uses only the separate Docker metric families and provides Docker-agent/service
|
|
filters so multi-agent installations can be inspected independently from ordinary
|
|
vhosts/backends.
|
|
|
|
Reference: https://prometheus.io/docs/instrumenting/exposition_formats/
|