• "Exploring the PowerShell PSDiagnostics Module"
  Published by The Scripting Guys on 23 Nov 2012
  http://blogs.technet.com/b/heyscriptingguy/archive/2012/11/23/exploring-the-powershell-psdiagnostics-module.aspx

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.