Hyper-V Host Check Reference

All configuration fields, thresholds, and result states for the Hyper-V Host check in octoja.

Written By Stefan Steuer

Last updated 26 days ago

Hyper-V Host Check Reference

The Hyper-V Host check runs on the octoja agent installed on a Hyper-V host and reports host-level health: virtual-machine state, Hyper-V Replica, checkpoints, integration services, and storage-volume usage. It is distinct from the per-VM Hyper-V VM Status check.

Configuration fields

The table lists every field in the order it appears in the check editor.

FieldTypeRequiredDefaultDescription
VMs that must runList of stringsNo—Virtual machines that must be running; any that is not running makes the result Critical
VMs to ignoreList of stringsNo—Virtual machines excluded from counts and alerts
Checkpoint age warning (days)NumberNo7Warns when a VM's oldest checkpoint is older than this
Checkpoint count warningNumberNo3Warns when a VM has more checkpoints than this
Volume warning threshold (%)PercentNo85Storage-volume usage that triggers a warning
Volume critical threshold (%)PercentNo95Storage-volume usage that triggers a critical result
Storage volumes / paths (optional)List of stringsNo—Explicit volumes or paths to check (for example D:, E:\Hyper-V, a mount-point folder, or a UNC share). Leave empty to auto-detect from the VHD locations and the host's default stores
Check Hyper-V ReplicaBooleanNoOnInclude replica health in the result
Check integration servicesBooleanNoOnInclude integration-service health for running VMs

If the warning and critical volume thresholds are entered the wrong way round, the check swaps them automatically.

Result states

ConditionSeverity
Host cannot be queried (module and WMI both fail)Critical
A required VM is not running or is missing; a VM is in a critical stateCritical
A volume reaches its critical threshold; replica health is criticalCritical
A volume reaches its warning thresholdWarning
A checkpoint is older than, or more numerous than, its thresholdWarning
Replica health is degraded, or integration services are degradedWarning
All checks passOK

The overall result is the worst severity across every VM, volume, replica, and integration-service check.

Collected metrics

  • Whether the host is reachable
  • Counts of running, stopped, critical, and other VMs
  • Replication job count and how many are unhealthy
  • Highest checkpoint age (days) and highest volume usage (%)
  • Per-VM name and state
  • Per-volume root, used percentage, and free bytes
  • A list of issues, each with severity, subject, value, and threshold

Platform support

PlatformSupported
Windows Server (Hyper-V host)Yes
Windows DesktopYes, where the Hyper-V role is present
LinuxNo
macOSNo

Notes

  • The check runs locally on the host — no network credentials are required.
  • With the Hyper-V PowerShell module installed it monitors VMs, replica, checkpoints, integration services, and storage. With only WMI available it falls back to reporting VM state.

See also: Configure a Hyper-V Host Check — the step-by-step setup guide.