Exploring the PowerShell PSDiagnostics Module

Doctor Scripto

Summary: Microsoft Scripting Guy, Ed Wilson, talks about exploring the Windows PowerShell PSDiagnostics module.

Microsoft Scripting Guy, Ed Wilson, is here. Let’s see, so today is November 23, 2012, which means that the Scripting Wife and I are in The Netherlands, and today, we are at the day-long Dutch PowerShell Group meeting. We get to see Jeff Wouters (yesterday’s guest on the Hey, Scripting Guy! Blog) and Stefan Stranger, who is a Microsoft PFE, as well as dozens of other way-cool Windows PowerShell people.

A quick look at the PSDiagnostics module

The PSDiagnostics module contains 10 functions that are useful when it comes to troubleshooting Windows PowerShell. To see the functions, use the Get-Command cmdlet, as shown here.

PS C:\> gcm -module psdiagnostics

CommandType     Name                                               ModuleName

———–     —-                                               ———-

Function        Disable-PSTrace                                    PSDiagnostics

Function        Disable-PSWSManCombinedTrace                       PSDiagnostics

Function        Disable-WSManTrace                                 PSDiagnostics

Function        Enable-PSTrace                                     PSDiagnostics

Function        Enable-PSWSManCombinedTrace                        PSDiagnostics

Function        Enable-WSManTrace                                  PSDiagnostics

Function        Get-LogProperties                                  PSDiagnostics

Function        Set-LogProperties                                  PSDiagnostics

Function        Start-Trace                                        PSDiagnostics

Function        Stop-Trace                                         PSDiagnostics

Unfortunately, there is absolutely no Help whatsoever when it comes to the PSDiagnostics module. This means that we are pretty much left to guess what it does and how it might be useful. So, what do the PSDiagnostics functions do? Typically, the way to find out about a function is to use Get-Help. Here is the output from Get-Help for the Enable-PSTrace function.

PS C:\> help Enable-PSTrace

NAME

    Enable-PSTrace

SYNTAX

    Enable-PSTrace [-Force] [-AnalyticOnly]

ALIASES

    None

REMARKS

    None

Hmm … that is not too enlightening. Well, one thing that is cool about Windows PowerShell functions is that there is a Function: PowerShell drive. Because, there is a Function: PowerShell drive, it means I can easily look at the content of a function to get a better idea of what it does. This is shown here.

What does the Enable-PSTrace function do? Well, it calls the Set-LogProperties function and passes either the Windows PowerShell analytic logs or the analytic and the debug logs so they can be enabled. So, we need to look at the Set-LogProperties function and see what it does. This is shown here.

The Set-LogProperties function is a bit longer, but one thing is clear—it calls Wevtutil and will enable the logs. From looking at it, it will also set backup, maximum log size, and other things as well.

Note   I wrote a couple of Hey, Scripting Guy! Blog posts that talked about using Wevtutil last year. One post was Automatically Enable and Disable Trace Logs using PowerShell and the other was Use PowerShell to Clear All Logs.

The Get-LogProperties function displays information about various diagnostic logs. It works as shown here.

PS C:\> Get-LogProperties Microsoft-Windows-PowerShell/Admin

Name       : Microsoft-Windows-PowerShell/Admin

Enabled    : True

Type       : Admin

Retention  : True

AutoBackup : False

MaxLogSize : 1048985600

Unfortunately, it does not accept wild cards, and when receiving wild cards in a log name, it paints the screen red, as shown here.

Of course, I can obtain the log names from the Event Viewer utility. All I need to do is to right-click the log, select Properties, and I can cut and paste the log name. The property page is shown here.

But, dude, this is Windows PowerShell. And with Windows PowerShell, I do not need to supply cryptic, long, convoluted log path names because I can use the Get-WinEvent cmdlet to find my Windows PowerShell log names, and then I can pass the information to the Get-LogProperties function. This is shown here.

PS C:\> Get-WinEvent -ListLog *powershell* | Foreach {Get-LogProperties $_.logname}

Name       : Windows PowerShell

Enabled    : True

Type       : Admin

Retention  : False

AutoBackup : False

MaxLogSize : 15728640

Name       : Microsoft-Windows-PowerShell/Admin

Enabled    : True

Type       : Admin

Retention  : True

AutoBackup : False

MaxLogSize : 1048985600

Name       : Microsoft-Windows-PowerShell/Operational

Enabled    : True

Type       : Operational

Retention  : False

AutoBackup : False

MaxLogSize : 15728640

If I want to look at only one log, I use the Where-Object to filter out the results. This is shown here.

PS C:\> Get-WinEvent -ListLog *powershell* | where logname -match admin | %{Get-LogPr

operties $_.logname}

Name       : Microsoft-Windows-PowerShell/Admin

Enabled    : True

Type       : Admin

Retention  : True

AutoBackup : False

MaxLogSize : 1048985600

If you are wondering why I use the Get-LogProperties function instead of the Get-WinEvent cmdlet, here is the output from Get-Winevent.

PS C:\> Get-WinEvent -ListLog *powershell* | where logname -match admin

LogMode   MaximumSizeInBytes RecordCount LogName

——-   —————— ———– ——-

Retain            1048985600           0 Microsoft-Windows-PowerShell/Admin

I see that both tell me the retention method and the maximum log size. But the Get-LogProperties function also tells me if the log is enabled, and if it has autobackup set.

Join me tomorrow when I will talk some more about using the functions from the PSDiagnostics module.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

Doctor Scripto Scripter, PowerShell, vbScript, BAT, CMD

Follow