LLI Wiki — My Digital Knowledge Base

Logging standards for scheduled PowerShell jobs

Levels, structured lines, a correlation id per run, where logs go (file, Log Analytics), what never to log, and Write-Host pitfalls in non-interactive runs.

A scheduled job that fails at 3 a.m. has one witness: its log. If the log is a pile of Write-Host lines with no level, no timestamp and no way to tell which run produced them, you will spend your morning guessing. These are the logging standards I apply to every unattended PowerShell job.

One logging function, five levels

All logging goes through a single function. Nobody calls Write-Host directly. The function has five levels and each one has a clear meaning.

Level Use it for Shown
Info Milestones of the run: step started, step finished, counts Always
Warning Degraded but continuing: a retry, a skipped item Always
Error A failure that matters Always
Verbose Execution trace: which server, which branch With -Verbose
Debug Technical detail: the query text, payload shape With -Debug

Verbose and debug stay quiet in production and can be switched on for one run without editing code, because they follow the standard $VerbosePreference and $DebugPreference variables.

Structured lines

A log line should be parseable by a human and by a query. I use a fixed shape: a UTC timestamp in a sortable format, the level in brackets, then the message.

20261119T030012 [INFO]: [run=7f3a9c] Step 2 started: collect pool metrics
20261119T030014 [WARNING]: [run=7f3a9c] Retry 2/5 after timeout (30s)
20261119T030040 [ERROR]: [run=7f3a9c] Step 2 failed: login timeout

UTC everywhere avoids the daylight-saving argument when two machines in different time zones log the same run.

function Write-Log {
    [CmdletBinding()]
    param(
        [ValidateSet('INFO','WARNING','ERROR','VERBOSE','DEBUG')][string]$Level = 'INFO',
        [Parameter(Mandatory)][string]$Message,
        [string]$LogFile,
        [string]$RunId = $script:RunId
    )
    $line = '{0:yyyyMMddTHHmmss} [{1}]: [run={2}] {3}' -f (Get-Date).ToUniversalTime(), $Level, $RunId, $Message
    if ($LogFile) { Add-Content -Path $LogFile -Value $line -Encoding utf8 }
    switch ($Level) {
        'ERROR'   { Write-Error $Message -ErrorAction Continue }
        'WARNING' { Write-Warning $Message }
        'VERBOSE' { Write-Verbose $Message }
        'DEBUG'   { Write-Debug $Message }
        default   { Write-Information $line -InformationAction Continue }
    }
}

When several processes write to the same file, serialise the writes with a named mutex scoped to that file path, not one machine-wide lock.

A correlation id per run

At start-up, generate a short id once and put it in every line.

$script:RunId = [guid]::NewGuid().ToString('N').Substring(0, 8)

When one night's run touches fifty databases and a log platform holds the logs of ten jobs, the run id is the only reliable filter. Put it in the report e-mail and in the file name as well, so an alert leads straight to the right log.

Where logs go

flowchart LR
    J["Scheduled job"] --> F["Log file per run"]
    J --> S["Structured record"]
    S --> L["Log Analytics custom table"]
    F --> A["Artifact or share"]
    L --> Q["KQL query / Grafana"]

What never to log

Review the debug output once with fresh eyes: query text is the usual leak.

Write-Host pitfalls in non-interactive runs

Lessons learned

Mastodon LLIMastodon SocialFosstodon