LLI Wiki — My Digital Knowledge Base

Standards de log pour jobs PowerShell planifiés

Niveaux, lignes structurées, identifiant de corrélation par exécution, destinations (fichier, Log Analytics), ce qu'on ne logue jamais et pièges de Write-Host.

Un job planifié qui échoue à 3 h du matin n'a qu'un témoin : son log. Si ce log est un tas de lignes Write-Host sans niveau, sans horodatage et sans moyen de savoir quelle exécution les a produites, vous passerez la matinée à deviner. Voici les standards de log que j'applique à tous mes jobs PowerShell non interactifs.

Une fonction de log, cinq niveaux

Tout passe par une seule fonction. Personne n'appelle Write-Host directement. Elle a cinq niveaux, chacun avec un sens précis.

Niveau Usage Affiché
Info Jalons de l'exécution : étape démarrée, terminée, volumes Toujours
Warning Dégradé mais on continue : un retry, un élément ignoré Toujours
Error Un échec qui compte Toujours
Verbose Trace d'exécution : quel serveur, quelle branche Avec -Verbose
Debug Détail technique : texte de requête, forme d'un payload Avec -Debug

Verbose et debug restent silencieux en production et s'activent pour une seule exécution sans modifier le code, car ils suivent les variables standard $VerbosePreference et $DebugPreference.

Lignes structurées

Une ligne de log doit être lisible par un humain et par une requête. J'utilise une forme fixe : horodatage UTC triable, niveau entre crochets, puis le 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

L'UTC partout évite la discussion sur l'heure d'été quand deux machines de fuseaux différents journalisent la même exécution.

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 }
    }
}

Quand plusieurs processus écrivent dans le même fichier, sérialisez les écritures avec un mutex nommé propre à ce chemin de fichier, pas un verrou global à la machine.

Un identifiant de corrélation par exécution

Au démarrage, générez une fois un identifiant court et mettez-le dans chaque ligne.

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

Quand le run d'une nuit touche cinquante bases et qu'une plateforme de logs contient dix jobs, l'identifiant de run est le seul filtre fiable. Mettez-le aussi dans le mail de rapport et dans le nom du fichier, pour qu'une alerte mène droit au bon log.

Où vont les logs

flowchart LR
    J["Job planifié"] --> F["Fichier de log par exécution"]
    J --> S["Enregistrement structuré"]
    S --> L["Table personnalisée Log Analytics"]
    F --> A["Artefact ou partage"]
    L --> Q["Requête KQL / Grafana"]

Ce qu'on ne logue jamais

Relisez une fois la sortie debug avec un oeil neuf : le texte des requêtes est la fuite habituelle.

Pièges de Write-Host en exécution non interactive

Retour d'expérience

Mastodon LLIMastodon SocialFosstodon