Decipher SCCM Client Logs with PowerShell

If you’re an SCCM admin, you’re probably familiar with the CMtrace log-reading tool. CMTrace knows the specific schema of SCCM client logs but did you know you can use PowerShell much like CMTrace?

Using PowerShell, you can read:

• SCCM client software install logs
• SCCM client software update logs
• SCCM client hardware inventory logs

..and just about all the rest of them!

SCCM client logs follow a certain schema. To get some kind of standardized output from them, you have to understand that schema. Luckily, for you, that’s already been done.

Reading SCCM Client Logs with PowrShell

Take a look at the PowerShell code below that queries SCCM client logs.

This Get-SCCMClientLog PowerShell function has two parameters; ComputerName and LogName allowing you to query remote computers and specify the log name you’d like to view.

Related: PowerShell Function Introduction

Once you make this function available in your PowerShell console, you can then run it like below. The example below would query the remote computer called PC and retrieve the execmgr log file.

Get-SccmClientLog -ComputerName PC -LogName execmgr

All of the heavy-lifting has already been done for you in the function.

Creating Your own SCCM Client Logs

What if you want to use the Get-SCCMClientLog function but for other purposes. You can create your own SCCM client-like log files too!

Just look at the beauty of the sortable columns and the red highlighting! At first, you might think that you can view any kind of text log in CMTrace and you’d be right. However, let’s a look at the WindowsUpdate.log file in CMTrace.

Notice all the columns are gone? CMTrace will still view regular log files but you won’t get some of the features that make CMTrace great. You’ll soon find that a text file has to be properly formatted in order to get all of those helpful columns to show up and to properly define which lines should be highlighted yellow vs. red. vs. nothing at all.

I’d like to show you a couple of PowerShell functions called Write-Log and Start-Log. These functions were specifically built to record your script’s activity to a log file which can then be read in CMTrace.

By the end of this post, you will have a function that you can call in your scripts to build log files in a way for CMTrace to read them properly.

Start-Log

To prevent having to specify the same SCCM client log file path over and over again I chose to create a function called Start-Log. This function is intended to be called at the top of your script. This function simply creates a text file and (the important part) sets a global variable called ScriptLogFilePath.

[CmdletBinding()]
param (
    [ValidateScript({ Split-Path $_ -Parent | Test-Path })]
    [string]$FilePath
)
try {
    if (!(Test-Path $FilePath)) {
        ## Create the log file
        New-Item $FilePath -Type File | Out-Null
    }
    ## Set the global variable to be used as the FilePath for all subsequent Write-Log calls in this session
    $global:ScriptLogFilePath = $FilePath
} catch {
    Write-Error $_.Exception.Message
}

This function is super-simple. However, is required to prevent us from having to pass LogFile every, single time we need to call our Write-Log function in our scripts. By simply creating a global variable ahead of time, we can then simply call Write-Log and it will know the log file path.

Write-Log

Once you’ve called Start-Log in your script, you are now able to run Write-Log to write SCCM client log messages to the log file. Write-Log has two parameters; Message and LogLevel. Message is easy. That’s simply what you’d like to write to the log. LogLevel requires some explaining.

To get CMTrace to highlight lines as red or yellow the line needs to be recorded a certain way. More specifically, it needs to have a string like this: type="1". This type of key can be 1,2 or 3. These indicate levels of severity in your script.

For example, if I’d like to log a simple informational message, then that’d be a 1. If I’d like to log a more severe activity then I might use 2 which would get highlighted yellow. Finally, I might choose 3 if I’d like that line highlighted red in CMTrace.

param (
    [Parameter(Mandatory = $true)]
    [string]$Message,

    [Parameter()]
    [ValidateSet(1, 2, 3)]
    [int]$LogLevel = 1
)

Notice the LogLevel parameter? By default, it will set that to a 1 but you are always able to override that if necessary if you’d like to write some more severe activity that happens during your script’s execution.

Next, you need that handy date/time column to show up right. To do this required a specific date/time format that is achieved by this string manipulation wizardry.

$TimeGenerated = "$(Get-Date -Format HH:mm:ss).$((Get-Date).Millisecond)+000"

Next is where I’ll build a log line’s template using all of the appropriate format that the line needs to have to show up correctly in CMTrace.

$Line = '<![LOG[{0}]LOG]!><time="{1}" date="{2}" component="{3}" context="" type="{4}" thread="" file="">'

After you’ve got the template it’s then a matter of building what’s going to go in the {} ‘s. Here, I build an array which I will then pass into the $Line to replace all of our {} ‘s with real information.

$LineFormat = $Message, $TimeGenerated, (Get-Date -Format MM-dd-yyyy), "$($MyInvocation.ScriptName | Split-Path -Leaf):$($MyInvocation.ScriptLineNumber)", $LogLevel

These are in the same order as the {} ‘s above. {0} will get converted to $Message, {1} will get converted to $TimeGenerated, {2} will get converted to today’s date and {4} will get converted to $LogLevel.

Notice I skipped {3} ? This is where I get all ninja on you. CMTrace has a component column that I never used much so I decided to make something out of it.

I wanted to see the script’s name and the line number in which Write-Log was called. This string: "$($MyInvocation.ScriptName | Split-Path -Leaf):$($MyInvocation.ScriptLineNumber)" is what makes that happen.

I then bring these two variables together using PowerShell’s string formatting to build $Line.

$Line = $Line -f $LineFormat

It’s then just a matter of writing $Line to a text file that’s already been defined by Start-Log.

Add-Content -Value $Line -Path $ScriptLogFilePath

How it Works

Let’s say I build a script that looks something like this called LogDemo.ps1:

Start-Log -FilePath C:\MyLog.log
Write-Host "Script log file path is [$ScriptLogFilePath]"
Write-Log -Message 'simple activity'
Write-Log -Message 'warning' -LogLevel 2
Write-Log -Message 'Error' -LogLevel 3

This script creates our log file at C:\MyLog.log and then proceeds to write 3 levels of severity to the log through using the LogLevel parameters I explained above.

When I check out the output of this file with Get-Content it looks pretty ugly.

<![LOG[simple activity]LOG]!><time="18:56:26.307+000" date="12-03-2015" component="LogDemo.ps1:3" context="" type="1" thread="" file=""> <![LOG[warning]LOG]!><time="18:56:26.307+000" date="12-03-2015" component="LogDemo.ps1:4" context="" type="2" thread="" file=""> <![LOG[Error]LOG]!><time="18:56:26.307+000" date="12-03-2015" component="LogDemo.ps1:5" context="" type="3" thread="" file="">

However, let’s break this open in CMTrace and see what it looks like.

Isn’t that beautiful?

Even if you’re not an SCCM admin I highly recommend using CMTrace for all your log viewing needs.

Once you’ve got the log files in the appropriate format (and you now have no excuse not to) simply open them up in CMTrace and observe the beauty of all that is CMTrace!