Commands
arc logs tail
Follows a log file in real time, similar to tail -F. On startup it seeks to the last 4 MB of the file to avoid re-processing the entire history, then emits new lines as they arrive.
On EOF it sleeps 200ms and reopens the file. This handles log rotation: Arc tracks the path, not the inode, so it automatically follows a new file created at the same path.
arc logs query
Reads the log file from the beginning (or from a time cutoff if --last is specified) and prints matching lines, then exits.
Arguments
Common arguments (both tail and query)
tail-only argument
query-only argument
Duration format
Examples:
5m, 1h, 30s, 200ms, 3600 (seconds).
Log file resolution
The CLI resolves the log file path in this order:- If
--fileis provided, use it directly. - Read the Arc config file (
--config, default/etc/arc/config.yaml). - Navigate to
logging.output.filein the config. - If not found, exit with a config error.
Filter logic
All filters are applied client-side. Each active filter must pass (logical AND). Lines that do not parse as valid JSON are silently skipped. Status matching handles two forms:- Exact:
502— parsed as an integer and compared directly. - Wildcard:
5xx,4xx— matches any status in the hundred-range (500–599, 400–499, etc.).
ts field is older than now - duration are skipped. Lines where the timestamp cannot be parsed are kept (fail-open).
Operational notes
Local only. The CLI reads files on the local node. It has no HTTP client and cannot query other nodes in a cluster. High throughput. Under high QPS, use--last to narrow the scan window. The tail command always starts from 4 MB before EOF regardless.
Log rotation. The tail command reopens the file path on EOF, following rotations automatically.
Non-JSON lines. Lines that do not parse as valid JSON (e.g. partial writes during rotation) are silently skipped.
Examples
Troubleshooting
No log file found
No log file found
Either
--file is not specified and the config file does not contain a logging.output.file path, or the config file path (--config) is wrong. Verify the path with --config /etc/arc/arc.json and ensure logging.output.file is set.arc logs tail shows no output
arc logs tail shows no output
The log file exists but no new lines are being written. Confirm Arc is running and receiving traffic. Also check that
observability.access_log.enabled: true and sample is not 0.0.Non-JSON lines are appearing
Non-JSON lines are appearing
Arc emits NDJSON. Non-JSON lines (e.g., startup messages before logging is initialized) are silently skipped by
arc logs. If you see them in the raw log file, they predate Arc’s structured logging initialization and can be ignored.--status 2xx filter returns no results
--status 2xx filter returns no results
Wildcard status matching requires the
xx suffix. Valid examples: 200, 2xx, 4xx, 5xx. Exact numeric codes and two-digit wildcards are both supported. Ensure there is traffic with matching status codes.Log rotation causes tail to miss lines
Log rotation causes tail to miss lines
arc logs tail handles rotation: when it reaches EOF, it sleeps 200ms and reopens the file. Lines written between the rename and reopen may be briefly missed. For high-throughput log analysis, use arc logs query with a time window instead.