VMware Monitor

[READ] Currently authenticated vCenter/ESXi sessions (who is logged in). Returns the list envelope with a real ``total``; each row has user_name, full_name, login_time, last_active, ip_address, user_agent (which client — e.g. Aria's adapter shows ``VMware vim-java``), call_count, kind (user/service) and a ``current`` flag for this skill's own session. vCenter's own solution users (``vpxd-extension-<machine id>`` and similar) are folded by default and counted in ``service_sessions``. Requires the Sessions privilege; low-privilege accounts get a single explanatory row instead of a traceback. Use this to attribute a change to a person — pair it with active_tasks, which names the user who started each task. Read-only — terminating a session is not supported here.

[READ] In-flight (and optionally just-completed) vCenter tasks. Answers "why is the cluster busy?". Returns the list envelope {items, returned, limit, total, truncated, hint} with a real ``total``; each row has name, entity, state, progress_pct, start_time, user, an active flag and error (for failed recent tasks), running/queued first. vCenter keeps only a short recent-task window, so an old task may simply be gone rather than absent. Use this before blaming load: a migration or clone in flight explains pressure that host_performance shows. Pair with active_sessions to see who started it. Read-only — cancelling a task belongs to vmware-aiops.

[READ] Per-host ESXi management certificate expiry. An expired ESXi cert drops host management — this surfaces it before the outage. Returns the list envelope with a real ``total``; each row has host, not_after, days_until_expiry and an ``expiring`` flag, soonest first. Host certificates only — the vCenter appliance's own certificate is not covered. Use this alongside license_status and ntp_status for a platform-hygiene sweep. Renewing a certificate is a write this skill cannot do; use vmware-aiops or vCenter directly.

[READ] One-glance health rollup for every cluster — "is anything on fire?". Start here for single-vCenter triage. Batches hosts, VM power state, live CPU/memory pressure and alarms per cluster, scores each "ok"/"warn"/ "critical", and ranks the anomalies into ``top_issues``. Use this instead of stitching list_all_clusters + list_esxi_hosts + get_alarms yourself. Returns {totals, top_issues, issues_total, clusters, snapshot, customization_hint} — not the list envelope. Lead with ``top_issues`` (worst first), show ``clusters`` as context, always echo ``customization_hint`` last. Point-in-time — no trending. ``top_issues`` includes datastores thin-provisioned past 100% of capacity (kind capacity, scope datastore), attributed to the cluster of a host that mounts them; datastore_capacity has the full table. Alarm issues carry ``condition_now`` and ``acknowledged_days``. Only a ``cleared`` alarm (its condition is read to be false now) ranks after live issues; an ``unknown`` one is not re-checked and keeps its severity rank, however long ago it was acknowledged — report it as possibly still live. Then drill into what ``top_issues`` names with vm_investigation_bundle, host_investigation_bundle or datastore_investigation_bundle; use cross_vcenter_attention to cover every target at once. Acting on a finding belongs to vmware-aiops.

[READ] Result of the last vLCM remediation (apply) on one cluster (REST). When to use: after a patch/remediation, to confirm the last apply succeeded and when it finished. Use cluster_patch_compliance for current drift; use this for the outcome of the most recent apply. What it returns: {available, cluster, status, end_time, note, fields}, read defensively. A cluster never remediated may return a "not found" teaching error; a 503 yields ``available: False`` (mid-patch, retry). Gotchas: ``cluster`` is the cluster MoID (e.g. domain-c123) — see list_all_clusters. Read-only. Endpoint and field parse verified against a live VCF 9.1 vCenter.

[READ] vLCM software (patch) compliance for one cluster (vSphere Automation REST). When to use: to check whether a cluster's hosts match their assigned software image/baseline before or after a patch cycle. Complements host_memory_tiering (that is per-host hardware; this is per-cluster lifecycle state). What it returns: {available, cluster, status, hosts_total, non_compliant_hosts, scan_time, note, fields}. ``available: False`` means vCenter answered 503 — it is likely mid-patch (vSphere has no maintenance-ETA endpoint; retry shortly), not an error. Endpoint and field parse verified against a live VCF 9.1 vCenter (see ``note``). Gotchas: ``cluster`` must be the cluster MoID (e.g. domain-c123), which the REST API requires — get it from list_all_clusters, not the display name. Read-only: reports compliance only; it never runs a remediation.

[READ] "What needs attention now?" across EVERY configured vCenter — one list. Start here when the estate has more than one vCenter. Rolls every configured target's cluster-health summary into one globally ranked ``top_issues`` list (worst first, each tagged with its ``vcenter``) plus a per-target rollup. Use this instead of calling cluster_health_summary once per target and merging yourself. Returns a rollup, not the list envelope; lead with ``top_issues``. Degrades gracefully: an unreachable target is listed under ``unreachable`` with a reason and the rest still aggregate. Point-in-time — no trending. Overlap is removed by identity: a host reached through a vCenter and as its own ESXi target counts once (hardware UUID), a datastore seen through both is one issue with the other view's figure under ``also_seen_via`` (datastore URL), and ``totals`` separates ``vcenters``, ``esxi_targets`` and ``unidentified_targets``. Then drill in with vm_investigation_bundle, host_investigation_bundle or datastore_investigation_bundle against the ``vcenter`` the issue names.

[READ] Per-datastore capacity with thin-provisioning over-commit. Returns the list envelope with a real ``total``: capacity_gb, free_gb, committed_gb, provisioned_gb, used_pct, overcommit_pct, riskiest first. Adds the risk signal list_all_datastores lacks — overcommit_pct over 100% means more space is promised to VMs than physically exists, so a thin datastore can fill up while still showing free space. Point-in-time. Whose figure: ``view`` (vCenter / ESXi host / unknown) and ``view_note``. Provisioned space is summed by the endpoint over the VMs it has registered on the datastore, so a vCenter and a directly-reached ESXi host can report different provisioned_gb for one datastore — each row's ``vm_count`` says how many VMs the figure covers, and ``vms_not_connected`` names those reported as orphaned/inaccessible/disconnected (None = could not be read). Use this for the capacity view, then datastore_investigation_bundle to drill into a specific datastore's hosts, VMs and alarms. Reclaiming space (delete snapshots, storage vMotion) belongs to vmware-aiops.

[READ] "What is happening around this datastore?" — one correlated drill-down. Use this instead of stitching list_all_datastores + datastore_capacity + get_alarms + get_events yourself. Returns one correlated bundle (not the list envelope): capacity / free space / accessibility, the hosts that mount it, a rollup of the VMs it backs, alarms across datastore/host, and a merged event timeline. All reads are batched. Explain it in operational language; do not dump it raw. Per-datastore latency is not included. Reach for it after cluster_health_summary flags storage pressure. Point-in-time snapshot — no trending. Freeing space (deleting snapshots, storage vMotion) belongs to vmware-aiops.

[READ] Get active/triggered alarms across the VMware inventory. Returns the list envelope with a real ``total``. Each alarm carries suggested_actions naming the companion skill and tool for remediation, who acknowledged it and when (``acknowledged_by`` / ``acknowledged_at``), and ``condition_now``: ``holds`` (live), ``cleared`` (vCenter still shows it but its state condition is false now — a stale alarm; see ``condition_note``), or ``unknown`` (event/metric-based or unreadable — never guessed). The envelope's ``stale_alarms`` counts the cleared ones. An expired-vCenter-license alarm is re-checked against this vCenter's own license assignment. ``object_label`` names alarms about the vCenter appliance itself (e.g. "vCenter appliance 192.168.60.16") that sit on the inventory root; ``entity_name`` stays the object vmware-aiops resolves. Do not report a ``cleared`` alarm as a live problem; do not report an ``unknown`` one as resolved. Empty ``items`` with ``truncated`` False means there genuinely are no active alarms — never report "no data" otherwise. Use this for the raw alarm list; prefer cluster_health_summary when you want alarms folded into a whole-cluster verdict. Then drill into the flagged object with vm_investigation_bundle or host_investigation_bundle.

[READ] Get recent vCenter/ESXi events filtered by severity. Returns the list envelope, newest first. Up to 5000 events in the window are read; when more matched, ``read_truncated`` is true and ``read_note`` says how far back the read got — the oldest events were not examined, so narrow ``hours`` before concluding nothing happened earlier in the window. Severity is this skill's own ranking where it has one, and otherwise vCenter's published event catalogue. An event neither can rank comes back with severity "unknown" (it is returned, not filtered out) and is counted in the envelope's ``unclassified``, with ``classification_note`` explaining. An empty ``items`` alongside a non-zero ``unclassified`` does NOT mean the window was quiet — read the note before reporting all-clear. Use this for an inventory-wide event sweep. When you already know the object, prefer vm_investigation_bundle / host_investigation_bundle instead: they return the same events correlated with that object's state in one call. ESXi syslog lines are not events — use host_log_scan for those.

[READ] Get hardware sensor status (temperature, voltage, fan, ...) for all hosts. Returns the list envelope with a real ``total``; each row has host, sensor_name, type, reading, unit and status (green/yellow/red). No rows for a host is not "hardware is fine": every connected host that reports no sensors is listed in ``hosts_without_sensors`` with ``cim_server_running`` / ``cim_server_policy`` (the CIM Server, sfcbd-watchdog, supplies the sensors; null = not read), and ``sensors_note`` says what that means — quote it. Use this for physical hardware only — for CPU/memory load use host_performance, and follow up on a red sensor with host_investigation_bundle to see the alarms and events around that host.

[READ] Get host service status (running state and startup policy). Returns the list envelope; each row has host, service key, label, running (bool) and policy (on/off/automatic). Every matching host is enumerated, so ``truncated`` is always False. Use this to check whether SSH, NTP or the firewall service is in the expected state. For NTP specifically prefer ntp_status, which also reports the configured servers. Starting or stopping a service is a write — this skill cannot do it; use vmware-aiops.

[READ] "What is happening around this ESXi host?" — one correlated drill-down. Use this instead of stitching list_esxi_hosts + host_performance + get_alarms + get_events yourself. Returns one correlated bundle (not the list envelope): the host's state (connection, CPU/memory pressure, version, uptime), its cluster, a rollup of the VMs it runs, the datastores it mounts, alarms across host/cluster/datastore, live performance, and a merged event timeline. All reads are batched. Explain it in operational language; do not dump it raw. Reach for it after cluster_health_summary flags a host. Point-in-time snapshot — no trending; for syslog lines use host_log_scan. Acting on a finding (maintenance mode, evacuate) belongs to vmware-aiops.

[READ] Scan recent ESXi host syslog lines for error/warning patterns. Reads the last ``lines`` entries of the hostd/vmkernel/vpxa logs via the diagnostic system and returns only the lines matching known trouble patterns (error, fail, critical, panic, lost access, timeout, …). Severity follows the level ESXi wrote on the line (Cr/Er/Wa/In…, raw token in ``log_level``); a critical keyword still wins. By default findings are grouped by pattern — each item has count, hosts, first_seen/last_seen (log time), severity, source (``host_log:<key>``), pattern and one sample; ``lines_matched`` is the ungrouped count. ``group=false`` returns one row per line (severity, source, message, time, entity, log_level, log_time). Returns the list envelope {items, returned, limit, total, truncated, hint}. ``total`` is null on purpose — this is "errors within the scanned window", not all errors ever. ``logs_unavailable`` lists every host/log that could NOT be read, with the reason (e.g. the account lacks Global.Diagnostics); empty ``items`` means nothing matched only when ``logs_unavailable`` is empty too. Use this when get_events or host_investigation_bundle show a host in trouble but not why: vCenter events and ESXi syslog are different sources. Filter with ``host_name`` to keep the scan fast on large clusters; a name that matches no host returns an error (get the exact name from list_esxi_hosts), not an empty result. Every call reads the last ``lines`` lines afresh.

[READ] Per-host memory tiering (vSphere 9.1) and NVMe uplift ratio. When to use: to see which ESXi hosts back RAM with NVMe (memory tiering, 8.0U3+), how large each tier is, and how much of a host's apparent memory rides on NVMe rather than DRAM. This is the only source of measured tier byte sizes. Returns the list envelope {items, returned, limit, total, truncated, hint}. Each row: host, tiering_type (noTiering|hardwareTiering|softwareTiering), tiering_active, dram_gb, nvme_gb, total_tiered_gb, uplift_ratio (total/DRAM, None if DRAM unknown), and a per-tier breakdown. A host with tiering off reads as tiering_type "noTiering", nvme_gb 0.0 — that is a real "checked, none", not a gap. Gotchas: reads pyVmomi HostSystem.hardware.memoryTierInfo (needs ESXi 8.0U3+/9.x); older hosts report tiering_type "unknown". Read-only.

[READ] Real-time CPU/memory/disk/network utilisation per ESXi host. Returns the list envelope with a real ``total`` (hosts that reported metrics). Unlike list_esxi_hosts (static config: cores, total GB) this is LIVE 20-second PerfManager data: cpu_usage_pct, mem_usage_pct, mem_consumed_mb, disk_kbps, net_kbps, busiest first. Disconnected hosts and hosts without a real-time provider are skipped, not reported as zero. Point-in-time only — no historical trend. Use this to find which host is hot, then host_investigation_bundle to drill into it, or vm_performance to see which VMs on it are driving the load.

[READ] vCenter/ESXi license inventory with usage and expiry. Returns the list envelope, one row per license: name, edition_key, total/used units, unlimited flag (row total == 0) and expiration. Every license is enumerated, so ``truncated`` is always False — this is the complete inventory. Use this to catch over-allocation or an approaching expiry, alongside certificate_status and ntp_status for a platform-hygiene sweep. ``assignments`` says which license each asset (vCenter, hosts, clusters) is assigned, with ``expired`` per asset — use it to tell whether an "expired license" alarm still applies. It is null with ``assignments_note`` when the account cannot read assignments. License keys are never returned. Assigning a license is a write.

[READ] List clusters with host count, DRS/HA status, and resource totals. Returns the list envelope with a real ``total``. Static topology only — use this to resolve a cluster name, then cluster_health_summary, which supersedes stitching this with list_esxi_hosts and get_alarms yourself.

[READ] List datastores with capacity, free space, type, and VM count. Returns the list envelope with a real ``total``. Raw free/used only — use this to resolve a datastore name, then datastore_capacity for thin-provisioning over-commit risk or datastore_investigation_bundle to drill into one datastore.

[READ] List networks with name, attached VM count, and accessibility. Returns the list envelope with a real ``total``. Name, vm_count and accessible only — no VLAN, uplink or NSX overlay detail. Use this to resolve a port-group name, then vm_info for the NICs of one VM. NSX segments live in vmware-nsx.

[READ] List ESXi hosts with CPU cores, memory, version, VM count, and uptime. Returns the list envelope; ``total`` is the real host count. Static config only (cores, total GB) — use this to resolve a host name, then host_performance for live load or host_investigation_bundle to drill into one host.

[READ] List virtual machines, with filtering, sorting, and field selection. Returns the family list envelope {items, returned, limit, total, truncated, hint}; ``total`` is the real post-filter count, so read ``truncated`` before summarising. Over 50 VMs with no limit/fields, only the first five fields below come back (``mode`` says which). ``vms`` is a deprecated pre-1.8.0 alias of ``items``, removed in 2.0 — read ``items``. Use this to resolve an exact VM name, then vm_info for detail or vm_investigation_bundle to drill into one; for a fleet-wide view start at cluster_health_summary instead.

[READ] Per-host NTP configuration health (servers + ntpd service state). Returns the list envelope; every matching host is enumerated, so ``truncated`` is always False. Each row has host, reachable, ntp_servers, ntpd_running, ntpd_policy and a ``healthy`` flag (servers configured AND ntpd running). The SOAP API does not expose live clock offset or stratum — this is configuration health only; for actual offset use esxcli on the host. healthy/ntp_servers/ntpd_running are null — not false/empty — for a host vCenter could not reach or could not read. Null means nothing was observed; false means NTP is misconfigured. Filtering rows for `healthy == false` will not surface the unread ones, so check the envelope's `hosts_unreachable` count and `unreachable_note` before reporting the estate as healthy. The envelope's ``ntp_sources_consistent`` compares hosts with each other: false when hosts that have servers configured use different ones (each row can still be healthy — this is how clocks drift apart), with ``ntp_sources_note`` naming which host uses which servers; null when fewer than two hosts have servers to compare. Prefer this over get_host_services for time problems: that tool reports whether ntpd runs but not which servers are configured. Fixing NTP is a write; use vmware-aiops.

[READ] Per-resource-pool CPU/memory reservation, limit, and current usage. Returns the list envelope with a real ``total``; each row has name, cpu_reservation_mhz, cpu_limit_mhz, cpu_usage_mhz, mem_reservation_mb, mem_limit_mb, mem_usage_mb, sorted by memory usage descending. A limit of -1 means unlimited. Pool names are not cluster-qualified, so identical names in different clusters may look alike. Use this when a VM is throttled but its host is not busy — the cap is usually the pool. Then vm_performance to see which VMs in it are demanding, or cluster_health_summary for the cluster-level picture.

[READ] Sweep ALL VMs for snapshots and flag old / sprawling ones. Use this for fleet-wide snapshot sprawl; prefer vm_list_snapshots when you only care about one VM. Returns {total_snapshots, old_snapshots, vms_with_snapshots, threshold_days, snapshots[], hint} — a rollup, not the list envelope. Each row has age_days, is_old and an est_size_mb lower bound (snapshotData+snapshotMemory; delta-disk growth is not separable per-snapshot via the API). Read-only — deleting snapshots belongs to vmware-aiops.

[READ] vCenter appliance deployment size (NEW in vSphere 9.1, REST). When to use: to read the vCenter appliance's current (and, where reported, target) deployment size class — capacity-planning context that inventory/perf tools do not cover. What it returns: {available, note, fields} where ``fields`` is a defensive passthrough of the endpoint's top-level scalar values. ``available: False`` means vCenter answered 503 (busy/restarting) or is older than 9.1 — ``reason`` says which; nothing crashed, and neither is a failure. Gotchas: 9.1-only endpoint — an older vCenter returns ``available: False``, not data. Endpoint and field parse verified against a live VCF 9.1 vCenter. Read-only.

[READ] How long backups held a snapshot open on one VM, from task history. Image-level backup products (Veeam, Commvault, Rubrik, NetBackup) snapshot the VM, copy the frozen disks, then delete the snapshot. vCenter records both ends, so the backup window is recoverable without credentials for the backup server. This is a LOWER BOUND on the job, not its duration: work the product does before the snapshot is taken and after it is removed is invisible to vCenter. The returned ``basis`` says so — quote it alongside any figure. Returns a rollup, not the list envelope: counts, four hour statistics (backup_active / snapshot_present / total_window / snapshot_removal), latest_cycle, longest_cycle, and ``unmatched`` rows for creations with no removal (a backup that left its snapshot behind) or removals whose creation predates the window. Read two fields before reporting all-clear. ``history_unavailable`` non-null means the history could not be read at all — that is not "no backups". ``coverage_note`` non-null means vCenter has already expired part of the requested window (``task.maxAge`` — 30 days by default; the option is NOT called vpxd.task.maxAge, which raises vim.fault.InvalidName), so the counts describe a shorter period than ``days`` asked for. ``window_fully_covered`` is the positive form: True when retention is at least ``days`` and nothing in the window can have expired, so a VM whose oldest task is recent was simply quiet; None when retention or the history could not be read. An unmatched creation is not a failed backup. Each one carries ``status: "open"``, ``age_hours``, this VM's ``longest_completed_cycle_hours`` and ``possibly_in_progress`` — True while it is inside that VM's own observed envelope, False past it, None when there is no completed cycle to compare against. Do not report ``incomplete_cycles`` as failures without reading those. The creation *task* itself, during the seconds it executes, is absent entirely: no completion time yet, so it forms n…

[READ] Get detailed information about one VM (CPU, memory, disks, NICs, snapshots). Returns a single detail dict, not the list envelope. Static configuration only — for live CPU/memory use vm_performance, and for the same VM correlated with its host, alarms and events use vm_investigation_bundle. Use this when you already know the exact name; get it from list_virtual_machines first, since an unknown name returns a teaching error rather than a match. Reconfiguring the VM belongs to vmware-aiops.

[READ] "What is happening around this VM?" — one correlated drill-down. Use this instead of stitching vm_info + vm_list_snapshots + get_alarms + vm_performance + get_events yourself. Returns one correlated bundle (not the list envelope): the VM's state, its host, cluster and backing datastores, its snapshots and triggered alarms, live performance, and a merged event timeline across VM/host/cluster/datastore (newest first). All reads are batched. Explain it in operational language; do not dump it raw. Reach for it after cluster_health_summary names a problem VM, or when asked "what's going on with <vm>?". Point-in-time snapshot — no trending. Acting on what you find (power, migrate, delete snapshot) belongs to vmware-aiops.

[READ] List all snapshots of one VM, including the nesting hierarchy. Returns the list envelope, one row per snapshot with name, description, created timestamp, state and level (0 = root; children are level+1). Empty ``items`` with ``truncated`` False means the VM genuinely has no snapshots. Read-only — creating, reverting and deleting snapshots live in vmware-aiops. Use this for one known VM; prefer snapshot_aging to sweep the whole inventory for old or sprawling snapshots. Get the name from list_virtual_machines first — an unknown name returns a teaching error.

[READ] Real-time CPU/memory/disk/network utilisation per virtual machine. Returns the list envelope with a real ``total`` (VMs that reported metrics) — with the default limit of 25, ``truncated`` tells you whether more VMs sit behind it. LIVE data (cpu_usage_pct, mem_usage_pct, mem_consumed_mb, mem_ballooned_mb, mem_swapped_mb, disk_read_kbps, disk_write_kbps, net_kbps), busiest first. mem_usage_pct is mem.usage.average — ACTIVE guest memory over configured, not consumed, so it can read low on a VM under pressure; non-zero mem_ballooned_mb (mem.vmmemctl.average) or mem_swapped_mb (mem.swapped.average) is the pressure signal. ``counters`` names the counter behind every field. Only powered-on VMs have a real-time provider; powered-off VMs are skipped. Point-in-time only. Use this to rank load across VMs; for one VM's configuration use vm_info, and to see the same VM correlated with its host, alarms and events use vm_investigation_bundle.