Get your tasklog here!

It happens quite often that you launch a PowerCLI cmdlet or a call to a SDK method or a script and that you get a rather cryptic message that something went wrong. One source of information to find out what went wrong are the vCenter’s vpxd log or the ESX(i) server’s hostd log.

But these logs are flooded with messages and it’s often quite hard to find the messages that relate to your task.

When running against a vCenter Server you can set the vCenter’s Logging Options to “Verbose” or “Trivia“. That produces more information in the logs but that often also makes it harder to find/extract the information that belongs to your task. And who has never forgotten to set the the Logging Options back to their original state when done with debugging ?

To make life a bit easier, I wrote a function that automates the above steps. I expanded on a function that I was using privately, and made it more general. This function allows you to retrieve the log entries for one specific or all recent task. The function also allows you to pass a cmdlet, or even a complete script, run the script in an elevated Logging Options mode and returns the task-related log entries.

The script

Annotations

Line 1-2: The script requires PowerShell v2 and PowerCLI 4.1

Line 32: The default parameter set is the “TaskId” set. This definition is required to allow a call to the function without any parameters specified. In that case the function will assume that the TaskId parameter contains $null and the function will return the log entries for all tasks.

Line 34-35: The TaskId parameter set.

Line 36-39: The Script parameter set. This set allows the caller to pass a script block to the function and it optionally allows the caller to specify a new logging level for the execution of the script block.

Line 38: The ValidateSet defines the accepted values for the LogLevel parameter.

Line 43-58: An internal helper function. It changes the logging level. Note that this only valid when using a vCenter connection. The function returns the logging level before the change.

Line 60-100: An internal function that extracts the required information from a vpxd log (vCenter connection).

Line 64-66: RegEx expression to easily extract the required fields from the lines in the vpxd log.

Line 68-69: Use the current vpxd log.

Line 72: Find the start of each Task. Note that the script doesn’t look at the internal tasks created by vCenter.

Line 74-77: From the vpxd log entry we can construct a MoRef, that will allow the script to get the Managed Object against which the task was executed.

Line 84-95: This loop extract all the lines that are produced by the current task.

Line 102-140: An internal function that extracts the required information from a hostd log (ESX(i) connection)

Line 106-107: RegEx expression to easily extract the required fields from the lines in the vpxd log.

Line 113: Find the start of each Task. Note that the script doesn’t look at the internal tasks.

Line 117-119: The hostd log also contains entries for some internal tasks, like for example the autoPowerOn task after a system start, that we don’t return in the results. This test skips those entries.

Line 122: From the hostd log the script can’t find the Managed Object against which the task was executed.

Line 123-134: This loop extract all the lines that are produced by the current task.

Line 143-146: The function needs a connection.

Line 148: The Switch statement checks if the connection is to a vCenter or an ESX(i) server.

Line 150-159: When the connection is to a vCenter server, the script checks which parameter set is used in the call. If the call used the Script parameter set, the script optionally changes the logging level, executes the script block and then sets the logging level back to the original value. See PowerShell V2: ParameterSets for more info on parameter sets.

Line 155: The script gets the task-id for the script block that was invoked. This task-id will be used in the subsequent call to extract the log entries. Notice that the result from the Get-Task cmdlet is converted to an array. This to allow retrieving the last entry via the -1 index, even when there is only 1 task returned.

Line 154,161: The output from the executed script is captured and returned in the ScriptOutput property.

Samples

Get all the tasks

This is the simplest form to call the function.

The function returns an array of objects, one element for each task. This call is useful to get an overview of the tasks that are found in the log.

I mostly the following small script to display the results in screen.

When connected to a vCenter Server this produces output like this

When connected to an ESX server, the result looks like this. Notice that in this case we don’t have the entity against which the task was executed.

Get a specific task

You can find the task number from the Get-Task cmdlet or from the list we obtained in the previous section.

A typical call, when connected to the vCenter, looks like this

And when you want to retrieve the log from an ESX server.

Run a task

The previous sections showed how you can trieve one or more of the tasks that ran on your vCenter or ESX server. But the function also allows you to run a script for you and optionally set the logging level on a vCenter server to a more verbose level.

You pass a script block to the function like this.

Note that we redirect the output of the cmdlets in the script block to $null. If we didn’t do that, the cmdlet’s output would also appear in the $log variable.

The result looks the same as what we got with the previous calls.

But we can also ask for more information with the -LogLevel parameter.

Now we see a lot more.

This kind of task log not only gives you an interesting way of finding problems in your code, but it also shows you that there is a lot going on behind the scene, that you normally wouldn’t see.

Enjoy !