RustProxy/docs/MONITORING.md

Monitoring, metrics and health

RustProxy has operational views in the authenticated panel and an optional standalone Prometheus exporter. They measure different things: dashboard sampling, process-lifetime counters and stored logs are not interchangeable.

What to watch

View	Main information	Interpretation
Overview	Active connections, request rate, errors, process CPU/RAM, protocols, backend state, optional charts	Dashboard samples are not long-term billing data.
Vhosts → Backends	Member health, weights, H1/H2 modes, current work, last observed upstream response	A last_status from normal proxy traffic is not an active health probe result.
Web Server	Requests/status classes, static/PHP traffic, response-header time, response bytes, PHP concurrency permits	Response header duration excludes streamed body transfer. PHP permits are not FPM child processes.
Traffic	Per-Vhost totals and top countries/IPs/paths/methods/agents/cache results	Bounded in-memory analytics, approximate top lists and possible sample loss under heavy load.
Cache	HOT/COLD occupancy, hit/miss/bypass, object metadata, selected invalidation	HTTP Age differs from cache residence age.
Docker / Streams	Agent status, dynamic Vhost health, TCP/UDP sessions and traffic	An agent can be waiting for first observation; Streams are non-HTTP.
Logs	Live requests, stored JSONL/error/protocol records	A log sink can be disabled while live memory view remains available.

Overview allows account-specific card layout and history controls; see Dashboard. GeoIP/country analytics depend on the installed/update database and whether country capture is enabled.

Prometheus exporter

The exporter is disabled by default and uses a separate HTTP listener, normally 127.0.0.1:9191, at /metrics. It is not protected by the admin browser cookie; it has its own client-network and bearer-token policy. In Settings → Prometheus enable the endpoint and configure:

• listen, path, allowed_cidrs and an optional environment-variable name bearer_token_env (the secret value is supplied separately to the service).
• allow_trusted_network_without_token only for a deliberately restricted monitoring subnet. /0 CIDRs are not accepted in this mode.
• Collector switches for process/system, Vhosts, traffic, backends, Docker, cache domains, Streams and logging.

A non-loopback exporter must have an actual token or an explicit token-free trusted-network exception. The exporter uses plain HTTP; keep it on loopback, trusted network or a protected TLS tunnel. Forwarded/X-Forwarded-For headers cannot grant exporter access because network restrictions apply to the transport peer.

For bearer authentication, provide a 32–4096-character printable non-whitespace ASCII token in a service environment variable and set bearer_token_env to its name, e.g. RUST_PROXY_METRICS_TOKEN. Changing exporter activation/bind/token-variable usually needs restart; some collector/CIDR settings apply live. The exact allowed GET path must not have a query string.

Example scrape configuration, after choosing the correct private target:

scrape_configs:
  - job_name: rustproxy
    static_configs:
      - targets: ['127.0.0.1:9191']

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.

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.

Metrics reset on process replacement, and some per-Vhost/backend records can reset when identity or config changes. Distinguish counters, rates and gauges; watch for traffic sampling gaps rather than interpreting every missing point as zero. Before deployment, verify collector reachability, firewall rules, CPU/RAM overhead and alert thresholds against real traffic.