RustProxy/docs/LOGS.md

Live logs, stored logs and error logging

RustProxy has several independent logging paths. Choose the one matching the question; enabling stored file logging is not required to view recent in-memory requests.

Live Logs

Use Logs → Live Logs in the authenticated panel, or locally:

rust-proxy --data-dir /var/lib/rustproxy --livelogs

The CLI connects to the local administration listener and follows structured request events. It can filter by host, Vhost, backend, route, method, client, protocol, status, cache state and latency; use filters, pause, resume, detail on and quit in the interactive view. It adapts to a loopback administration HTTPS listener where configured.

For a published Docker application, Docker vhosts → Live logs (beside Open app) opens this same dialog filtered to the generated Vhost. It includes HTTP traffic for that publication and its aliases. It does not display Docker container stdout/stderr; the Docker agent remains inventory-only.

Live viewing is bounded in memory. Slow consumers may receive a gap/loss indication and are not allowed to block proxy traffic. Low-level malformed HTTP/TLS/H2/H3 protocol errors can be sent only to persistent sinks rather than appearing in the ordinary live request list. A request ID (X-Request-ID) helps correlate an application response with proxy records.

Stored Logs

The authenticated Logs → Stored logs page reads the configured structured JSON/JSONL access logs, optional per-Vhost files and optional error log. These files can remain readable even when their current writer is disabled. The explorer supports paging, dynamic columns, sorting, record expansion/Raw JSON and repeated-value analysis.

Search uses a restricted case-insensitive query syntax, for example:

status:>=500 AND path:/api/*
client_ip:192.0.2.* AND status:5xx
method:POST AND !country:Poland
error:"connection reset"

Plain words search stored values; quotes allow spaces, ! negates a clause, * matches wildcards and numeric operators work on supported fields. OR is not supported. Searches and repeated-value statistics are bounded by server scan limits; do not interpret a truncated result as the entire historical archive.

Error and protocol logs

RustProxy can persist warnings/errors and selected protocol failures separately from access traffic. Set output level, sink and optional retention/rotation under Settings → Logging and related error-log controls. Access logs may use the global structured file or per-Vhost locations. Log paths must be writable by the service identity, including when running inside a container/systemd sandbox.

The installed Linux deployment may configure logrotate for durable logs; check the installed policy rather than assuming all platforms rotate automatically. Logging is bounded/asynchronous where practical, and some records can be dropped under saturation; inspect sink drop/error counters in monitoring.

Privacy and investigation

Logs can contain client IPs, URLs, application hostnames and timing metadata. Limit access and retention. RustProxy masks selected known credential fields, but avoid deliberately logging secrets or personal data in query parameters and custom headers. The administration API and stored-log search remain behind authentication.

For common symptoms:

• 502/503/504: correlate request ID, Vhost and backend health with upstream timeout/connect/TLS errors.
• 403/405/429: inspect ACL, method rule, country or rate limiting.
• Unexpected cache result: inspect optional X-Cache diagnostics and Cache dashboard alongside request logs.
• Files empty: enable the correct sink and check permissions, path and rotation state.
• Protocol failures missing from Live Logs: inspect configured persistent error/protocol logs instead.

Also see Monitoring and Troubleshooting.