Public/Get-PrismVMStats.ps1
|
function Get-PrismVMStats { <# .SYNOPSIS Retrieves performance statistics for one or more Prism VMs. .DESCRIPTION Accepts PrismVM objects directly or through the pipeline. Retrieves AHV VM statistics using each VM's originating session unless overridden. The default time range is the hour preceding EndTime (now by default). All VMs in an invocation use the same time range. .PARAMETER VM A PrismVM object or collection of PrismVM objects to query. .PARAMETER StartTime Start of the reporting period. Defaults to one hour before EndTime. Supply a datetimeoffset with an explicit offset for unambiguous times. .PARAMETER EndTime End of the reporting period. Defaults to the current UTC time. .PARAMETER SamplingInterval Sampling interval in seconds. Defaults to 60. .PARAMETER StatType Optional down-sampling operator: SUM, MIN, MAX, AVG, COUNT, or LAST. Defaults to AVG. .PARAMETER Select OData property selection, such as 'stats/hypervisorCpuUsagePpm'. Defaults to '*' to request all available properties. .PARAMETER PrismSession Overrides the originating session for all supplied VMs. .EXAMPLE Get-PrismVMStats -VM $vm .EXAMPLE Get-PrismVMStats -VM $vms -SamplingInterval 60 -StatType AVG .EXAMPLE $vms | Get-PrismVMStats -StartTime ([datetimeoffset]'2026-11-10T09:00:00-04:00') -EndTime ([datetimeoffset]'2026-11-10T10:00:00-04:00') .OUTPUTS PrismVMStats with VM/session context, reporting period, query settings, Stats (the API's time series), and RawData (the complete VM stats payload). .NOTES GET /vmm/v{ApiVersion}/ahv/stats/vms/{extId} (getVmStatsById). Reference: https://developers.nutanix.com/api/v1/sdk/namespaces/main/vmm/versions/v4.2/languages/python/ntnx_vmm_py_client.api.stats_api.html #> [CmdletBinding()] [OutputType([PrismVMStats])] param( [Parameter(Mandatory, Position = 0, ValueFromPipeline)] [ValidateNotNullOrEmpty()][PrismVM[]]$VM, [Parameter()][datetimeoffset]$StartTime, [Parameter()][datetimeoffset]$EndTime = [datetimeoffset]::UtcNow, [Parameter()][ValidateRange(1, [int]::MaxValue)][int]$SamplingInterval = 60, [Parameter()][ValidateSet('SUM', 'MIN', 'MAX', 'AVG', 'COUNT', 'LAST')][string]$StatType = 'AVG', [Parameter()][ValidateScript({ -not [string]::IsNullOrWhiteSpace($_) })][string]$Select = '*', [Parameter()][string]$PrismSession ) begin { if (-not $PSBoundParameters.ContainsKey('StartTime')) { $StartTime = $EndTime.AddHours(-1) } if ($StartTime -ge $EndTime) { throw 'StartTime must be earlier than EndTime.' } $query = @{ '$startTime' = $StartTime.ToString('o') '$endTime' = $EndTime.ToString('o') # Prism requires these even though the SDK documents them as optional. '$samplingInterval' = $SamplingInterval '$statType' = $StatType.ToUpperInvariant() '$select' = $Select } } process { foreach ($item in $VM) { if ($null -eq $item -or [string]::IsNullOrWhiteSpace($item.ExtId)) { throw 'A VM ExtId is required for every supplied VM.' } $sessionName = if ($PSBoundParameters.ContainsKey('PrismSession')) { $PrismSession } else { $item.PrismSession } $sessionConfig = Get-PrismSession $sessionName $RequestSplat = @{ PrismSession = $sessionConfig.Name Method = 'GET' Path = ('vmm/v{0}/ahv/stats/vms/{1}' -f $sessionConfig.ApiVersion, $item.ExtId) Query = $query } $response = Invoke-PrismRequest @RequestSplat [PrismVMStats]::new( $response.data, $item, $sessionConfig.Name, $StartTime, $EndTime, $SamplingInterval, $StatType, $Select ) } } } |