Writing to a Log file with PowerShell

My experience in a systems administrator role has taught me that logs are critical to debug and troubleshoot technical situations. Most endpoint management systems such as Intune or Configuration Manager output to logs files on the client that log the activity of application deployments, health scripts, policies, etc. I was taught to use a logging viewer like CMTrace, use SMB protocol in File Explorer to open logs in remote machines and examine the contents of the log files to debug and troubleshoot issues. There are a variety of log viewers and syslog servers available for free or low cost.

What is a Log File

A log file is a chronological record of events, activities, or errors generated by software or systems, aiding in troubleshooting, auditing, and understanding system behavior over time. Logs files are generated when a script, OS, or application appends its output to a log file

Redirect Streams in PowerShell

Stdout and stderr are both streams used in computing environments, including PowerShell and other command-line interfaces. In PowerShell (and many other command-line environments), 1 and 2 are file descriptors representing different output streams. According to the Microsoft Redirect Docs, amazingly, there are six different streams, we will be using 1 and 2:

Redirect Stream Syntax

• 1 represents Standard Output (stdout).
• 2 represents Standard Error (stderr).

I’m sure you’ve seen this syntax 1> or 2>, this is redirecting the output stream to the file. For example, this code would redirect an error stream because the Cmdlet is outputting a stream with 1 if successful, or 2 if the path doesn’t exist (./FakePath does not exist on my host).

Get-ChildItem ./FakePath 2> error2FD.txt

But conversely, this line would output the stderr (2) to the console because we are trying to capture stdout (1), the command doesn’t have that stdout file descriptor stream, only stderr, so it outputs it to the console.

Get-ChildItem ./FakePath 1> error1FD.txt
--------------------CONSOLE------------------------
Line |
  20 |  Get-ChildItem ./FakePath 1> error1FD.txt
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Cannot find path 'C:\Users\Administrator.HOME-CENTER-1.001\Desktop\PowerShell\tools\FakePath' because it does not exist.

Append Redirection Operator

Redirecting the stream using > to an outfile does overwrite the existing contents with the redirected stream. To append the stream to outfile – the stream being stdout (1) or stderr (2), – use the >> syntax, also called the “append redirection operator”. So, for example:

Write-Error "Redirect the contents." 2> error.txt

Write-Error "Append the contents." 2>> error.txt

Write-Error "Redirect the stderr (2) to stdout (1) then append that stream to the file." 2>&1>> error.txt

Although this is common knowledge in programming languages such as C and C++, not common for me. Believe me when I say I am learning as I go, and I hope you are too. This knowledge can be valuable when creating a log file, because now we can use a Write Cmdlet in certain parts of our code and pass in the appropriate prefix (INFO, WARN, ERROR) when we redirect output steams using the file descriptor. I can experiment more with this method and get back to you, or you can experiment and leave a comment or Contact Me!

Create a Simple Write-Log Function in your Script!

Let’s get to the code, shall we? This is a fairly simple function you can incorporate into your script and call it with a custom message and information level. In the context of log files, whether or not the file references the first part of a string like “INFO” or “WARN” depends entirely on how the log file is structured and what logging conventions or standards are being followed by the application or system generating the log.

Conventionally, many log files do include a prefix or tag at the beginning of each log entry to indicate the log level or severity, such as “INFO”, “WARN”, “ERROR”, etc. This prefix helps to categorize log entries and make it easier to identify the nature of each log message.

$fileName = "$($($MyInvocation.MyCommand.Name) -replace '.ps1', '')_$(Get-Date -f 'yyyyMMdd').log"

function Write-Log {
    param (
        [Parameter(Mandatory=$true)]
        [ValidateSet("INFO", "WARN", "ERROR")]
        [string] $importance,

        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [string] $message
    )
    
    if( -not (Test-Path $fileName)){ New-Item -Path $PSScriptRoot -Name $fileName -Force | Out-Null }
    "$importance $(Get-Date -f "hh:mm:ss") - $message" | Add-Content $fileName
}


@("Mercury", "Venus", "Earth", "Mars") | ForEach-Object {
    try{
        switch -Regex ($_){
            "^(Mercury|Venus)$" {
                throw "$_ is not habitable."
            }
            "Earth" { 
                Write-Log -message "$_ is our base station for now!" -importance INFO 
            }
            "Mars" { 
                Write-Log -message "$_, like matt Damon from Martian, we will be explorers on a new planet within a decade!" -importance WARN 
            }
        }
    }catch{
        Write-Log -message $_.Exception.Message -importance ERROR
    }
}

Conclusion

Ok, so $MyInvocation is an Automatic Variable, and we use it to return the name of the script it is being run from. You can generally assume that $MyInvocation.MyCommand.Name will return the name of the script or function within the scope where it’s called. We Create a Write-Log function and use the ValidateSet attribute to require one of these prefixes. We use this file name and the formatted date as the default name of our logging file. In the function, we test for the path of the log file, and we format a string with the prefix, time and message, then pipe it to Add-Content Cmdlet. I created an array of planet names and through each iteration I wrapped the logic in a try-catch block. Notice the throw keyword – yeah bro – that throws a stream number of 2, so we catch the stack and write the message property to the log file. You can incorporate this function into your code and call it whenever you want to log output.