Dealing with the inevitable events in life – reporting problems with PowerCLI

There are certain events in life that we all strive to avoid, yet they seem practically inevitable. Facing problems, when using some software product is one of those. And using PowerCLI and vSphere makes no exception. Occasionally, you will stumble upon a configuration, environment, or a PowerCLI/vSphere problem itself. This article shows how you can effectively report the problem to VMware. You will need this if cannot solve some problem yourself and need outside help or just want to inform VMware about the problem so they can fix it at some later point.

Reporting a problem with PowerCLI is easy. What you have to do is generate a diagnostic bundle with the Get-ErrorReport cmdlet and send it to VMware (or someone else with enough expertise on PowerCLI). There are 2 main scenarios for reporting the problem. The first is sending the bundle to VMware tech support (if you have a tech support account). The second is to post it in the PowerCLI community forum (http://communities.vmware.com/community/vmtn/vsphere/automationtools/powercli), attach the bundle to your post, and wait for someone to take a look at it. 

Here is the online documentation of the cmdlet: http://www.vmware.com/support/developer/PowerCLI/PowerCLI41/html/Get-ErrorReport.html

Get-ErrorReport has the following signature:


  • ProblemScript <ScriptBlock> 
  • ProblemScriptTimeoutSeconds <Double> 
  • ProblemDescription <String> 
  • Destination <DirectoryInfo>
  • DontIncludeServerLogs
  • <CommonParameters>

-ProblemScript is the Powershell script that reproduces the problem. Get-ErrorReport executes this script and captures all the actions caused by it, so someone at VMware can be able to analyze them later.

-ProblemScriptTimeoutSeconds is the time limit in which the script must finish execution. If the script exceeds this time limit it’s considered an error. This parameter is needed because Get-ErrorReport cannot know what time an arbitrary script should take, so it cannot know if the script has blocked or is still operating as expected.

-ProblemDescription is your description of the problem you observed. It should be as specific as possible. It should describe what the erroneous behavior is and what the expected behavior is.

-Destination is the directory where you want to save the diagnostic bundle. It’s a .zip file.

-DontIncludeServerLogs specifies if vCenter logs should be captured as well. If this switch parameter is not set, the cmdlet will extract the vCenter logs + the logs of all ESX servers managed by the vCenter. This is quite a slow operation and will increase the size of the diagnostic bundle dramatically. Including vCenter logs is useful if the problem you’re reporting is on the vCenter/ESX side. So it’s better to set this parameter if you report a PowerCLI-specific problem.

Let’s see some examples now. 

Example 1.

Let’s say you have a problem moving a virtual machine from one host to another. You can assign the script that moves the virtual machine to a variable and pass it to Get-ErrorReport.

Example 2.

Let’s say you want to connect to a server and retrieve the virtual machines but the operation hangs. Again, you can create the script that gets the virtual machines and pass it to Get-ErrorReport, specifying that you expect that the script should take no longer than 60 seconds to finish. Let’s assume you also want to include the vCenter logs in the report. 

Now you know how to record diagnostic information that will help someone with PowerCLI expertise understand your problem (and hopefully provide a solution). This someone will probably be VMware tech support (for those of you who have a tech support account) or the PowerCLI community forum where someone from VMware or the community can hopefully take a look at it.

Surely, some of you are curious about the contents of the diagnostic bundle. You can take a look yourself by unpacking the .zip file. Here is the list of the types of information the support bundle includes:

– The problem description that the user has supplied

– The PowerCLI version and configuration

– The script that reproduces the error

– The output objects of the script that reproduces the error

– A snapshot of the Powershell session state before and after the script execution. This snapshot includes all the Powershell variables and their values (the contents of the PSCmdlet.SessionState object). 

– All the Soap communication messages between PowerCLI and the vCenter/ESX it’s connected to;

– [Optionally] The vCenter logs.

PS. Any information that is previously known to be sensitive (like passwords used when authenticating to the server) is not included in the diagnostic bundle. But, note that if you have a clear-text password stored in a Powershell variable – it will go in the log, since there is no way for Get-ErrorReport to know that some arbitrary variable contains a password.

Best regards,

– Angel Evrov,  MTS at VMware


2 comments have been added so far

  1. I was wondering if you ever thought of changing
    the structure of your website? Its very well written;
    I love what youve got to say. But maybe you could a little more
    in the way of content so people could connect with it better.
    Youve got an awful lot of text for only having one or two images.

    Maybe you could space it out better?

Leave a Reply

Your email address will not be published. Required fields are marked *