VMware (ESXi / vCenter) Check Reference

Configuration fields, alert thresholds, monitored dimensions, and platform support for the VMware check in octoja.

Written By Stefan Steuer

Last updated 28 days ago

VMware (ESXi / vCenter) Check Reference

Configuration options and alert behaviour for the VMware (ESXi / vCenter) check.

The VMware check connects to a vCenter Server or standalone ESXi host over the vSphere SOAP API and evaluates three dimensions: host alerts, VM power states, and datastore capacity. Default interval: 5 minutes. The check runs on the octoja agent; the monitored vCenter / ESXi does not need an agent.

Configuration fields

Field	Type	Required	Default	Description
Host	string	Yes	—	vCenter / ESXi hostname or IP (e.g. `vcenter.example.com`); an `http://` or `https://` prefix is accepted and normalised
Username	string	Yes	—	vSphere user (e.g. `administrator@vsphere.local`)
Password	password	Yes	—	Password for the vSphere user
Ignore SSL certificate errors	boolean	No	true	Accept self-signed certificates (typical for vCenter / ESXi)
Monitor host alerts	boolean	No	true	Flag disconnected, not-responding, or powered-off hosts
Monitor VM states	boolean	No	true	Count running VMs; warn on suspended VMs
Monitor datastores (LUNs)	boolean	No	true	Check datastore capacity
Datastore warning threshold (% used)	number	No	80	Warn when datastore usage at or above this percent. Only visible when datastore monitoring is on
Datastore critical threshold (% used)	number	No	90	Critical when datastore usage at or above this percent. Only visible when datastore monitoring is on

Alert behaviour

Condition	Severity
Authentication failure, network error, or SOAP request error	Failure
Host is disconnected or not responding	Critical
Host is powered off	Warning
Host is in standby power state	Warning
Host overall status is red	Critical
Host overall status is yellow	Warning
One or more VMs in suspended state	Warning
Datastore is inaccessible (`summary.accessible=false`)	Critical (independent of usage threshold)
Any datastore used % ≥ critical threshold	Critical
Any datastore used % ≥ warning threshold (and < critical)	Warning
All active dimensions clean	OK

Metrics collected

Per check run:

Virtual machines — running count out of the total inventory (shown as "Virtual machines x/y running")
Datastores — datastore count, plus per-datastore capacity in GB, free space in GB, used %, and computed severity
Alerts — list of host alerts (name, status text, entity name, severity)
Problem VMs — list of suspended VMs (name, power state, severity)

Platform support

The check runs on the octoja agent; reachability to the vCenter / ESXi SOAP endpoint matters, not the agent OS.

Agent platform	Supported
Windows	Yes
macOS	Yes
Linux	Yes

vSphere target	Supported
vCenter Server	Yes
ESXi host (standalone)	Yes

Notes

The check runs every 5 minutes on the agent. The interval is not user-configurable.
The vSphere user needs read access to the inventory you want monitored. The built-in Read-only role is sufficient; assign it at the inventory level you want covered (host, cluster, datacenter, or root).
Datastore thresholds are evaluated per datastore against the global warning / critical thresholds. The check does not currently support per-datastore overrides.
If the warning threshold is set above the critical threshold, the check silently swaps the two values at runtime.
The SOAP session is opened, queried, and closed within each check interval — the agent does not maintain a long-lived connection.
For a multi-vCenter estate, configure one check per vCenter. The check does not federate across vCenters.
The device Checks tab visualises datastore usage history with dashed lines marking the warning and critical thresholds, and aggregates repeated host alerts into an Alert events list.