Automating the world one-liner at a time…
xDscDiagnostics is a PowerShell module that consists of two simple operations that can help analyze DSC failures on your machine – Get-xDscOperation and Trace-xDscOperation. These functions help in identifying all the events from past DSC operations run in your system, or any other computer (Note: you need a valid credential to access remote computers). Here, we use the term DSC Operation to define a single unique DSC execution from its start to its end. For instance, Test-DscConfiguration would be a separate DSC Operation. Similarly, every other cmdlet in DSC (such as Get-DscConfiguration, Start-DscConfiguration, etc.) could each be identified as a separate DSC operation.
The two cmdlets are explained here and in more detail below. Help regarding the cmdlets are available when you run get-help <cmdlet name>.
This cmdlet lets you find the results of the DSC operations that run on one or multiple computers, and returns an object that contains the collection of events produced by each DSC operation.
For instance, in the following output, we ran three commands, the first of which passed, and the others failed. These results are summarized in the output of Get-xDscOperation.
Figure 1 : Get-xDscOperation that shows a simple output for a list of operations executed in a machine
Figure 2 : Get-xDscOperation can display the last 5 operations’ event logs
The cmdlet returns an array of objects each of type Microsoft.PowerShell.xDscDiagnostics.GroupedEvents. Each object in this array pertains to a different DSC operation. The default display for this object has the following properties:
For instance, if you’d like to aggregate results of the last operation from multiple computers, we have the following output:
Figure 3 : Get-xDscOperation can display logs from many other computers at once.
This cmdlet returns an object containing a collection of events, their event types, and the messages output generated from a particular DSC operation. Typically, when you find a failure in any of the operations using Get-xDscOperation, you would want to trace that operation to find out which of the events caused a failure.
Figure 4: Trace-xDscOperation with sequence ID specified
Figure 5: Trace-xDscOperation taking JobID as a parameter – to output the same record as above – they just have two identifiers- job id and SequenceID
Figure 6: Trace-xDscOperation running on a different computer with the -ComputerName option
Note: Since Trace-xDscOperation would aggregate events from Analytic, Debug, and operational logs, it will prompt the user to enable these logs. If the logs are not enabled, an error message is displayed stating that these events cannot be read until it has been enabled. However, the trace from other logs are still displayed. This error can be ignored.
The cmdlet returns an array of objects, each of type Microsoft.PowerShell.xDscDiagnostics.TraceOutput. Each object in this array contains the following fields:
a. Operational : Indicates the event is from the operational log
b. Analytic : The event is from the analytic log
c. Debug : This would mean the event is from the debug log
d. Verbose: These events are output as verbose messages during execution. The verbose messages make it easy to identify the sequence of events that are published.
e. Error: These events are error events. Please note that by looking for the error events, we can immediately find the reason for failure most of the times.
There are some fields in this object that are not displayed by default, which can be used for more information about the event. These are:
Hence, we could obtain information on the events too, if we saved the output of Trace-xDscOperation into a variable. To display all the events for a particular DSC operation, the following command would suffice:
That would display the same result as the Get-Winevent cmdlet, such as in the output below.
Figure 7 : Output that is identical to a get-winevent output. These details can be extracted using the xDscDiagnostics module as well
Ideally, you would first want to use Get-xDscOperations to list out the last few DSC configuration runs on your machines. Following this, you can dissect any one single operation (using its sequenceID or JobID) with Trace-xDscOperation to find out what it did behind the scenes.
In summary, xDscDiagnostics is a simple tool to extract the relevant information from DSC logs so that the user can diagnose operations across multiple machines easily. We urge the users to use this more often to simplify their experience with DSC.
Inchara Shivalingaiah Software Developer Windows PowerShell Team
Very helpful, thank you!