February 11th, 2014

DSC Diagnostics Module– Analyze DSC Logs instantly now!

PowerShell Team
PowerShell Team
Have you ever witnessed a DSC Configuration run where you had no idea about what it might have done behind the scenes? Well, then your worries end here! During any DSC Operation, the DSC engine writes into windows event logs, which are like bread crumbs that the engine leaves along the way during any execution. If you read the blog here about DSC troubleshooting, you could learn how to use the Get-WinEvent cmdlet to debug a DSC failure using event logs. However, something that really simplifies life is the new module that has been published in Wave 2 of the DSC Resource Kit , called xDscDiagnostics.

Introduction

xDscDiagnostics is a PowerShell module that consists of two simple operations that can help analyze DSC failures on your machine – GetxDscOperation 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>.

Get-xDscOperation

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.

image001

Figure 1 : Get-xDscOperation that shows a simple output for a list of operations executed in a machine

Parameters

  • Newest – Accepts an integer value to indicate the number of operations to be displayed. By default, it returns 10 newest operations. For instance,

Image 6355 image002 thumb 022E9926

Figure 2 : Get-xDscOperation can display the last 5 operations’ event logs

  • ComputerName – Parameter that accepts an array of strings, each containing the name of a computer from where you’d like to collect DSC event log data. By default, it collects data from the host machine. To enable this feature, you must run the following command in the remote machines, in elevated mode so that the will allow collection of events

    New-NetFirewallRule -Name “Service RemoteAdmin” -Action Allow      

  • Credential – Parameter that is of type PSCredential, which can help access to the computers specified in the ComputerName parameter.

Returned object

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:

  1. SequenceID: Specifies the incremental number assigned to the DSC operation based on time. For instance, the last executed operation would have SequenceID as 1, the second to last DSC operation would have the sequence ID of 2, and so on. This number is another identifier for each object in the returned array.
  1. TimeCreated: This is a DateTime value that indicates when the DSC operation had begun.
  1. ComputerName: The computer name from where the results are being aggregated.
  1. Result: This is a string value with value “Failure” or “Success” that indicates if that DSC operation had an error or not, respectively.
  1. AllEvents: This is an object that represents a collection of events emitted from that DSC operation.

For instance, if you’d like to aggregate results of the last operation from multiple computers, we have the following output:

image003

Figure 3 : Get-xDscOperation can display logs from many other computers at once.

Trace-xDscOperation

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.

Parameters

  • SequenceID: This is the integer value assigned to any operation, pertaining to a specific computer. By specifying a sequence ID of say, 4, the trace for the DSC operation that was 4th from the last will be output

image004

Figure 4: Trace-xDscOperation with sequence ID specified

  • JobID: This is the GUID value assigned by LCM xDscOperation to uniquely identify an operation. Hence, when a JobID is specified, the trace of the corresponding DSC operation is output.

image005

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

  • Computer Name and Credential: These parameters allow the trace to be collected from remote is necessary to run the command :

    New-NetFirewallRule -Name “Service RemoteAdmin” -Action Allow

image006

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.

Returned object

The cmdlet returns an array of objects, each of type Microsoft.PowerShell.xDscDiagnostics.TraceOutput. Each object in this array contains the following fields:

  1. ComputerName: The name of the computer from where the logs are being collected.
  1. EventType: This is an enumerator type field that contains information on the type of event. It could be any of the following :

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.

  1. TimeCreated : A DateTime value indicating when the event was logged by DSC
  1. Message: The message that was logged by DSC into the event logs.

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:

  1. JobID : The job ID (GUID format) specific to that DSC operation
  1. SequenceID: The SequenceID unique to that DSC operation in that computer.
  1. Event: This is the actual event logged by DSC, of type System.Diagnostics.Eventing.Reader.EventLogRecord. This can also the obtained from running the cmdlet Get-Winevent, as in the blog here. It contains more information such as the task, eventID, level, etc. of the event.

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:

(Trace-xDscOperation-SequenceID3).Event

That would display the same result as the Get-Winevent cmdlet, such as in the output below.

image007

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

Author

PowerShell Team
PowerShell Team

PowerShell is a task-based command-line shell and scripting language built on .NET. PowerShell helps system administrators and power-users rapidly automate tasks that manage operating systems (Linux, macOS, and Windows) and processes.

0 comments

Discussion are closed.