Correlating vSAN perf metrics from vSphere Web Client to both PowerCLI & vSAN Mgmt API

While going through the PowerCLI 6.5.1 release notes last week, in addition to the new Get-VsanView cmdlet which exposes the complete vSAN Management API through PowerCLI, I had learned that we had also released a new Get-VsanStat cmdlet. This new cmdlet allows customers to easily retrieve the various vSAN Performance Metrics provided by the vSAN Performance Service.

The really nice thing about vSAN Performance Service is that all vSAN stats are now available directly in the vSphere Web Client, where as before, this information was only available as part of the vSAN Observer which was a completely different interface. The other huge benefit to using the vSAN Performance Service is that it also stores the historical stats compared to the vSAN Observer which was primarily used for real time troubleshooting. As of vSAN 6.6, the vSAN Observer has been deprecated and will only be used by GSS in limited scenarios, everything you were able to do with the vSAN Observer is now possible with the vSAN Performance Service.

While trying out the new Get-VsanStat cmdlet, I had found it to be quite difficult to easily map the vSAN metrics I saw in the UI to the specific PowerCLI query required to extract that information. The documentation was also quite light and only included a single sample and although some of the metrics could easily be deduced, there were many others that I was just unsure of. I had also tried using the vSAN Management API directly, thinking that I might have more luck but it was also challenging to use for other reasons and I still ran into the same problem which was how do I easily map what I saw from the UI down to the API or even associating that back to PowerCLI.

After spending a few days with BOTH PowerCLI and the vSAN Management API and with a bit of frustration, I think I have finally figured out how to map what I saw from the UI back to the both CLI and API. This was not an easy task as and I had to cross-reference multiple datasources to build up this mapping and I thought I would put together a reference which outlines this mapping so that others would have to go through the same pain. IMHO, this should be a pretty straight forward task. In addition, I have also provided a PowerCLI sample for each of the metric types as well as the associated vSAN Management API mapping as those differ in name as well. This hopefully should make it easy for anyone to start using either of these interfaces for collecting vSAN metrics from an Automation standpoint. As part of this exercise, I also ran into a variety of bugs which I have already filed internally and all this information has been feedback to Engineering teams to hopefully improve both our CLI and API in future updates.

I have published the vSAN UI Metrics mapping on Github: https://github.com/lamw/mapping-vsan-perf-stats-to-powercli-api

Below is some additional context on how to use both the GetVsanStat cmdlet as well as the vSAN Management API for retrieving vSAN metrics.

Using PowerCLI Get-VsanStat cmdlet

Documentation: https://www.vmware.com/support/developer/PowerCLI/PowerCLI651/html/Get-VsanStat.html

The cmdlet accepts an Entity property which maps back to either a PowerCLI Cluster, VirtualDisk, VMHost, VirtualMachine, VsanDisk, VsanDiskGroup, VsanIscsiLun & VsanIscsiTarget object. Based on the Entity type, it supports a specific set of Metric Type as outlined in the table below, which are prefixes to the actual metric.

To give you an example, if we look at the performance view for a vSphere Cluster within the UI, we can see there are three sections: vSAN - Virtual Machine Consumption, vSAN - Backend and vSAN iSCSI. If we want to retrieve the "Read Throughput" for the first section, we need to provide the Cluster object as well as the full metric name which would start with VMConsumption. followed by the specific metric name, which in this case is called ReadThroughput.

The following PowerCLI snippet below return all metrics for a vSphere Cluster named VSAN-Cluster since we did not scope the start and end time.

$cluster = Get-Cluster -Name VSAN-Cluster
Get-VsanStat -Entity $cluster -Name VMConsumption.ReadThroughput

To retrieve other vSAN metric types, the formula is similiar, you just need to know the specific metric name which is the tricky part and hence the mapping that I have already put together. The -Name property can also accept wildcards, so you could also list all available metric types by doing something like:

Get-VsanStat -Entity $cluster -Name VMConsumption.*

For more details on retrieving particular vSAN metrics, please refer to the Github reference page which includes PowerCLI snippets for each of the vSAN metric types.

Using vSAN Management API

Documentation: http://pubs.vmware.com/vsphere-65/index.jsp?topic=%2Fcom.vmware.vsan.apiref.doc%2Fvim.cluster.VsanPerformanceManager.html

Behind the scenes, Get-VsanStat just uses the VsanPerformanceManager and specifically the VsanPerfQueryPerf() API method to retrieve the specific vSAN metrics. The API also accepts an Entity, but it must be composed by using the following format <entity-type>:<entity-uuid>.

The following vSAN Entity Types are supported:

• cache-disk
• capacity-disk
• cluster-domclient
• cluster-domcompmgr
• disk-group
• host-domclient
• host-domcompmgr
• virtual-disk
• virtual-machine
• vsan-host-net
• vsan-iscsi-host
• vsan-iscsi-lun
• vsan-iscsi-target
• vsan-pnic-net (currently not available in PowerCLI)
• vsan-vnic-net (currently not available in PowerCLI)
• vscsi (currently not available in PowerCLI)

Note: The entity types above should be fairly straight forward with the exception of domclient and domcompmgr which just maps to the the "VM Consumption" and "Backend" fields noted in the UI respectively.

One thing to be aware of is that all vSAN metrics are data driven and they can be derived by simply querying the vSAN APIs. To get a list of supported entity types, you can use the VsanPerfGetSupportedEntityTypes() API method and using this exact same method, you can also retrieve all the supported metrics for that given entity which is how the UI is rendered today. Currently, there are a total of 204 vSAN metrics that can be collected.

To demonstrate the how to retrieve the list of available entity types and metrics as well as actually querying for a particular vSAN statistic, I have create a PowerCLI script called VSANPerformance.ps1 which includes three functions: Get-VSANPerformanceEntityType, Get-VSANPerformanceEntityMetric and Get-VSANPerformanceStat which exercises these APIs.

To list all supported vSAN entity types, just run the following:

Get-VSANPerformanceEntityType

Here is an example of running the Get-VSANPerformanceEntityMetric function which will also auto-populate the supported entity type to list out all supported vSAN metrics for that given entity.

As you can see from the output below, these are the different metrics supported for vSAN's cache disk. The MetricID you see below maps to the vSAN Mgmt API name which is also shown on the Github page which I have already mapped out for you.

Here is an example of using the Get-VSANPerformanceStat function which accepts a StartTime, EndTime, Metric and the EntityID which must be crafted to meet the requirements (<entity-type>:<entity-uuid>) as outlined earlier. In this example, I am retrieving the iopsSched metric which is part of the vSAN Disk Group entity type.

Get-VSANPerformanceStat -Cluster VSAN-Cluster -StartTime "04/23/2017 4:00" -EndTime "04/23/2017 4:05" -EntityId "disk-group:5239bee8-9297-c091-df17-241a4c197f8d" -Metric iopsSched