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"]
- File: one file per run, named with timestamp, job and environment, in a per-environment folder. Split error and warning lines into their own small files so a glance at the folder shows which runs had problems.
- Log Analytics: send the structured record (run id, level, step, message) to a custom table through the Logs Ingestion API and a data collection rule. That gives you cross-run KQL queries and dashboards. Expect an ingestion delay of a few minutes before a line is queryable.
- Keep the file as the source of truth: it still works when the network or the workspace does not.
What never to log
- Secrets: passwords, keys, tokens, connection strings with credentials, API keys. Not even at debug level, because debug is exactly what someone enables during an incident.
- Full access tokens: log that a token was obtained and its expiry, never its value.
- The complete bound-parameter dump of a function that takes a secret. Mask by name (
*password*,*key*,*token*,*secret*) before printing. - Personal data that happened to come back from a query.
Review the debug output once with fresh eyes: query text is the usual leak.
Write-Host pitfalls in non-interactive runs
Write-Hostis not a log. It has no level, no timestamp and nothing writes it to your file unless you capture the information stream.- It does not travel on the success output stream, so redirecting the output of a function does not capture it, and it cannot be filtered with
-Verboseor-Debug. - In a scheduler, pipeline or batch task the host is not a console. Colours are meaningless, and some hosts drop or mangle the text.
- Inside a function that returns data, mixing
Write-Hostmessages with returned objects is a trap: use the right stream for each.
Lessons learned
- Log the beginning and end of every step, with counts. "Step 3 done, 42 items, 2 skipped" saves more time than any stack trace.
- Always log the exception message and, at debug level, the script stack trace.
- A retry is a warning, not an info: if you never read the warnings you will miss the job that needs three attempts every night.
- Cap log retention. Logs without a retention policy become the next disk-full incident.