Exploring the PowerShell PSDiagnostics Module

Exploring the PowerShell PSDiagnostics Module

  • Comments 2
  • Likes

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.

Image of command output

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.

Image of command output

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.

Image of command output

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.

Image of Log Properties dialog box

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

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hi,

    I hope that you enjoy your trip in Europe.

    I enjoyed your post as I've been recently troubleshooting a PS remoting issue.

    But, can you pls be more specific about the version of Powershell and the plateform you've been using for these commands. I can only see in the title of the image that it's powershell V3 and that some syntaxes are V3 only.

    The following log doesn't exist on Windows 7: Microsoft-Windows-PowerShell/Admin

    It has been introduced on W8/WS2012 platforms. You don't get it even if you install the WMF 3.0 on Windows 7.

    The content of the PSDiagnostics cmdlets has also changed.

    On V2, you have: (dir Function:Enable-PSTrace).Definition

       $Properties = Get-LogProperties ($script:psprovidername + $script:analyticlog)

       $Properties.Enabled = $true

       Set-LogProperties $Properties

    To enable Eventlog logging, instead of using wevtutil, you can do with admin privileges for example:

       $log = New-Object -TypeName System.Diagnostics.Eventing.Reader.EventLogConfiguration -ArgumentList "Microsoft-Windows-NDIS/Diagnostic"

       $log.isEnabled = $true

       try {

           $log.SaveChanges()

       } catch {

           Write-Warning -Message "Failed to save changes because $($_.Exception.Message)"

       }

  • useful script, thanks.