Quick Tip - Retrieving vSphere Distributed Switch (VDS) DVPort ID & Stats using PowerCLI

I have seen several variations of this question get asked internally on how how to retrieve the DVPort ID and/or Stats on a vSphere Distributed Switch (VDS). Usually the question is prefaced with an example output from an ESXi host like the one show below using a classic CLI called esxcfg-vswitch. As you can see, there are a number of DVPort IDs which are either mapped to a physical NIC on the ESXi host or to a specific VM and its network adapter, if there is more than one.

My usual response for these sort of questions is that yes, it can be programmatically and automatically retrieved without going directly to an ESXi host. The answer is by using the vSphere API and specifically the set of methods provided by the VirtualDistributedSwitch managed object, which will allow users to retrieve all things related to the VDS.

Note: Although PowerCLI does provide some higher level cmdlets for managing VDS and Distributed Virtual Portgroups (DVPG), not everything that is available in VDS API is available through these higher level cmdlets, but that does not mean you can not use PowerCLI to easily retrieve all this additional information.

Ports

To retrieve the basic DVPort ID and Client information, you can use the FetchDVPorts() method which is available when getting a reference to a specific VDS. In the example PowerCLI snippet below, I am fetching all ports by providing the $null parameter, which does not filter out specific ports that I am interested in. After that, the key and state.runtimeinfo.linkpeer property contains the two pieces of information that allows us to build an output similar to that shown from esxcfg-vswitch. There is a ton of rich information for each DVPort, I highly recommend taking a look at the vSphere API documentation for DVPort to explore what else can be retrieved.

$vds = Get-VDSwitch -Name VDS

$ports = $vds.ExtensionData.FetchDVPorts($null)

$results = @()
foreach ($port in $ports | Sort-Object -Property key) {
    $tmp = [pscustomobject] @{
        DVPortID = $port.key;
        Client = $port.state.RuntimeInfo.LinkPeer
    }
    $results += $tmp
}

$results

Here is an example screenshot of the output that is expected:

Stats

For each DVPort, there are also a number of statistics that can be retrieved by looking at the state.stats property. Building on our example from above, I have decided to include two additional fields with the following metrics: BytesInUnicast and PacketsInBroadcast. To demonstrate this, I have updated the PowerCLI example from above to include these additional metrics as part of the output.

$vds = Get-VDSwitch -Name VDS

$ports = $vds.ExtensionData.FetchDVPorts($null)
foreach ($port in $ports | Sort-Object -Property key) {
    $tmp = [pscustomobject] @{
        DVPortID = $port.key;
        Client = $port.State.RuntimeInfo.LinkPeer
        BytesInUnicast = $port.state.stats.BytesInUnicast
        BytesOutUnicast = $port.state.stats.PacketsInBroadcast
    }
    $results += $tmp
}

$results

Here is an example screenshot of the output that is expected:

Lastly, all of this information can also be viewed using the vSphere UI under the Ports tab and this should give you an idea of all the different pieces of information that can be retrieved by using the vSphere API