The DRS and SDRS functionality will use vMotion and svMotion to better use the available resources.

And you as a vSphere administrator can use it to facilitate your work. Just think of how easy patching or datastorecluster maintenance becomes with the help of these two features.
But as an administrator you want to be able to report on what vMotion and svMotion have been doing over a specific time interval in your vSphere environment.

In the past I already provided a vMotion reporting tool in Events – Part 8 – vMotion history, but now it was time to provide a universal (s)vMotion reporting feature.

Update October 29th 2013: added additional parameters to the Get-VIEventPlus function

• User: one or more users for which to return the events
• System: a switch to return all system user events
• ScheduledTask: return all events for a specific Scheduled Task

Update February 10th 2014: it’s always nice to see another implementation based on one of your scripts. The Opvizor solution will soon contain this function, see Dennis Zimmer‘s post called Storage vMotion Activities Report !

The Script

function Get-VIEventPlus {
<#   
.SYNOPSIS  Returns vSphere events    
.DESCRIPTION The function will return vSphere events. With
    the available parameters, the execution time can be
   improved, compered to the original Get-VIEvent cmdlet. 
.NOTES  Author:  Luc Dekens   
.PARAMETER Entity
   When specified the function returns events for the
   specific vSphere entity. By default events for all
   vSphere entities are returned. 
.PARAMETER EventType
   This parameter limits the returned events to those
   specified on this parameter. 
.PARAMETER Start
   The start date of the events to retrieve 
.PARAMETER Finish
   The end date of the events to retrieve. 
.PARAMETER Recurse
   A switch indicating if the events for the children of
   the Entity will also be returned 
.PARAMETER User
   The list of usernames for which events will be returned 
.PARAMETER System
   A switch that allows the selection of all system events. 
.PARAMETER ScheduledTask
   The name of a scheduled task for which the events
   will be returned 
.PARAMETER FullMessage
   A switch indicating if the full message shall be compiled.
   This switch can improve the execution speed if the full
   message is not needed.   
.EXAMPLE
   PS> Get-VIEventPlus -Entity $vm
.EXAMPLE
   PS> Get-VIEventPlus -Entity $cluster -Recurse:$true
#>

  param(
    [VMware.VimAutomation.ViCore.Impl.V1.Inventory.InventoryItemImpl[]]$Entity,
    [string[]]$EventType,
    [DateTime]$Start,
    [DateTime]$Finish = (Get-Date),
    [switch]$Recurse,
    [string[]]$User,
    [Switch]$System,
    [string]$ScheduledTask,
    [switch]$FullMessage = $false
  )

  process {
    $eventnumber = 100
    $events = @()
    $eventMgr = Get-View EventManager
    $eventFilter = New-Object VMware.Vim.EventFilterSpec
    $eventFilter.disableFullMessage = ! $FullMessage
    $eventFilter.entity = New-Object VMware.Vim.EventFilterSpecByEntity
    $eventFilter.entity.recursion = &{if($Recurse){"all"}else{"self"}}
    $eventFilter.eventTypeId = $EventType
    if($Start -or $Finish){
      $eventFilter.time = New-Object VMware.Vim.EventFilterSpecByTime
    if($Start){
        $eventFilter.time.beginTime = $Start
    }
    if($Finish){
        $eventFilter.time.endTime = $Finish
    }
    }
  if($User -or $System){
    $eventFilter.UserName = New-Object VMware.Vim.EventFilterSpecByUsername
    if($User){
      $eventFilter.UserName.userList = $User
    }
    if($System){
      $eventFilter.UserName.systemUser = $System
    }
  }
  if($ScheduledTask){
    $si = Get-View ServiceInstance
    $schTskMgr = Get-View $si.Content.ScheduledTaskManager
    $eventFilter.ScheduledTask = Get-View $schTskMgr.ScheduledTask |
      where {$_.Info.Name -match $ScheduledTask} |
      Select -First 1 |
      Select -ExpandProperty MoRef
  }
  if(!$Entity){
    $Entity = @(Get-Folder -Name Datacenters)
  }
  $entity | %{
      $eventFilter.entity.entity = $_.ExtensionData.MoRef
      $eventCollector = Get-View ($eventMgr.CreateCollectorForEvents($eventFilter))
      $eventsBuffer = $eventCollector.ReadNextEvents($eventnumber)
      while($eventsBuffer){
        $events += $eventsBuffer
        $eventsBuffer = $eventCollector.ReadNextEvents($eventnumber)
      }
      $eventCollector.DestroyCollector()
    }
    $events
  }
}

function Get-MotionHistory {
<#   
.SYNOPSIS  Returns the vMotion/svMotion history    
.DESCRIPTION The function will return information on all
   the vMotions and svMotions that occurred over a specific
    interval for a defined number of virtual machines 
.NOTES  Author:  Luc Dekens   
.PARAMETER Entity
   The vSphere entity. This can be one more virtual machines,
   or it can be a vSphere container. If the parameter is a
    container, the function will return the history for all the
   virtual machines in that container. 
.PARAMETER Days
   An integer that indicates over how many days in the past
   the function should report on. 
.PARAMETER Hours
   An integer that indicates over how many hours in the past
   the function should report on. 
.PARAMETER Minutes
   An integer that indicates over how many minutes in the past
   the function should report on. 
.PARAMETER Sort
   An switch that indicates if the results should be returned
   in chronological order. 
.EXAMPLE
   PS> Get-MotionHistory -Entity $vm -Days 1
.EXAMPLE
   PS> Get-MotionHistory -Entity $cluster -Sort:$false
.EXAMPLE
   PS> Get-Datacenter -Name $dcName |
   >> Get-MotionHistory -Days 7 -Sort:$false
#>

  param(
    [CmdletBinding(DefaultParameterSetName="Days")]
    [Parameter(Mandatory=$true,ValueFromPipeline=$true)]
    [VMware.VimAutomation.ViCore.Impl.V1.Inventory.InventoryItemImpl[]]$Entity,
    [Parameter(ParameterSetName='Days')]
    [int]$Days = 1,
    [Parameter(ParameterSetName='Hours')]
    [int]$Hours,
    [Parameter(ParameterSetName='Minutes')]
    [int]$Minutes,
    [switch]$Recurse = $false,
    [switch]$Sort = $true
  )

  begin{
    $history = @()
    switch($psCmdlet.ParameterSetName){
      'Days' {
        $start = (Get-Date).AddDays(- $Days)
      }
      'Hours' {
        $start = (Get-Date).AddHours(- $Hours)
      }
      'Minutes' {
        $start = (Get-Date).AddMinutes(- $Minutes)
      }
    }
    $eventTypes = "DrsVmMigratedEvent","VmMigratedEvent"
  }

  process{
    $history += Get-VIEventPlus -Entity $entity -Start $start -EventType $eventTypes -Recurse:$Recurse |
    Select CreatedTime,
    @{N="Type";E={
        if($_.SourceDatastore.Name -eq $_.Ds.Name){"vMotion"}else{"svMotion"}}},
    @{N="UserName";E={if($_.UserName){$_.UserName}else{"System"}}},
    @{N="VM";E={$_.VM.Name}},
    @{N="SrcVMHost";E={$_.SourceHost.Name.Split('.')[0]}},
    @{N="TgtVMHost";E={if($_.Host.Name -ne $_.SourceHost.Name){$_.Host.Name.Split('.')[0]}}},
    @{N="SrcDatastore";E={$_.SourceDatastore.Name}},
    @{N="TgtDatastore";E={if($_.Ds.Name -ne $_.SourceDatastore.Name){$_.Ds.Name}}}
  }

  end{
    if($Sort){
      $history | Sort-Object -Property CreatedTime
    }
    else{
      $history
    }
  }
}

Annotations

Line 1-101: The Get-VIEventPlus function. This function adds some improvements, at least for me, to the current Get-VIEvent cmdlet. It allows you to specify which specific events to return and it allows you to use a ‘recursive’ search for events starting from the ‘Entity’.

Line 52: The function uses the EventHistoryCollector. Access to the found events is through a ‘sliding‘ window. This variable defines the size of that sliding window. From my average use, I came to the conclusion that 100 events is a workable size for this window. But your mileage may vary.

Line 55-85: These lines are the hearth of the function. In here the ‘filter‘ is specified for the events to search for. See the EventFilterSpec objects for the details.

Line 89: The EventFilterSpec can hold only one MoRef. So if multiple entities are passed, they will have be handled one by one. This makes a big difference in execution time when you do not select the value for the Entity parameter correctly. See later.

Line 93-96: This While construction reads all the found events.

Line 103-187: The Get-MotionHistory function. This function uses the Get-VIEventPlus function to retrieve specific events. The returned events are used to report on all the vMotions and svMotions.

Line 140-145: The function has 3 parametersets, each indicating a specific type of interval (Days/Hours/Minutes). The default is 1 day back in time.

Line 151: Since the function supports pipeline input, the history records it creates must be stored in an array until all pipeline objects have been handled.

Line 152-162: The 3 parametersets are handled with a Switch statement, and the Start parameter for the Get-VIEvent cmdlet is calculated accordingly.

Line 163: For the (s)vMotion history the function only needs these 2 types of events.

Line 171: The vMotion and or svMotion actions can be user invoked or system invoked (DRS/SDRS)

Line 173-176: Depending on the type of ‘motion‘, the functions will include a target host or target datastore.

Sample Usage

The Get-MotionHistory function is quite simple to use as the following example will show.

Get-MotionHistory -Entity (Get-VM VM*) -Days 1 |
Export-Csv C:\motion-report1.csv -NoTypeINformation -UseCulture

The content of the produced CSV looks like this.

When you use the Get-MotionHistory take care of what you pass on the Entity parameter !

The following calls will produce the same result.

Get-Cluster -Name Cluster1 | Get-MotionHistory -Hours 4 -Recurse:$true

as this one

Get-Cluster -Name Cluster1 | Get-VM | Get-MotionHistory -Hours 4

But the difference between these two calls of the function is the execution time. The second method was 80 times slower compared to the first method in my test environment, where there are about 100 VMs in that cluster.

The reason is that the Get-VIEventPlus function has to call the EventHistoryCollector for each VM in the 2nd method, while it is only called once in the 1st method !

That is also the main reason I introduced the Recurse parameter on the Get-VIEventPlus function. A feature that is sadly missing on the Get-VIEvent cmdlet

If you want to have a report for a specific set of VMs in a cluster, it is most probably better to call the Get-MotionHistory function for the complete cluster with the Recurse switch set to $true, and filter out the required VMs from the produced result. Something like this for example

Get-Cluster -Name Cluster1 | Get-MotionHistory -Hours 4 -Recurse:$true |
Where {$_.VM -like "VM*"}

Enjoy !

A single vMotion can now scale over multiple NICs. This feature can use a regular vSwitch or distributed vSwitch.On YouTube there are 2 videos, uploaded by VMwareKB, that show how to configure such a vMotion enabled multi-NIC vSwitch, regular and distributed.

Very useful videos, but as you can imagine, I wanted to automate this. No GUI clicking for me 

The script

function Set-vMotionMultiNic{
<#
.SYNOPSIS  Configure multi-NIC vMotion
.DESCRIPTION The function will configure multi-NIC vMotion
  enabled portgroups on a regular vSwitch 
.NOTES  Author:  Luc Dekens
.PARAMETER VMHost
  The ESXi host where the vMotion enabled portgroups shall be
  configured.
  The parameter accepts a string or the object returned by the
  Get-VMHost cmdlet.
.PARAMETER VirtualSwitch
  The virtual switch on which the vMotion enabled portgroups
  shall be configured.
  The parameter accepts a string or the object returned by the
  Get-VirtualSwitch cmdlet.
.PARAMETER pNic
  An array with the vnics that shall be used to configure the
  portgroups. Depending on the number of provided vnics, the
  function will create the optimal number of portgroups.
  The arrays on pNic, IPaddress and SubnetMask shall have the
  same number of elements.
.PARAMETER IpAddress
  An array with the IP addresses that shall be used on the
  portgroups
.PARAMETER SubnetMask
  An array with the subnetmasks.
.EXAMPLE
  PS> Set-vMotionMultiNic -VMHost MyESX -VSwitch MyvSw `
  PS>>   -pNic "vmnic2","vmnic3","vmnic4" `
  PS>>   -IpAddress "192.168.1.1","192.168.1.2","192.168.1.3" `
  PS>>   -SubnetMask (,"255.255.255.0" * 3)
#>
  param(
    [psobject]$VMHost,
    [psobject]$VirtualSwitch,
    [string[]]$pNic,
    [string[]]$IpAddress,
    [string[]]$SubnetMask
  )56
  
  if($VMHost.getType().Name -eq "string"){
    $VMHost = Get-VMHost -Name $VMHost
  }
  if($VMHost.ApiVersion.Split('.')[0] -lt 5){
    Write-Warning "MultiNic for vMotion requires at least ESXi 5.0"
    exit
  }

  if($VirtualSwitch.getType().Name -eq "string"){
    $VirtualSwitch = $VMHost | Get-VirtualSwitch -Name $VirtualSwitch
  }
  $indices = 0..($pNic.Count - 1)
  foreach($i in $indices){
    $pg = New-VirtualPortGroup -Name ("vMotion-{0:d2}" -f ($i + 1)) -VirtualSwitch $VirtualSwitch
    New-VMHostNetworkAdapter -VMHost $VMHost -VirtualSwitch $VirtualSwitch -PortGroup $pg -IP $IpAddress[$i] -SubnetMask $SubnetMask[$i] -VMotionEnabled:$true | Out-Null
    Get-NicTeamingPolicy -VirtualPortGroup $pg | 
    Set-NicTeamingPolicy -MakeNicActive $pNic[$i] -MakeNicStandby $pNic[($indices | where {$_ -ne $i})] |Out-Null
  }
}

Annotations

Line 42-44: A simple Object By Name (OBN) implementation for the ESXi host

Line 45-48: A check if we are configuring this for at least a vSphere 5 server

Line 50-52: A simple Object By Name (OBN) implementation for the regular vSwitch

Line 53: When the function is called with ‘n’ vnics, it will have to create ‘n’ portgroups. This calculation creates the list of suffixes that will be used on the portgroup names.

Line 55: The creation of the portgroup. Note how the function adds a 2 digit suffix with the -format operator to the basename (‘vMotion’)

Line 56: Set the IP address and subnetmask

Line 57-58: The Teaming is configured in the same way the VMwareKB video demonstrates.

Sample use

To demonstrate the function, I will use a simple configuration. We have 1 regular vSwitch that has 3 vnics connected to it.

We call the function

$IP = "192.168.0.210","192.168.0.211","192.168.0.212"
$MASK = "255.255.255.0","255.255.255.0","255.255.255.0"
$NIC = "vmnic1","vmnic2","vmnic3"

Set-vMotionMultiNic -VMHost 192.168.0.107 -VirtualSwitch vSwitch1 -pNic $NIC -IPAddress $IP -SubnetMask $MASK

The function creates the vMotion portgroups (in the same way as the VMwareKB video shows).

And each of these vMotion enabled portgroups is configured similar to the method shown in the video.

In a following post I will show how this can be done for a dvSwitch.

Enjoy !

Since vSphere doesn’t maintain any historical data with the guests themselves, we have to fall back on the Tasks and Events to create such a report. The basic algorithm to query the tasks, and their related events, is already published in Events – Part 3 : Auditing VM device changes. But to get a historical record of the servers where your guests have been hosted requires a bit more logic in the script.

The script

There are 2 distinct parts in the script.

1. Get all the vMotion tasks. A vMotion can be user– or DRS-initiated. These produce different tasks.
2. Compile the final report by only looking at the selected guests

$hours = 24 # Number of hours back
$start = (Get-Date).AddHours(-$hours)
$tasknumber = 999 # Windowsize for task collector
$eventnumber = 100 # Windowsize for event collector
$tgtTaskDescriptions = "VirtualMachine.migrate","Drm.ExecuteVMotionLRO"
$migrations = @()
$report = @()

# Get the guest for which we want the report
$vmHash = @{}
Get-Datacenter -Name "MyDC" | Get-VM | %{
	$vmHash[$_.Name] = $_.Host
}

# Retrieve the vMotion tasks and the corresponding events
$taskMgr = Get-View TaskManager
$eventMgr = Get-View eventManager

$tFilter = New-Object VMware.Vim.TaskFilterSpec
$tFilter.Time = New-Object VMware.Vim.TaskFilterSpecByTime
$tFilter.Time.beginTime = $start
$tFilter.Time.timeType = "startedTime"

$tCollector = Get-View ($taskMgr.CreateCollectorForTasks($tFilter))

$dummy = $tCollector.RewindCollector
$tasks = $tCollector.ReadNextTasks($tasknumber)

while($tasks){
	$tasks | where {$tgtTaskDescriptions -contains $_.DescriptionId} | % {
		$task = $_
		$eFilter = New-Object VMware.Vim.EventFilterSpec
		$eFilter.eventChainId = $task.EventChainId

		$eCollector = Get-View ($eventMgr.CreateCollectorForEvents($eFilter))
		$events = $eCollector.ReadNextEvents($eventnumber)
		while($events){
			$events | % {
				$event = $_
				switch($event.GetType().Name){
					"VmBeingHotMigratedEvent" {
						$migrations += New-Object PSObject -Property @{
							VMname = $task.EntityName
							Source = $event.Host.Name
							Destination = $event.DestHost.Name
							Start = $task.StartTime
							Finish = $task.CompleteTime
							Result = $task.State
							User = $task.Reason.UserName
							DRS = &{if($task.DescriptionId -like "Drm.*"){$true}else{$false}}
						}
					}
					Default {}
				}
			}
			$events = $eCollector.ReadNextEvents($eventnumber)
		}
		$ecollection = $eCollector.ReadNextEvents($eventnumber)
# By default 32 event collectors are allowed. Destroy this event collector.
		$eCollector.DestroyCollector()
	}
	$tasks = $tCollector.ReadNextTasks($tasknumber)
}

# By default 32 task collectors are allowed. Destroy this task collector.
$tCollector.DestroyCollector()

# Handle the guests that have been vMotioned
$grouped = $migrations | Group-Object -Property VMname
$grouped | Sort-Object -Property Count -Descending | where{$vmHash.ContainsKey($_.Name)} | %{
	$i = 1
	$row = New-Object PSObject
	Add-Member -InputObject $row -Name VM -Value $_.Name -MemberType NoteProperty
	$_.Group | Sort-Object -Property Finish | %{
# The original location of the guest
		if($i -eq 1){
			Add-Member -InputObject $row -Name ("Time" + $i) -Value $start -MemberType NoteProperty
			Add-Member -InputObject $row -Name ("Host" + $i) -Value $_.Source -MemberType NoteProperty
			$i++
		}
# All the vMotion destinations
		Add-Member -InputObject $row -Name ("Time" + $i) -Value $_.Finish -MemberType NoteProperty
		Add-Member -InputObject $row -Name ("Host" + $i) -Value $_.Destination -MemberType NoteProperty
		Add-Member -InputObject $row -Name ("DRS" + $i) -Value $_.DRS -MemberType NoteProperty
		Add-Member -InputObject $row -Name ("User" + $i) -Value $_.User -MemberType NoteProperty
		$i++
	}
	$report += $row
	$vmHash.Remove($_.Name)
}

# Add remaining guests to report
$vmHash.GetEnumerator() | %{
	$row = New-Object PSObject
	Add-Member -InputObject $row -Name VM -Value $_.Name -MemberType NoteProperty
	Add-Member -InputObject $row -Name Time1 -Value $start -MemberType NoteProperty
	Add-Member -InputObject $row -Name Host1 -Value $_.Value -MemberType NoteProperty
	Add-Member -InputObject $row -Name DRS1 -Value $false -MemberType NoteProperty
	$report += $row
}

$report | Export-Csv "C:\vMotion-history.csv" -NoTypeInformation -UseCulture

Annotations

Line 1-2: Specify how far back you want to report on through the $start variable

Line 5: The vMotion tasks can be triggered by a user or by DRS.

Line 10-13: We collect all the guests on which we want to report. This can be changed at will, just make sure the hash table $vmHash is populated.

Line 15-66: This is the same logic as was used in Events – Part 3 : Auditing VM device changes

Line 69-70: We group the discovered vMotions per guest and then we sort the groups descending on the Count property. This is required because we will later use the Export-Csv cmdlet and if the array holds rows of varying length, the longest row should be first.

Line 76-80: For the vMotioned guest we first make an entry with the original location at time $start.

Line 82-86: For each vMotion we add the same properties Time, Host, DRS and User, but each time with an incremented suffix number.

Line 89: A guest that was vMotioned is removed from hash table to avoid duplicate entries later one.

Line 93-100: The guest that were not vMotioned during the reporting interval are added to the report.

Sample output

The script produces a CSV file that contains quite a bit of information.

A guest that was not vMotioned during the reporting interval will only have a Time1 and Host1 column.

Guests that were vMotioned will have additional Timen and Hostn columns. Notice the DRSn column which indicates if a vMotion was triggered by DRS or by a user.  The Usern column will display the username if it was a user-invoked vMotion.