VIRT-007 · Script
Virtual Machine Performance Report
Reports current or recent CPU, memory, storage and network usage of virtual machines and flags the most heavily used ones.
What it does
Read-only. Nothing is changed. Writes one CSV row per running virtual machine to -ReportDir.
VMware: reads vCenter Server or ESXi performance statistics for CPU usage (%), memory usage (%), disk throughput (KB/s) and network throughput (KB/s), as average and peak values. -Hours 0 (default) uses the real-time samples from about the last 5 minutes; a larger value uses the historical statistics kept by vCenter Server for that period. How far back data exists depends on your vCenter statistics settings.
Hyper-V: reports the current CPU usage (%), assigned memory and memory demand of each running VM. When resource metering is turned on for a VM (Enable-VMResourceMetering), it also reports the averages Hyper-V has collected since metering was last reset: CPU (MHz), memory (MB), storage IOPS and network traffic (MB). This script does not turn metering on. -Hours is not used for Hyper-V.
A VM is flagged when its average CPU is at or above -CpuWarnPercent or its memory usage is at or above -MemoryWarnPercent. Runs silently. No prompts.
Requirements
Windows PowerShell 5.1+. Hyper-V: the Hyper-V PowerShell module. VMware: VMware PowerCLI installed by you.
How to run it
- Run from: an admin workstation or scheduled task with the Microsoft modules installed and app sign-in configured
- This is an admin script for your Virtualization tenant, not a per-device endpoint script
- User interaction: none with app-only sign-in
- Schedule: run on demand, or weekly for reports
Settings
| Name | What it does | Options | Default |
|---|---|---|---|
| Platform | HyperV (default) or VMware. | HyperV, VMware | HyperV |
| VMName | Virtual machine names, wildcards allowed, for example "SRV-*". Empty = all running VMs. | (none) | |
| Hours | VMware only. 0 (default) = real-time, about the last 5 minutes. 1 to 720 = average and peak over that many past hours, for example 24. | 0 | |
| CpuWarnPercent | Flag VMs with average CPU usage at or above this percentage. Default 80. | 80 | |
| MemoryWarnPercent | Flag VMs with memory usage at or above this percentage (Hyper-V: memory demand compared with assigned memory). Default 90. | 90 | |
| ComputerName | Hyper-V only. Name of a remote Hyper-V host, for example HV01. Leave empty to use this computer. The account running the script needs Hyper-V administrator rights on that host. | ||
| Server | VMware only. vCenter Server or ESXi host name, for example vcenter.school.local. | ||
| CredentialPath | VMware only. Path to a credential file created with Get-Credential | Export-Clixml, for example C:\ProgramData\Runbookia\Secure\vcenter.xml. Create the file as the same account (for example SYSTEM) on the same computer that runs this script; Windows encrypts it so no other account can read it. Not needed with UseExistingSession. | ||
| UseExistingSession | VMware only. Reuse a vCenter Server or ESXi connection that is already open in this PowerShell session (from Connect-VIServer) instead of CredentialPath. | False | |
| IgnoreCertificateErrors | VMware only. Accept an untrusted or self-signed server certificate for this run only. Off by default; the PowerCLI setting on disk is not changed. | False | |
| ReportDir | Folder for CSV reports. Default C:\ProgramData\Runbookia\Reports. | C:\ProgramData\Runbookia\Reports |
Exit codes
- 0 = No VM above the thresholds
- 1 = At least one VM is above a threshold, or a named VM was not found
- 2 = Script error (missing module, connection failed)
Testing steps
- Run it on one test tenant or small OU and check the output and log.
- Check the exit code: 0 = OK, 1 = needs attention, 2 = error (see log), 9 = this copy is past its Valid until date.
- Roll out to a small group next, then everyone.
Rollback steps
Report only. Nothing is changed, so nothing needs to be rolled back.
Version and change log
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | November 2026 | First release. |