44 lines
2.5 KiB
Markdown
44 lines
2.5 KiB
Markdown
# Optional error-file logging
|
|
|
|
RustProxy can write an additional local file containing only `ERROR` events. This is an optional sink layered on the existing tracing/logging pipeline; journald/systemd and other configured sinks remain independent.
|
|
|
|
## Configuration
|
|
|
|
The settings document contains:
|
|
|
|
```json
|
|
{
|
|
"error_log": {
|
|
"enabled": true,
|
|
"path": "/var/log/rustproxy/error.log",
|
|
"format": "JSON"
|
|
}
|
|
}
|
|
```
|
|
|
|
`format` is `JSON` or `RAW`. The feature is disabled by default. The administration Settings UI exposes the same enable/path/format controls and applies changes at runtime.
|
|
|
|
The sink accepts only `ERROR` events. JSON is one object per line; RAW is one human-readable line per event.
|
|
|
|
## Runtime behavior
|
|
|
|
Events are handed to a bounded queue and written by one asynchronous worker. The request path does not perform the file write. When the queue is full, new error-file events are dropped and counted instead of allowing unbounded memory growth.
|
|
|
|
Filesystem errors do not stop RustProxy. The worker reports failures through the existing logger, rate-limits repeated diagnostics and retries opening the file. Changing the path or disabling the sink closes the current file; a format change takes effect without an application restart.
|
|
|
|
Created log files use mode `0600` on POSIX. Symlink/non-regular targets are refused.
|
|
|
|
## Secret redaction
|
|
|
|
The common logging pipeline redacts sensitive keys and values before they reach the error-file sink. This includes authorization credentials, provider tokens/passwords, backup passwords, private-key PEM material and Secret Store/master-key related values. Structured secret fields are replaced with `[REDACTED]`.
|
|
|
|
Error messages from dependencies should still be treated as untrusted diagnostic input; do not deliberately embed secrets in error text.
|
|
|
|
## Rotation
|
|
|
|
RustProxy does not implement file rollover, retention or compression. Use the system `logrotate`. The Debian package configuration in `debian/rustproxy.logrotate` already covers `/var/log/rustproxy/*.log` and uses `copytruncate`, so the default error-log path is included without a RustProxy restart.
|
|
|
|
## Stored-log explorer
|
|
|
|
The authenticated `/logs` workspace can read the configured error file alongside structured access/protocol files. It remains independent from Live Logs and can inspect an existing error file even while `error_log.enabled` is false. The browser API does not accept arbitrary paths; it resolves only the configured error-log path and applies the same bounded, read-only regular-file/symlink protections documented in [FILE_LOGS](FILE_LOGS.md).
|