Public/Invoke-VMMetricsCollection.ps1
|
function Invoke-VMMetricsCollection { <# .SYNOPSIS Discovers VMs in a subscription, pulls their platform metrics, and exports VMPerformance-compatible rows for FinOps rightsizing. .DESCRIPTION End-to-end orchestrator: 1. For each subscription (or the current context): discovers VMs via Get-AzVM. 2. For each VM pulls 'Percentage CPU' + 'Available Memory Bytes' and aggregates to monthly Min/Median/P95/P99/Max rows. 3. Writes ONE combined CSV (+ manifest) across all subscriptions and returns a run report. 4. Optionally uploads the CSV (+ manifest) to blob storage. Platform metrics retain only ~93 days; -WindowDays above that is capped with a warning. For longer history, run this on a schedule so rows accumulate, or stand up a diagnostic-setting export to Log Analytics (see README). .PARAMETER SubscriptionId One or more subscriptions to operate in. If omitted, the current Az context is used. All subscriptions are aggregated into a single output file. Pass (Get-AzSubscription).Id to sweep everything visible to the signed-in identity. .PARAMETER ResourceGroupName Optional resource-group filter. .PARAMETER VMName Optional VM-name filter (one or more exact names). .PARAMETER WindowDays Look-back window in days, default 90 (capped at 93 -- platform retention). .PARAMETER TimeGrain Aggregation grain, default 00:05:00 (PT5M). .PARAMETER OutputPath Directory to write the CSV + manifest into. Default: current directory. .PARAMETER Format 'CSV' (default) or 'Parquet'. .PARAMETER StorageAccountName Optional. When set, the CSV (+ manifest) is uploaded to this storage account under {Customer}/{date}/ after the local write. Requires -Customer. .PARAMETER ContainerName Blob container for the upload (default 'vmperformance'); created if missing. .PARAMETER Customer Real customer name; first blob path segment. Required when -StorageAccountName is set. .PARAMETER StorageAccountKey Account key for the upload. If omitted, -StorageAccountResourceGroup is used to fetch it. .PARAMETER StorageAccountResourceGroup Resource group of the storage account, used to fetch the key when none is supplied. .PARAMETER SasToken Container-scoped SAS token for the upload. When given, key auth is bypassed -- use this for cross-tenant uploads from a customer's Cloud Shell. .OUTPUTS [pscustomobject] run report: OutputFile, BlobUri, Subscriptions, VMsProcessed, VMsSkipped, RowCount, Skipped (per-VM reasons), Window. #> [CmdletBinding(SupportsShouldProcess)] [OutputType([pscustomobject])] param( [string[]] $SubscriptionId, [string] $ResourceGroupName, [string[]] $VMName, [ValidateRange(1, 93)] [int] $WindowDays = 90, [timespan] $TimeGrain = ([timespan]'00:05:00'), [string] $OutputPath = (Get-Location).Path, [ValidateSet('CSV', 'Parquet')] [string] $Format = 'CSV', # --- Optional blob upload (account-key or SAS auth) --- [string] $StorageAccountName, [string] $ContainerName = 'vmperformance', [string] $Customer, [string] $StorageAccountKey, [string] $StorageAccountResourceGroup, [string] $SasToken ) if ($StorageAccountName -and -not $Customer) { throw "-Customer is required when -StorageAccountName is set (it is the first blob path segment)." } # Resolve the subscription list. Default to the current context's subscription. if ($SubscriptionId) { $subList = @($SubscriptionId) } else { $cur = Get-AzContext -ErrorAction Stop if (-not $cur) { throw "No Azure context. Run Connect-AzAccount first." } $subList = @($cur.Subscription.Id) } $endTime = (Get-Date).ToUniversalTime() $startTime = $endTime.AddDays(-$WindowDays) $allRows = [System.Collections.Generic.List[object]]::new() $skipped = [System.Collections.Generic.List[object]]::new() $processed = 0 $subsDone = [System.Collections.Generic.List[string]]::new() # Remember the caller's context so a multi-subscription sweep doesn't leave them # parked on the last subscription. $originalSub = (Get-AzContext -ErrorAction SilentlyContinue).Subscription.Id $subTotal = $subList.Count $subIdx = 0 foreach ($sid in $subList) { $subIdx++ Write-Progress -Id 0 -Activity "FinOpsVMMetrics: collecting VM metrics" ` -Status "Subscription $subIdx/$subTotal ($sid) - $processed VM(s) so far" ` -PercentComplete ([int](($subIdx - 1) / [math]::Max($subTotal, 1) * 100)) try { Write-Verbose "Setting subscription context to $sid" Set-AzContext -Subscription $sid -ErrorAction Stop | Out-Null } catch { Write-Warning "Cannot select subscription ${sid}: $($_.Exception.Message)" $skipped.Add([pscustomobject]@{ Subscription = $sid; VM = '(subscription)'; Reason = $_.Exception.Message }) continue } $subsDone.Add($sid) $vmParams = @{ Status = $false } if ($ResourceGroupName) { $vmParams['ResourceGroupName'] = $ResourceGroupName } $vms = Get-AzVM @vmParams -ErrorAction Stop if ($VMName) { $vms = $vms | Where-Object { $_.Name -in $VMName } } if (-not $vms) { Write-Verbose "No VMs in subscription $sid for the given filters." continue } Write-Verbose "Subscription ${sid}: discovered $($vms.Count) VM(s)." $vmTotal = @($vms).Count $vmIdx = 0 foreach ($vm in $vms) { $vmIdx++ Write-Progress -Id 1 -ParentId 0 -Activity "Pulling platform metrics (sub $subIdx/$subTotal)" ` -Status "VM $vmIdx/${vmTotal}: $($vm.Name)" ` -PercentComplete ([int]($vmIdx / [math]::Max($vmTotal, 1) * 100)) try { $rows = Get-AzVMUtilization -VM $vm -StartTime $startTime -EndTime $endTime -TimeGrain $TimeGrain if ($rows -and $rows.Count -gt 0) { foreach ($r in $rows) { $allRows.Add($r) } $processed++ } else { $skipped.Add([pscustomobject]@{ Subscription = $sid; VM = $vm.Name; Reason = 'No metric data in window' }) } } catch { Write-Warning "Failed for $($vm.Name): $($_.Exception.Message)" $skipped.Add([pscustomobject]@{ Subscription = $sid; VM = $vm.Name; Reason = $_.Exception.Message }) } } Write-Progress -Id 1 -ParentId 0 -Activity "Pulling platform metrics" -Completed } Write-Progress -Id 0 -Activity "FinOpsVMMetrics: collecting VM metrics" -Completed # Restore the caller's original subscription context after the sweep. if ($originalSub -and $subsDone.Count -and $subsDone[-1] -ne $originalSub) { Set-AzContext -Subscription $originalSub -ErrorAction SilentlyContinue | Out-Null } if ($allRows.Count -eq 0) { Write-Warning "No VM metric data collected across $($subList.Count) subscription(s)." return [pscustomobject]@{ OutputFile = $null; BlobUri = $null; Subscriptions = $subsDone.ToArray() VMsProcessed = 0; VMsSkipped = $skipped.Count; RowCount = 0 Skipped = $skipped.ToArray(); Window = @{ Start = $startTime; End = $endTime; Days = $WindowDays } } } $stamp = $endTime.ToString('yyyy-MM-dd') $fileName = "VMPerformance-$stamp.$($Format.ToLowerInvariant())" $dataPath = Join-Path $OutputPath $fileName $manifest = @{ subscriptions = $subsDone.ToArray() windowStartUtc = $startTime.ToString('o') windowEndUtc = $endTime.ToString('o') windowDays = $WindowDays timeGrain = $TimeGrain.ToString() vmsProcessed = $processed vmsSkipped = $skipped.Count } if ($Customer) { $manifest['customer'] = $Customer } $written = $null if ($PSCmdlet.ShouldProcess($dataPath, "Export $($allRows.Count) rows")) { $written = Export-VMPerformanceData -Row $allRows.ToArray() -Path $dataPath -Format $Format -Manifest $manifest } # Optional upload to blob storage. $blobUri = $null if ($StorageAccountName -and $written) { $uploaded = Publish-VMPerformanceData -Path $written -Customer $Customer ` -StorageAccountName $StorageAccountName -ContainerName $ContainerName ` -StorageAccountKey $StorageAccountKey -StorageAccountResourceGroup $StorageAccountResourceGroup ` -SasToken $SasToken -Date $endTime.ToString('yyyy-MM-dd') $blobUri = $uploaded.BlobUri } [pscustomobject]@{ OutputFile = $written BlobUri = $blobUri Subscriptions = $subsDone.ToArray() VMsProcessed = $processed VMsSkipped = $skipped.Count RowCount = $allRows.Count Skipped = $skipped.ToArray() Window = @{ Start = $startTime; End = $endTime; Days = $WindowDays } } } |