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.
• Package repository — on Ubuntu, Debian, Fedora, or RHEL, add the signed Errorgap repository and install with apt or dnf, so upgrades arrive through the system package manager.
• 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.

Install from a package repository

The repositories carry every released version of the agent. Packages are built for x86-64 and arm64 and are statically linked, so they do not depend on the distribution's libc. Both repositories are signed with the Errorgap package signing key, fingerprint 325C D6A8 06E1 D195 BEE2 289F 2119 D95F 1186 EF49.

On Ubuntu or Debian:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://apt.errorgap.com/errorgap.asc -o /etc/apt/keyrings/errorgap.asc
echo "deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/errorgap.asc] https://apt.errorgap.com stable main" | sudo tee /etc/apt/sources.list.d/errorgap.list
sudo apt update && sudo apt install errorgap-agent

On Fedora or the RHEL family. The repository metadata is signed and individual packages are not, so the repo file sets repo_gpgcheck=1 and gpgcheck=0:

sudo tee /etc/yum.repos.d/errorgap.repo <<'EOF'
[errorgap]
name=Errorgap
baseurl=https://rpm.errorgap.com
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://rpm.errorgap.com/RPM-GPG-KEY-errorgap
EOF
sudo dnf install errorgap-agent

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.