← Home Getting Started Commands Configuration SSH & Shutdown USB Accessories Building

Prometheus Metrics

havm can expose Prometheus metrics on an HTTP endpoint for monitoring with Prometheus or any compatible scraper. Enable it in the config:

metrics:
  enabled: true

The server binds to 127.0.0.1:9210 and [::1]:9210 (both loopbacks) by default and serves two endpoints:

Endpoint	Description
`GET /metrics`	Prometheus text format metrics
`GET /health`	Liveness check — returns `200 OK`

Available Metrics

Metric	Type	Labels	Description
`havm_vm_state`	gauge	`state`	VM state (running, stopped, paused, starting, …)
`havm_usb_accessories`	gauge	—	Number of connected USB accessories
`havm_disk_usage_bytes`	gauge	`disk`, `type`	Disk image size: `type=logical` (configured size) or `allocated` (actual APFS allocation)

Prometheus also adds its synthetic up metric — 1 when the scrape succeeds, 0 when havm is unreachable.

Prometheus Scrape Config

scrape_configs:
  - job_name: 'havm'
    static_configs:
      - targets: ['localhost:9210']

LAN Access

The server binds to both loopback addresses by default. To allow LAN access (e.g., a dedicated Prometheus host), bind to all interfaces:

metrics:
  enabled: true
  prometheus:
    host: ["::"]

Custom Port

metrics:
  enabled: true
  prometheus:
    port: 8080

Grafana Dashboard

An example Grafana dashboard is included in the repository at grafana/dashboard.json. Import it via Grafana’s UI (Dashboards → New → Import) or place it in a provisioned dashboard directory.

The dashboard covers:

Panel	Type	Metric
VM Status	Stat	`havm_vm_state`
VM Status (History)	Time series	`havm_vm_state`
USB Devices	Stat	`havm_usb_accessories`
Disk (Logical)	Stat	`havm_disk_usage_bytes{type="logical"}`
Disk (Allocated)	Stat	`havm_disk_usage_bytes{type="allocated"}`
Usage (%)	Gauge	`allocated / logical * 100`
Disk (Unallocated)	Stat	`logical - allocated`
Storage Usage (History)	Time series	`havm_disk_usage_bytes`

Configuration Reference

metrics:
  enabled: true           # default: false
  type: prometheus        # prometheus (default) — extensibility point for OTLP
  prometheus:
    port: 9210            # default: 9210
    host: ["127.0.0.1", "::1"]  # default: both loopbacks

The type field is an extensibility point — only prometheus is supported today, but the field exists for future OTLP or other formats.