RustProxy/docs/FILE_LOGS.md

Stored log explorer

RustProxy 0.26.0 adds an authenticated, read-only Logs workspace at /logs. It is a local file-backed explorer for RustProxy logging outputs and is intentionally separate from Live Logs.

Separation from Live Logs

Live Logs uses the bounded in-memory request history and Tokio broadcast channel. It remains available even when file logging is disabled and is optimized for current request activity.

The stored-log explorer does not read that memory ring. It reads only files derived from the active RustProxy logging configuration:

• the combined structured access-log path, or JSONL files directly inside the configured per-vhost directory;
• the configured optional error-log file.

Existing files remain browsable after their writer is disabled. Disabling file logging therefore stops new persistent access/protocol records but does not remove old files.

Protocol and malformed-traffic records

Ordinary completed requests use event: "request". RustProxy can also persist low-level records that fail before a normal routed HTTP exchange exists. Those records use:

{
  "event": "protocol_error",
  "protocol_error": "tls_handshake_error",
  "error_detail": "...",
  "client_ip": "192.0.2.10",
  "local_addr": "192.0.2.20:443",
  "tls_sni": "app.example",
  "transport": "tls",
  "http_version": "",
  "status": 0,
  "outcome": "protocol_error"
}

Covered classes include connection-limit rejection, malformed/incomplete HTTP/1 connections, invalid/disabled h2c upgrades, HTTP/2 protocol termination, TLS ClientHello and handshake errors/timeouts, and HTTP/3/QUIC handshake, header, protocol and stream-limit failures.

These low-level records are sent only through the configured persistent structured-log sinks (file, Logstash and/or Loki). They are deliberately not inserted into Live Logs, so scanner noise cannot displace the ordinary bounded live request history. For protocol_error events, the diagnostic envelope fields shown above are always emitted even when a custom JSON field mapping is active; custom/static fields are retained, but they cannot hide or overwrite the required protocol-diagnostic fields.

Dependency error text is secret-redacted and capped before it enters the persistent record. Raw packets, request bodies and raw malformed request bytes are not captured.

Browser security model

The browser never supplies a filesystem path. /api/file-logs returns opaque source IDs derived from the current configuration, and /api/file-logs/query accepts only those IDs or all.

The reader is bounded:

• up to 2 MiB scanned from the tail of one source;
• up to 8 MiB across one query;
• up to 20,000 lines across the complete query, shared fairly across selected sources;
• at most 32 sources in an all query;
• page size at most 500 and offset at most 10,000.

File reads run in a blocking worker rather than the async proxy runtime. Only regular files are accepted. On Unix the reader opens with O_NOFOLLOW; a symlink is not followed. Per-vhost enumeration also rejects a configured directory that is itself a symlink and only lists direct regular .jsonl children.

The endpoints are private administration routes and inherit the existing panel session/Host/Origin access controls. There is no public-proxy route to the file reader.

Filters

The workspace supports source, case-insensitive text, event class, HTTP status class, client IP and vhost filters. Results are paged from the bounded scanned tail. Selecting a row shows the complete parsed JSON object. RAW error-log lines are wrapped as a record with event: "error" and a raw field.

The explorer is diagnostic rather than a retention system. RustProxy does not add rollover, indexing or compression; use the existing operating-system log rotation policy for retention.