Ship logs

The agent follows each configured log file the way tail -f does: it remembers its position, picks up new lines as they are written, and survives log rotation. Each record is posted to the project log stream with a source label and severity level.

How log shipping works

• One follower runs per configured file, so a slow file never blocks another.
• When a file shrinks or is replaced during rotation, the agent flushes anything pending and starts reading the new file from the beginning.
• Failed deliveries retry three times with backoff before the record is dropped.
• Empty lines are skipped.

Add log sources

List each file under logs: in /etc/errorgap-agent.yml, then restart the agent.

logs:
  - path: /var/www/html/wordpress/web/app/debug.log
    source: wordpress
    level: info
    start_at: end
    multiline:
      start_pattern: '^\\[[0-9]{2}-[A-Za-z]{3}-[0-9]{4} '
  - path: /var/log/nginx/error.log
    source: nginx
    level: error
    start_at: end

• path — the file to follow. A missing file is not an error; the agent waits for it to appear.
• source — the label shown in the logs view. Defaults to the file name.
• level — the severity applied to records from this file. Defaults to info.
• start_at — end ships only new lines from startup onward; use the beginning of the file to backfill existing content once.

Set a top-level environment: value (for example production orstaging) to tag every shipped record with the environment it came from. The logs view can then filter records per environment. When unset, the agent falls back to metrics.environment.

Group multiline records

Stack traces and pretty-printed output span many lines. Without grouping, each line arrives as its own record and the trace becomes unreadable. Set a start_pattern regex that matches the first line of each record — typically the leading timestamp — and the agent buffers continuation lines into a single entry.

multiline:
  start_pattern: '^\\[[0-9]{2}-[A-Za-z]{3}-[0-9]{4} '

A buffered record is sent when the next record starts, or after flush_after_msof quiet so the final record in a burst is not held indefinitely.

Tune polling and flushing

Two top-level settings control latency:

• poll_interval_ms — how often the agent checks each file for new content. Default 1000, minimum 100.
• flush_after_ms — how long a multiline buffer can sit idle before it is sent. Default 750.

The defaults suit most servers. Lower them when sub-second delivery matters more than the small extra IO.

View shipped logs

Shipped records appear in the project logs view alongside logs sent by SDKs. The project overview shows the latest lines, and the full view offers three modes:

• Live stream — a real-time tail for watching activity as it happens.
• List view — pages of recent history for reviewing a time window.
• Aggregate view — groups duplicate lines after stripping leading timestamps, useful for spotting noisy repeats.

Every mode supports free-text search over messages plus level, source, environment, and time-range filters.

Troubleshooting

• No records arriving — check journalctl -u errorgap-agent for delivery warnings, and confirm the endpoint, project slug, and API key.
• Nothing ships from an existing file — with start_at: end only lines written after startup are shipped. Append a test line to confirm.
• Stack traces arrive line by line — the start_pattern does not match the first line of each record. Test the regex against real log lines.
• Permission errors — the agent user must be able to read the log files. Add it to the group that owns them, such as adm on Debian-based systems.