logs
Show a unified view of application events and proxy engine logs.
xrat logs [flags]
xrat logs merges two sources:
- App events — structured rows recorded in the database (
eventstable): daemon start/stop, runtime connect/disconnect, proxy rotation, health failover, and test runs. - Engine logs — the stdout/stderr of the
xray-core/sing-boxprocess for the active or most recent runtime session, plus the daemon’s owndaemon.logfile.
By default it prints the last N entries and exits. Use --follow to stream new
entries live (press Ctrl-C to stop).
Flags
| Flag | Description |
|---|---|
-f, --follow | Stream new entries as they arrive instead of exiting |
-n, --lines | Number of recent entries to show before following (default: 200) |
--source | Which feeds to include: all, app, daemon, xray, singbox (default: all) |
--level | Minimum event level: info, warn, or error (applies to app events) |
--format | Event stream format: table, tsv, or json (default: table) |
Notes:
--format json/--format tsvemit the structured app events only; engine/daemon text logs are unstructured and are shown only in the defaulttableview or while following.--source xray/--source singboxtail the engine log files for the active or last session;--source daemontailsdaemon.log;--source appshows only structured events.- Engine logs are parsed into TIME / LEVEL / SOURCE / MESSAGE columns (xray and
sing-box), matching the TUI engine tab. Access logs from xrat’s own stats
polling of the
apiinbound ([api -> api]) are filtered out as instrumentation noise.
Examples
# Last 200 events plus engine log tails
xrat logs
# Live stream everything
xrat logs -f
# Only the last 50 lines of xray-core output
xrat logs --source xray -n 50
# Only error-level app events, as JSON
xrat logs --source app --level error --format json
Clearing persisted events
xrat logs clear [--yes]
xrat logs clear permanently deletes every row from the events table. It
prompts for confirmation first; pass --yes to skip the prompt (useful in
scripts). This only clears the structured app events in the database —
engine and daemon log files are left untouched by this command.
XRAT automatically removes managed stdout/stderr logs for completed sessions older than the 10 newest completed sessions. Cleanup runs at application startup and before connections and runtime replacements. It covers both Xray/V2Ray and sing-box session logs in the runtime directory, including files accumulated before upgrading. Starting, running, and stopping sessions are protected. Cleanup failures produce warnings without blocking normal operations.
This retention policy does not cap the size of an active log, rotate daemon.log,
or remove generated JSON configs, custom engine logs, or files whose sessions
are absent from the database.
The TUI exposes the same database clear from the logs card via the C p clear
chord, kept distinct from any view-only buffer clears.
# Wipe all recorded app events without a prompt
xrat logs clear --yes
Where logs live
| Source | Location |
|---|---|
| App events | events table in the database |
| Daemon | <runtime-dir>/daemon.log |
| xray-core | <runtime-dir>/session-<id>.out.log / .err.log |
| sing-box | <runtime-dir>/session-<id>.singbox.out.log / .err.log |
The daemon emits its own process output to daemon.log (errors and panics);
normal operational events are captured as structured rows instead.