Host metrics

Track your infrastructure’s health by sending host metrics to Honeybadger Insights. Monitor CPU usage, memory consumption, and disk space alongside your application errors and logs.

Using the Honeybadger CLI

The easiest way to collect host metrics is with the Honeybadger CLI. Download a prebuilt binary from the GitHub releases page, or install with Go:

go install github.com/honeybadger-io/cli@latest

See the CLI installation guide for other options, including Homebrew.

Start the metrics agent with your project API key:

hb agent --api-key PROJECT_API_KEY

The agent collects CPU, memory, and disk metrics every 60 seconds and sends them to Insights. You can customize the interval with the -i, --interval flag (see the CLI reference for details).

Querying agent metrics in Insights

Once metrics are flowing, you can query them in Insights. Each metric type sends a separate event:

{"@id": "ca4dee56-bede-453d-a41e-a6fd93d30eaf", "@stream.id": "3XepYQVyo5to", "@ts": "2026-01-12 22:22:11.000", "total_bytes": 994662584320, "used_bytes": 544694333440, "free_bytes": 449968250880, "used_percent": 54.76, "device": "/dev/disk3s1s1", "event_type": "report.system.disk", "host": "vonnegut.lan", "mountpoint": "/", "fstype": "apfs"}
{"@id": "d76ca037-3bab-4c1c-beb1-a18b9e6ff765", "@stream.id": "3XepYQVyo5to", "@ts": "2026-01-12 22:22:11.000", "total_bytes": 51539607552, "used_bytes": 38632865792, "free_bytes": 164954112, "available_bytes": 12906741760, "used_percent": 74.96, "event_type": "report.system.memory", "host": "vonnegut.lan"}
{"@id": "5b7c4060-1ff3-4d52-90d8-a9d3af17174a", "@stream.id": "3XepYQVyo5to", "@ts": "2026-01-12 22:22:11.000", "num_cpus": 14, "used_percent": 32.85, "load_avg_1": 3.35009765625, "load_avg_5": 3.73046875, "load_avg_15": 3.86083984375, "event_type": "report.system.cpu", "host": "vonnegut.lan"}

Here’s an example BadgerQL query to get a snapshot of disk usage:

fields @ts, mountpoint::str, used_percent::float
| filter event_type::str == "report.system.disk"
| sort used_percent desc
| limit 1 by mountpoint::str

@ts TIME EDT	mountpoint STR	used_percent FLOAT
2026-01-12 16:15:06.000	/	55.01
2026-01-12 16:14:21.000	/data	11.91

Using Vector

If you need more flexibility or are already using Vector in your infrastructure, you can use it to send host metrics to Insights instead.

Here’s a sample configuration:

# Put this in /etc/vector/vector.yaml
sources:
  host:
    type: "host_metrics"

sinks:
  honeybadger_events:
    type: "http"
    inputs: ["host"]
    uri: "https://api.honeybadger.io/v1/events"
    request:
      headers:
        X-API-Key: "PROJECT_API_KEY"
    encoding:
      codec: "json"
    framing:
      method: "newline_delimited"

The easiest way to run Vector is via Docker. Here’s a sample Docker Compose configuration, assuming your Vector configuration is in a file named vector.yaml:

version: "3.2"
services:
  vector:
    image: timberio/vector:latest-alpine
    volumes:
      - "vector.yaml:/etc/vector/vector.yaml:ro"

See the Vector documentation for more configuration options.

Querying Vector’s metrics

Vector’s metrics are structured like this:

{
  "@id": "01922983-149f-7a69-b5e1-ddca928d815e",
  "@stream.id": "cEhUcrZrnny0",
  "@ts": "2025-09-25 14:08:26.048",
  "gauge": {
    "value": 1.25
  },
  "tags": {
    "collector": "load",
    "host": "api-10-0-11-252"
  },
  "kind": "absolute",
  "name": "load15",
  "namespace": "host"
}

Here’s an example BadgerQL query to get a snapshot of disk usage:

fields @ts, tags.mountpoint::str, round(gauge.value::float * 100, 2) as used_percentage
| filter namespace::str == "host"
| filter name::str == "filesystem_used_ratio"
| filter gauge.value::float > 0.0
| filter tags.filesystem::str not in ["tmpfs", "devtmpfs", "squashfs"]
| sort @ts
| limit 1 by tags.mountpoint

@ts TIME EDT	tags.mountpoint STR	used_percentage FLOAT
2025-09-25 10:45:11.047	/	29.77
2025-09-25 10:45:11.047	/efs	0