# errorgap-agent — AI installation guide

Use this guide when an Errorgap setup prompt asks you to install `errorgap-agent` for log shipping, infrastructure metrics, or both.

## Safety requirements

- The prompt provides `ERRORGAP_ENDPOINT`, `ERRORGAP_PROJECT_SLUG`, and `ERRORGAP_API_KEY`.
- Treat the API key as a secret. Never commit it to source control, bake it into a container image, print it in logs, or include it in your final response.
- The agent currently reads its credentials from YAML. Use the deployment's existing secret mechanism to render or mount `/etc/errorgap-agent.yml` at runtime with permissions limited to the agent user. If the repository has no safe mechanism, give the user the exact manual secret step instead of committing the key.
- Inspect the deployment before choosing an install method. Prefer the repository's existing systemd, container, Kubernetes, configuration-management, or infrastructure-as-code conventions.

## Requirements

- Outbound HTTPS access to `ERRORGAP_ENDPOINT`.
- Read access to every configured log file.
- Linux `/proc` access for cross-process metrics. Hardened hosts and containers may restrict which processes are visible.
- An optional writable spool directory for offline buffering. When configured, its default cap is 50 MiB.

## Installation methods

Choose the method that matches the deployment:

- **Debian/Ubuntu:** install the release `.deb` with `sudo apt install ./errorgap-agent_*.deb`.
- **RHEL/CentOS/Amazon Linux/Fedora:** install the release `.rpm` with `sudo dnf install ./errorgap-agent-*.rpm`.
- **Binary archive:** extract the Linux release archive and place `errorgap-agent` at `/usr/local/bin/errorgap-agent`.
- **Container:** use `ghcr.io/jgrubbs/errorgap-agent:latest` and mount the config read-only. Mount any host log directories that the agent must tail.

Release packages and archives are published at <https://github.com/jGRUBBS/errorgap/releases>. Do not build from source for a normal installation.

## Configuration

The default configuration path is `/etc/errorgap-agent.yml`:

```yaml
endpoint: ERRORGAP_ENDPOINT
project_slug: ERRORGAP_PROJECT_SLUG
api_key: ERRORGAP_API_KEY
poll_interval_ms: 1000
flush_after_ms: 750
spool_dir: /var/lib/errorgap-agent/spool
max_spool_mb: 50
```

The config must include at least one `logs` entry or `metrics.enabled: true`.

### Log shipping

Derive paths and formats from the actual application and deployment configuration. Do not invent a path. The agent begins at the end of a file by default, so only newly appended lines ship after startup.

```yaml
logs:
  - path: /real/path/from/the/deployment.log
    source: service-name
    level: info
    start_at: end
    multiline:
      start_pattern: '^pattern-that-matches-the-first-line-of-a-record'
```

Omit `multiline` for one-record-per-line formats such as JSON Lines. For stack traces and pretty-printed records, set `start_pattern` to match the first line of each new record so continuation lines remain attached.

The agent user needs read access to each path. Grant the narrowest group or ACL access that works; do not run as root only to bypass an unexplained permission problem.

### Infrastructure metrics

```yaml
metrics:
  enabled: true
  interval_secs: 15
  role: web
  cluster: production
  environment: production
  region: us-east-1
  processes:
    enabled: true
    top_n: 40
  volumes:
    enabled: true
    exclude_mounts:
      - /dev
      - /sys
      - /proc
      - /run
      - /dev/shm
      - /dev/pts
```

Use labels found in the deployment configuration. Omit labels you cannot determine instead of guessing. In a container without suitable `/proc` access, set `processes.enabled: false`.

## Running the agent

Debian and RPM packages install a systemd unit. For a binary install, create an equivalent unit using:

```ini
[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 run `sudo systemctl enable --now errorgap-agent`. Use the deployment's normal rollout workflow for containerized environments rather than starting an unmanaged local container.

## Verification

1. Check service or container status and review startup output. It reports how many log sources it follows and whether metrics are enabled.
2. For logs, append a distinctive test line to a configured file and check the agent output for delivery errors, then ask the user to verify it on the project Logs page. The page is the definitive ingestion check.
3. For metrics, check the agent output for delivery errors, then ask the user to verify the host on the project Infrastructure page within one minute. The page is the definitive ingestion check.
4. If delivery fails, check the endpoint, slug, key, file permissions, outbound HTTPS, and `journalctl -u errorgap-agent` or container logs.
5. Report what changed and the verification outcome without repeating the API key.