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