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"]
- Fichier : un fichier par exécution, nommé avec horodatage, job et environnement, dans un dossier par environnement. Séparez les lignes d'erreur et d'avertissement dans de petits fichiers dédiés : un coup d'oeil au dossier montre quelles exécutions ont posé problème.
- Log Analytics : envoyez l'enregistrement structuré (id de run, niveau, étape, message) vers une table personnalisée via l'API d'ingestion de logs et une règle de collecte de données. Vous obtenez des requêtes KQL multi-exécutions et des tableaux de bord. Comptez un délai d'ingestion de quelques minutes avant qu'une ligne soit interrogeable.
- Gardez le fichier comme source de vérité : il fonctionne encore quand le réseau ou le workspace ne répondent plus.
Ce qu'on ne logue jamais
- Les secrets : mots de passe, clés, jetons, chaînes de connexion avec identifiants, clés d'API. Pas même en debug, car le debug est exactement ce que l'on active pendant un incident.
- Les jetons d'accès complets : loguez qu'un jeton a été obtenu et son expiration, jamais sa valeur.
- Le dump complet des paramètres d'une fonction qui reçoit un secret. Masquez par nom (
*password*,*key*,*token*,*secret*) avant d'afficher. - Les données personnelles revenues par hasard d'une requête.
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
Write-Hostn'est pas un log. Il n'a ni niveau ni horodatage, et rien ne l'écrit dans votre fichier sauf si vous capturez le flux d'information.- Il ne passe pas par le flux de sortie standard : rediriger la sortie d'une fonction ne le capture pas, et
-Verboseou-Debugne peuvent pas le filtrer. - Dans un planificateur, un pipeline ou une tâche batch, l'hôte n'est pas une console. Les couleurs n'ont aucun sens et certains hôtes perdent ou déforment le texte.
- Dans une fonction qui renvoie des données, mélanger messages
Write-Hostet objets retournés est un piège : utilisez le bon flux pour chaque chose.
Retour d'expérience
- Loguez le début et la fin de chaque étape, avec des volumes. « Étape 3 terminée, 42 éléments, 2 ignorés » fait gagner plus de temps qu'une pile d'appels.
- Loguez toujours le message de l'exception et, en debug, la pile d'appels du script.
- Un retry est un warning, pas une info : si vous ne lisez jamais les warnings, vous raterez le job qui a besoin de trois tentatives chaque nuit.
- Plafonnez la rétention. Des logs sans politique de rétention deviennent le prochain incident de disque plein.