Infrastructure metrics

With metrics enabled, the agent reads host telemetry at a configurable interval and posts a snapshot to the project. The Infrastructure page aggregates snapshots across the fleet into host, volume, and process views with time-series charts.

What gets collected

• Host — CPU percentage across all cores, memory usage, load averages (1/5/15 minutes), and uptime.
• Volumes — capacity and usage per mount, plus IO utilization and read/write throughput on Linux.
• Processes — the top N processes by CPU with memory, thread count, open files, and uptime.
• Largest directories — an optional periodic scan of each volume that shows where disk space is going.
• Docker containers — optional per-container state, CPU, memory, restarts, uptime, and network / block-IO rates read from the Docker socket.
• Network interfaces — per-NIC rx/tx byte and packet rates plus lifetime error and drop counters, shown in the host detail’s Network tab. Enabled by default; disable with metrics.net.enabled: false.

IO utilization, throughput, thread counts, open files, and directory scans rely on Linux interfaces and are reported as empty on other platforms.

Enable metrics

Add a metrics: block to /etc/errorgap-agent.yml and restart the agent. A config with only metrics: and no logs: is valid.

metrics:
  enabled: true
  interval_secs: 15          # collection frequency (minimum 5)
  role: "web · puma"         # optional host role label
  cluster: prod-us-east-1    # optional cluster tag
  environment: production    # defaults to "production"
  region: us-east-1b         # optional region tag

  processes:
    enabled: true
    top_n: 40                # report the top N processes by CPU

  volumes:
    enabled: true
    exclude_mounts:          # pseudo-filesystems to skip
      - /dev
      - /sys
      - /proc
      - /run
      - /dev/shm
      - /dev/pts
    dirs:                    # optional largest-directory scan
      enabled: true
      scan_interval_secs: 300
      max_entries: 10

sudo systemctl restart errorgap-agent

Label your hosts

Tags make the fleet readable once more than a few hosts report. All four are optional but worth setting from the start.

• role — what the host does, shown in the hosts table, such as “web · puma” or “worker · sidekiq”.
• cluster — groups hosts for filtering, such as a deployment or fleet name.
• environment — separates production from staging in dashboard filters.
• region — records where the host runs.

Processes and volumes

Process reporting captures the top top_n processes by CPU each interval. Thread and open-file counts require permission to read each process’s /procentries; when the agent runs as a non-root user those fields are empty for other users’ processes.

Volume reporting covers every mounted filesystem except the configured exclude_mounts. The optional directory scan runs du against each volume on its own schedule and populates the largest-directories tab in the volume detail view — useful when a disk fills and you need to find what grew.

Docker containers

The container collector reads the Docker daemon’s unix socket directly — no docker CLI required — and reports each container’s state, CPU, memory (against its limit, or against host memory when unlimited), restart count, uptime, and combined network and block-IO rates. Containers appear in the Containers tab of the Infrastructure page.

metrics:
  containers:
    enabled: true
    socket_path: /var/run/docker.sock   # default
    max_containers: 50                  # default

The agent user needs access to the socket (typically the docker group). When the agent itself runs as a container, mount the socket read-only into its service:

services:
  errorgap-agent:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Network and block-IO rates are deltas between collection intervals, so the first sample after an agent restart reports them as empty. Container log tailing, mounts, environment, and labels belong to later metrics.containers.* collectors and show as “not yet collected” in the container detail view.

Read the dashboard

The Infrastructure page shows fleet averages with time-series charts for CPU, memory, disk used, and disk utilization, plus drill-downs per host, volume, and process. Each host gets a status based on its latest snapshot:

• crit — CPU at 90% or above, memory at 90% or above, or 1-minute load above 6.0.
• warn — CPU at 65% or above, memory at 75% or above, or 1-minute load above 2.0.
• ok — everything else.

Data retention

Metric history is retained according to your organization's plan and project policy. Use the Infrastructure page for recent investigation and export or summarize important findings in incidents or linked issues when they need to survive beyond the normal retention window.