Install the agent

errorgap-agent is a small daemon that runs on each server you want to observe. It tails log files and collects host metrics, then ships both to your project over HTTPS using the project API key. Install it once per host; log shipping and metrics collection are enabled independently in its config file.

What the agent does

• Log shipping — follows one or more log files and forwards new records to the project log stream, including multiline stack traces grouped into single entries.
• Infrastructure metrics — reports CPU, memory, load, disk, volume, and per-process metrics that power the project Infrastructure page.

The agent does not capture application errors or performance transactions. Those come from an SDK installed in your application.

Choose an install method

• Binary archive — download the Linux build, extract the errorgap-agent binary, and copy it to /usr/local/bin.
• Debian package — on Ubuntu or Debian, install with sudo apt install ./errorgap-agent_*.deb.
• RPM package — on RHEL, CentOS, Amazon Linux, or Fedora, install with sudo dnf install ./errorgap-agent-*.rpm.
• Container image — run the published image with the config file mounted read-only.

The Debian and RPM packages install a systemd unit and create the config file for you. With the binary archive or container image, create the config file yourself as shown below.

Configure the agent

The agent reads /etc/errorgap-agent.yml at startup. Every config needs the endpoint of your Errorgap deployment, the project slug, and the project API key. Find the slug and API key in the project settings.

endpoint: https://errorgap.example.com
project_slug: your-project-slug
api_key: your-project-api-key

logs:
  - path: /var/log/app/production.log
    source: app

metrics:
  enabled: true

The logs and metrics sections are each optional, but configure at least one — see Ship logs and Infrastructure metrics for the full options.

Run as a service

Run the agent under systemd so it starts at boot and restarts on failure. The Debian and RPM packages install this unit automatically; with the binary install, create it yourself.

[Unit]
Description=Errorgap Agent
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/errorgap-agent --config /etc/errorgap-agent.yml
Restart=always
RestartSec=5
User=errorgap
Group=errorgap

[Install]
WantedBy=multi-user.target

Then enable and start it:

sudo systemctl enable --now errorgap-agent

Run in Docker

Mount the config file read-only and pass it with --config. To ship logs from the host, also mount the log directories you reference in the config.

docker run --rm \
  --name errorgap-agent \
  -v /etc/errorgap-agent.yml:/etc/errorgap-agent.yml:ro \
  ghcr.io/jgrubbs/errorgap-agent:latest \
  --config /etc/errorgap-agent.yml

Verify the agent

1. Check the service is running: systemctl status errorgap-agent.
2. Review startup output with journalctl -u errorgap-agent — the agent logs how many log sources it follows and whether metrics are enabled.
3. If logs are configured, append a line to a watched file and confirm it appears in the project logs view.
4. If metrics are enabled, open the project Infrastructure page and confirm the host appears within a minute.