{"id":20156257,"url":"https://github.com/dsccommunity/xdscdiagnostics","last_synced_at":"2026-03-05T21:32:12.065Z","repository":{"id":30468245,"uuid":"34022231","full_name":"dsccommunity/xDscDiagnostics","owner":"dsccommunity","description":"This module contains cmdlets for analyzing DSC event logs.","archived":false,"fork":false,"pushed_at":"2020-05-01T13:39:07.000Z","size":150,"stargazers_count":33,"open_issues_count":11,"forks_count":12,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-24T00:16:50.816Z","etag":null,"topics":["diagnostics","dsc","dsc-events","dsc-operation"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dsccommunity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-15T22:42:59.000Z","updated_at":"2024-11-15T16:21:19.000Z","dependencies_parsed_at":"2022-07-12T16:09:31.158Z","dependency_job_id":null,"html_url":"https://github.com/dsccommunity/xDscDiagnostics","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsccommunity%2FxDscDiagnostics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsccommunity%2FxDscDiagnostics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsccommunity%2FxDscDiagnostics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsccommunity%2FxDscDiagnostics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dsccommunity","download_url":"https://codeload.github.com/dsccommunity/xDscDiagnostics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248120939,"owners_count":21051053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diagnostics","dsc","dsc-events","dsc-operation"],"created_at":"2024-11-13T23:38:12.333Z","updated_at":"2026-03-05T21:32:12.011Z","avatar_url":"https://github.com/dsccommunity.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xDscDiagnostics\r\n\r\n[![Build Status](https://dev.azure.com/dsccommunity/xDscDiagnostics/_apis/build/status/dsccommunity.xDscDiagnostics?branchName=master)](https://dev.azure.com/dsccommunity/xDscDiagnostics/_build/latest?definitionId=33\u0026branchName=master)\r\n![Azure DevOps coverage (branch)](https://img.shields.io/azure-devops/coverage/dsccommunity/xDscDiagnostics/33/master)\r\n[![Azure DevOps tests](https://img.shields.io/azure-devops/tests/dsccommunity/xDscDiagnostics/33/master)](https://dsccommunity.visualstudio.com/xDscDiagnostics/_test/analytics?definitionId=33\u0026contextType=build)\r\n[![PowerShell Gallery (with prereleases)](https://img.shields.io/powershellgallery/vpre/xDscDiagnostics?label=xDscDiagnostics%20Preview)](https://www.powershellgallery.com/packages/xDscDiagnostics/)\r\n[![PowerShell Gallery](https://img.shields.io/powershellgallery/v/xDscDiagnostics?label=xDscDiagnostics)](https://www.powershellgallery.com/packages/xDscDiagnostics/)\r\n\r\nThis module contains cmdlets for analyzing DSC event logs and identifying the\r\ncauses of any failure in a DSC operation.\r\n\r\n## Code of Conduct\r\n\r\nThis project has adopted this [Code of Conduct](CODE_OF_CONDUCT.md).\r\n\r\n## Releases\r\n\r\nFor each merge to the branch `master` a preview release will be\r\ndeployed to [PowerShell Gallery](https://www.powershellgallery.com/).\r\nPeriodically a release version tag will be pushed which will deploy a\r\nfull release to [PowerShell Gallery](https://www.powershellgallery.com/).\r\n\r\n## Contributing\r\n\r\nPlease check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing).\r\n\r\n## Description\r\n\r\nThe **xDscDiagnostics** module exposes cmdlets that aid in diagnosing DSC errors.\r\n\r\nHere, we use the term DSC operation to indicate the execution of any DSC cmdlet\r\nfrom its start to its end. For instance, Start-DscConfiguration and Test-DscConfiguration\r\nwould form two separate DSC operations. The cmdlets also let you diagnose\r\noperations run on other computers. More details about their usage is given\r\nbelow in the Details section.\r\n\r\n## Install the module\r\n\r\n### Install the latest released version\r\n\r\nFor Windows PowerShell run the following steps.\r\n\r\n```powershell\r\nInstall-Module xDscDiagnostics -Scope 'CurrentUser'\r\n```\r\n\r\n### Install the latest released preview version\r\n\r\nFor Windows PowerShell run the following steps.\r\n\r\n```powershell\r\nInstall-Module xDscDiagnostics -Scope 'CurrentUser' -AllowPrerelease\r\n```\r\n\r\n## Cmdlets\r\n\r\n### Get-xDscOperation\r\n\r\nThis cmdlet lists statuses of the last few run DSC operations. It returns an\r\nobject that has information about the time that operation was created, whether\r\nthe operation was successful or not, a handle to all the events generated by\r\nthat operation, and the unique job identifier for that operation.\r\n\r\n\u003eFor more information read the article\r\n\u003e[Using Event Logs to Diagnose Errors in Desired State Configuration](https://devblogs.microsoft.com/powershell/using-event-logs-to-diagnose-errors-in-desired-state-configuration)\r\n\u003eto understand the role of the job ID in DSC events.\r\n\r\n#### Parameters\r\n\r\n- **Newest**: Number of past operations you want to output. By default,\r\n  it will display details of the last 10 operations\r\n- **Credential**: Credentials required to access the computer given in\r\n  the `ComputerName` property\r\n- **ComputerName**: Name of the computer from which you'd like to collect\r\n  the event diagnostic details. The input can be an array of strings. You\r\n  would need to execute the following command on the remote computer in\r\n  order to execute this operation on it.\r\n  ```powershell\r\n  New-NetFirewallRule -Name \"Service RemoteAdmin\" -Action Allow\r\n  ```\r\n\r\n### Trace-xDscOperation\r\n\r\nOnce we run Get-xDscOperation, we can see which of the operations were a\r\nfailure/success. Also, we can note a correlation between SequenceID and\r\nJobID for each operation. Trace-xDscOperation takes either of these values\r\nas parameters and gives you a readable list of events generated by their\r\nrespective DSC operation. By default, Trace-xDscOperation will list all\r\nthe events generated by the most recent DSC operation. This cmdlet returns\r\nan object that contains properties such as event type, event message, and\r\ntime of event creation.\r\n\r\n#### Parameters\r\n\r\n- **SequenceID**: This is a field present in the object returned from\r\n  running Get-xDscOperation. It identifies an operation run in the computer.\r\n  By specifying the sequence ID, all the events pertaining to the corresponding\r\n  operation are returned.\r\n- **JobID**: This is a GUID that is a prefix to all the events published\r\n  by DSC, which uniquely identifies each operation. It is also a field\r\n  present in the object returned from running Get-xDscOperation cmdlet.\r\n  By specifying a JobID, this cmdlet will extract and display all events\r\n  pertaining to the corresponding DSC operation.\r\n- **Credential**: Credentials required to access the computer given in the\r\n  `ComputerName` property.\r\n- **ComputerName**: Name of the computer from which you'd like to collect\r\n  the event diagnostic details. The input can be an array of strings.\r\n  You would need to execute the following command on the remote computer(s)\r\n  in order to execute this operations on it.\r\n  ```powershell\r\n  New-NetFirewallRule -Name \"Service RemoteAdmin\" -Action Allow\r\n  ```\r\n\r\n### Update-xDscEventLogStatus\r\n\r\nThis cmdlet helps us enable or disable any of the DSC event logs. When the\r\ncmdlets Get-xDscOperation and Set-xDscOperation are used, they will output\r\ndetails from events generated in the enabled channels. If the channel is\r\ndisabled, a warning is issued on the PowerShell console. By using the cmdlet\r\n`Update-xDscEventLogStatus`, you could enable the channel required to collect\r\nDSC events.\r\n\r\n#### Parameters\r\n\r\n- **Channel**: This is a mandatory parameter that indicates which DSC\r\n  channel status needs to be updated. { Analytic | Debug | Operational }\r\n- **Status**: This is a mandatory parameter that indicates the final\r\n  state of the channel. { Enabled | Disabled }\r\n- **Credential**: Credentials required to access the computer given in the\r\n  `ComputerName` property.\r\n- **ComputerName**: Name of the computer on which you would like to set\r\n  the log status. You would need to execute the following command on the\r\n  remote computer(s) in order to execute this operations on it.\r\n  ```powershell\r\n  New-NetFirewallRule -Name \"Service RemoteAdmin\" -Action Allow\r\n  ```\r\n\r\n### New-xDscDiagnosticsZip\r\n\r\nThis cmdlet generates a zip of DSC and DSC Extension diagnostics to send\r\nto support. The output will be the name of the zip file. The cmdlet will\r\nconfirm by default.\r\n\r\n#### Parameters\r\n\r\n- **Session**: This is an optional parameter of a PSSession to use to\r\n  collect the diagnostics\r\n\r\n### Get-xDscDiagnosticsZipDataPoint\r\n\r\nThis cmdlet returns the list a zip data point.\r\n\r\n#### Parameters\r\n\r\n_None._\r\n\r\n#### Outputs\r\n\r\nA data point has the following properties:\r\n\r\n- **Name**: A unique name for the data point.\r\n- **Description**: A description of the data point.\r\n- **Target**: The general area of diagnostics the datapoint targets.\r\n\r\n## Examples\r\n\r\n### Display the status of last 20 DSC operations\r\n\r\nThis example will list the last 20 DSC operations to see if any of them failed.\r\n\r\n```powershell\r\nGet-xDscOperation -Newest 20\r\n```\r\n\r\n### Display the status of the last two DSC operations in computer XXYY after passing Credential $cred\r\n\r\nThis example lets you find the status of DSC operations run on another computer. *Note: this requires a credential.*\r\n\r\n```powershell\r\nGet-xDscOperation -ComputerName Temp-Computer.domain.com -Credential $cred -Newest 2\r\n```\r\n\r\n### Trace a DSC operation that has a specific job ID\r\n\r\nThis example displays all events generated by the DSC operation that was assigned a particular unique job ID.\r\n\r\n```powershell\r\nTrace-xDscOperation -JobId aa6b4f3e-53f9-4f02-a502-26028e7531ca\r\n```\r\n\r\n### Get events of the second to last operation run on the localhost machine\r\n\r\nThis example displays a list of events and their messages published by the DSC operation run second to last (i.e. the sequence ID assigned to it is 2).\r\n\r\n```powershell\r\nTrace-xDscOperation -SequenceId 2 -ComputerName localhost\r\n```\r\n\r\n### Get diagnostic events of operations run on multiple computers that use the same credential\r\n\r\nThis example displays the list of events and their messages from multiple computers, as long as the credential passed works for all of them.\r\n\r\n```powershell\r\nGet-xDscOperation -ComputerName localhost, tempcomputer.domain.com -Credential $cred\r\n```\r\n\r\n### Enable the DSC Analytic event log\r\n\r\nThis example shows how you can enable the DSC Analytic channel event log.\r\nBy default, this channel is disabled.\r\nBy using this cmdlet, you can enable the channel collect all DSC events using the other 2 xDscDiagnostics cmdlets.\r\n\r\n```powershell\r\nUpdate-xDscEventLogStatus -Channel Analytic -Status Enabled\r\n```\r\n\r\n### Gather diagnostics from the machine running DSC or DSC Extension\r\n- [Install the Module](#install-the-module)\r\n- Open an elevated PowerShell Windows\r\n- Run:\r\n```PowerShell\r\nNew-xDscDiagnosticsZip\r\n```\r\n- Email the Zip that pops up to your support contact\r\n\r\n### Gather diagnostics for the DSC Pull Server and Windows data points.\r\n- [Install the Module](#install-the-module)\r\n- Open an elevated PowerShell Windows\r\n- Run:\r\n```PowerShell\r\nGet-xDscDiagnosticsZip -DataPointTarget 'DSC Pull Server','Windows'\r\n```\r\n- Email the Zip that pops up to your support contact\r\n\r\n### Gather diagnostics for only eventlog datapoints\r\n- [Install the Module](#install-the-module)\r\n- Open an elevated PowerShell Windows\r\n- Run:\r\n```PowerShell\r\nGet-xDscDiagnosticsZip -includedDataPoint (@(Get-xDscDiagnosticsZipDataPoint).where{$_.name -like '*eventlog'})\r\n```\r\n- Email the Zip that pops up to your support contact\r\n\r\n\r\n### Gather diagnostics from a PSSession to the machine running DSC or DSC Extension\r\n- [Install the Module](#install-the-module)\r\n- Open an PowerShell Windows\r\n- Open the PSSession to the Azure VM as an administrator on the VM\r\n- Run:\r\n```PowerShell\r\nNew-xDscDiagnosticsZip -Session $SessionToVm\r\n```\r\n- Email the Zip that pops up to your support contact\r\n\r\n\r\n### Get the details of the last operation DSC performed\r\n\r\n- Gets the verbose details of the Configuration Status object you pass to it.\r\n\r\n``` PowerShell\r\nStart-DscConfiguration .\\Example -Wait\r\nGet-DscConfigurationStatus | Get-xDscConfigurationDetail\r\n```\r\n\r\nExample output\r\n\r\n```plaintext\r\ntime                         type    message\r\n----                         ----    -------\r\n2016-03-16T12:45:17.756-7:00 verbose [tplunktower]: LCM:  [ Start  Set      ]\r\n2016-03-16T12:45:18.272-7:00 verbose [tplunktower]: LCM:  [ Start  Resource ]  [[Log]example]\r\n2016-03-16T12:45:18.273-7:00 verbose [tplunktower]: LCM:  [ Start  Test     ]  [[Log]example]\r\n2016-03-16T12:45:18.273-7:00 verbose [tplunktower]: LCM:  [ End    Test     ]  [[Log]example]  in 0.0000 seconds.\r\n2016-03-16T12:45:18.273-7:00 verbose [tplunktower]: LCM:  [ Start  Set      ]  [[Log]example]\r\n2016-03-16T12:45:18.274-7:00 verbose [tplunktower]:                            [[Log]example] example\r\n2016-03-16T12:45:18.274-7:00 verbose [tplunktower]: LCM:  [ End    Set      ]  [[Log]example]  in 0.0010 seconds.\r\n2016-03-16T12:45:18.274-7:00 verbose [tplunktower]: LCM:  [ End    Resource ]  [[Log]example]\r\n2016-03-16T12:45:18.278-7:00 verbose [tplunktower]: LCM:  [ End    Set      ]\r\n2016-03-16T12:45:18.279-7:00 verbose [tplunktower]: LCM:  [ End    Set      ]    in  0.5230 seconds.\r\n\r\n```\r\n\r\n### Decrypt the current mof\r\n\r\n- Decrypts the current mof LCM is using.  **Must be run as administrator**\r\n\r\n``` PowerShell\r\nUnprotect-xDscConfigurtion -Stage Previous\r\n```\r\n\r\nExample output\r\n\r\n```\r\n?/*\r\n@TargetNode='localhost'\r\n@GeneratedBy=tplunk\r\n@GenerationDate=04/07/2016 16:54:16\r\n@GenerationHost=localhost\r\n*/\r\n\r\ninstance of MSFT_LogResource as $MSFT_LogResource1ref\r\n{\r\nSourceInfo = \"::1::24::log\";\r\n ModuleName = \"PsDesiredStateConfiguration\";\r\n ResourceID = \"[Log]example\";\r\n Message = \"example\";\r\n\r\nModuleVersion = \"1.0\";\r\n ConfigurationName = \"example\";\r\n};\r\ninstance of OMI_ConfigurationDocument\r\n\r\n                    {\r\n Version=\"2.0.0\";\r\n\r\n                        MinimumCompatibleVersion = \"1.0.0\";\r\n\r\n                        CompatibleVersionAdditionalProperties= {\"Omi_BaseResource:ConfigurationName\"};\r\n\r\n                        Author=\"tplunk\";\r\n\r\n                        GenerationDate=\"04/07/2016 16:54:16\";\r\n\r\n                        GenerationHost=\"localhost\";\r\n\r\n                        Name=\"example\";\r\n\r\n                    };\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsccommunity%2Fxdscdiagnostics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdsccommunity%2Fxdscdiagnostics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsccommunity%2Fxdscdiagnostics/lists"}