Log collection

Pull-based, on demand

Log collection is command-driven: the agent does not continuously tail files. It receives READ_LOG commands from the backend on its heartbeat and executes them on demand, so a host is touched only when the platform asks. During registration the agent advertises the log_reader capability, which tells the backend it can handle these commands.

Logs appear on request, not in a stream: A line shows up in VerOps only after a READ_LOG command runs for its file. There is no continuous ingestion of every line the host writes.

The READ_LOG command

Parameter	Required	Description
filePath	Yes	Absolute path to the log file (e.g. /var/log/syslog).
patterns	No	Regular expressions; a line is kept if it matches any. Omit to return all lines up to the read limit.
expectedContent	No	A string the file should contain; the result reports whether it was found (a validation check).

On completion the agent posts back matching_lines, match_count, and validation_passed to /api/machine/agents/{id}/command-result.

Regex examples

Goal	Patterns
Error-level messages	["ERROR", "FATAL", "CRITICAL"]
A specific service	["\\[checkout-service\\]"]
A timestamp window	["^2026-05-11T1[0-5]"]
Stack traces	["Exception", "at\\s+[\\w.$]+\\("]

Limits and permissions

Reads are bounded by [log_collector]: max_file_size_mb (files above it are skipped) and max_lines_per_read (memory ceiling per read). The agent process needs read access to each file — grant the minimum, don't run as root:

# Let the verops user read /var/log via the adm group
sudo usermod -aG adm verops

# In Docker, mount log dirs read-only
docker run -v /var/log:/var/log:ro verops-machine-agent

Filter at the source: Combine patterns with a smaller max_lines_per_read on large or busy logs — it cuts both the data transferred and the memory the agent holds at once.