Skip to content

docs: explain Imp metrics discovery #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
syscod3 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: explain Imp metrics discovery #101

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 27 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,12 +392,33 @@ slice.

## Metrics & Observability

Imp exposes operator and agent metrics so you can monitor VM lifecycle and platform health:

- VM state and phase metrics
- Scheduling/boot latency metrics
- Guest resource metrics (CPU, memory, disk)
- Prometheus-compatible scraping and dashboards
Imp exposes Prometheus-compatible `/metrics` endpoints:

| Component | Default port | Metric-family examples |
| --- | --- | --- |
| Operator | `:8080` | `imp_vm_scheduling_latency_seconds`, `imp_vm_boot_latency_seconds` |
| Agent | `:9090` | `imp_vm_state`, `imp_vm_guest_cpu_usage_ratio`, `imp_vm_guest_cpu_iowait_ratio`, `imp_vm_guest_memory_used_bytes`, `imp_vm_guest_disk_used_bytes` |
| Runtime | `:8082` | `imp_runtime_ready`, `go_*`, `process_*` |

Sources: [operator endpoint](cmd/operator/main.go), [controller metrics](internal/controller/metrics.go),
[agent metrics](internal/agent/metrics.go), and [runtime endpoint](cmd/runtime/main.go).

The [chart defaults](charts/imp/values.yaml) enable an operator
[ServiceMonitor](charts/imp/templates/operator/servicemonitor.yaml) and
[agent](charts/imp/templates/agent/podmonitor.yaml)/[runtime](charts/imp/templates/runtime/podmonitor.yaml)
PodMonitors. This route requires Prometheus Operator and its monitor CRDs, with a
Prometheus instance configured to select the monitors; creating them alone does
not prove scraping works.

Unraid uses Grafana Kubernetes Monitoring collector-side discovery instead of
Prometheus Operator monitor CRDs. For that route, disable
`metrics.serviceMonitor.enabled` and `metrics.podMonitor.enabled` in the Imp
chart, and configure the collector to discover and scrape all three endpoints.
Disabling monitors does not disable the metrics endpoints or configure the collector.

Ephemeral VM names in the `impvm` label create new Prometheus series as VMs churn.
Monitor series cardinality and retention/storage usage; deleting a VM stops its
exported samples but does not remove its retained history from Prometheus.

## Reconcile Sequence

Expand Down
Loading