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
            )
        }
    }
}