Journalisation

À propos

PowerShell Universal utilise un cadre de journalisation structuré appelé Serilog. Serilog permet d'avoir plusieurs cibles de journalisation (sinks), des propriétés d'événements de journal et le stockage des données d'événements de journal. Par défaut, PowerShell Universal enregistre deux fichiers journaux différents. Le premier est le journal système. Il contient les détails de journalisation concernant le serveur PowerShell Universal et est réglé sur verbose par défaut. Le second est le journal utilisateur. Le journal utilisateur capture les informations sur tous les scripts exécutés dans PowerShell Universal qui sont créés par l'utilisateur.

Les deux fichiers journaux se trouvent dans %ProgramData%\PowerShellUniversal.

Journalisation système

La journalisation système est configurée par l'intermédiaire des paramètres de l'application (appsettings.json) ou des variables d'environnement. Les journaux système contiennent généralement une journalisation interne utile pour déterminer ce qui se passe dans le serveur PowerShell Universal, et pas nécessairement dans vos scripts.

Les paramètres du journal système se trouvent à la racine de appsettings.json.

{
    "SystemLogPath": "%ProgramData%\\PowerShellUniversal",
    "SystemLogLevel": "Information"
}

Le chemin du journal système peut contenir des variables d'environnement. Les niveaux de journalisation valides comprennent :

• Verbose
• Debug
• Information
• Warning
• Error

Nous recommandons d'utiliser le niveau Information ou supérieur dans les environnements de production et de ne descendre sous ces niveaux que lors du débogage de problèmes.

Configuration

La configuration de la journalisation peut être modifiée sous Observe > Logging > Logging Targets.

Cibles

PowerShell Universal offre cinq cibles de journalisation intégrées.

• File
• Database
• TCP
• HTTP
• PowerShell

Chaque cible possède son propre ensemble de propriétés. Par exemple, les fichiers auront une propriété de chemin de fichier.

Portée

Chaque cible peut être configurée pour capturer un ensemble précis d'événements de journal selon ce qui les génère. Ceux-ci comprennent :

• Scope – Messages de journal système ou utilisateur
• Feature – La fonctionnalité qui génère le message de journal (p. ex. API)
• Resource – Une ressource précise qui génère le journal (p. ex. Script1.ps1)

Si la fonctionnalité ou la ressource ne sont pas précisées, la cible de journalisation recevra tous les messages de la portée. Par exemple, si vous définissez une cible avec une portée User et une fonctionnalité API, elle journaliserait toutes les requêtes API.

Niveau

Les niveaux de journalisation définissent quels messages journaliser selon le niveau des messages de journal. Par exemple, une cible de journalisation configurée au niveau Information recevra les messages de journal d'Information jusqu'à Error, mais ne journalisera pas les messages debug ou verbose.

Cible PowerShell

La cible de journalisation PowerShell peut être utilisée pour créer un journaliseur personnalisé avec un bloc de script PowerShell qui reçoit les messages. Le bloc de script devrait avoir deux paramètres. Le premier est l'objet d'événement de journal produit par Serilog et le second est la chaîne du message rendu.

New-PSULoggingTarget -Type 'PowerShell' -Level 'Information' -Scope User -Feature API -ScriptBlock {
    param($LogEvent, $Message) 
    
    $Message | Out-File C:\logs\log.txt
}

Tenez compte de la performance lorsque vous utilisez la cible PowerShell, car PowerShell sera exécuté pour chaque message de journal. Un pool de runspaces de journalisation est utilisé pour fournir une journalisation multithread pour les cibles PowerShell.

Ne journalisez pas dans votre cible PowerShell à l'aide de Write-PSULog.

Write-PSULog

Vous pouvez utiliser l'applet de commande Write-PSULog pour écrire dans les journaux à partir de vos scripts. L'applet de commande définit automatiquement la portée User et vous pouvez choisir de fournir une fonctionnalité, une ressource et un message.

Write-PSULog -Feature 'MyFeature' -Message 'MyMessage'

Console

Vous pouvez permettre à Write-PSULog d'écrire dans les flux de la session PowerShell courante en utilisant le paramètre de commutateur -Console. Selon le niveau que vous sélectionnez, les messages de journal apparaîtront sur ces flux.

# Information Stream
Write-PSULog -Console -Message "MyInfoMessage" -Level Information
# Error Stream
Write-PSULog -Console -Message "MyErrorMessage" -Level Error
# Warning Stream
Write-PSULog -Console -Message "MyWarningMessage" -Level Warning

Runspaces imbriqués

Si votre solution crée ses propres runspaces, directement ou par l'intermédiaire de tâches, vous pouvez continuer d'utiliser Write-PSULog, mais vous devrez fournir la variable globale $UniversalClient au runspace.

$iss= [InitialSessionState]::CreateDefault()
$var1 = [SessionStateVariableEntry]::new("UniversalClient",
                                      $UniversalClient,
                                      "The PSU Client")
$iss.Variables.Add($var1)
$runspace = [runspacefactory]::CreateRunspace($iss)
$runspace.Open()
$script = { Write-PSULog -Message 'Hello from a runspace!' }
$pipeline = $runspace.CreatePipeline()
$pipeline.Commands.AddScript($script)
$pipeline.Invoke()
$runspace.Close()

Consulter les journaux

Vous pouvez consulter les journaux en direct sous Observe > Logging > Live Logs. La visionneuse de journaux affichera tous les messages de journal par défaut. Vous pouvez utiliser les options de tri et de filtrage pour sélectionner des niveaux, des fonctionnalités et des ressources particuliers pour lesquels consulter les journaux.

La barre de recherche cherchera les messages de journal contenant la chaîne de recherche.

Exemple : pile ELK

Vous pouvez utiliser la cible de journalisation TCP pour stocker et analyser les messages de journal dans une pile ELK. Pour les besoins de cet exemple, nous utiliserons le dépôt docker-elk.

Clonez le dépôt docker-elk et exécutez les commandes suivantes dans le dépôt.

docker-compose up setup
docker-compose up

Une fois exécutées, la pile ELK sera en cours d'exécution. Vous pouvez accéder à la console Web en naviguant vers http://localhost:5601.

Le nom d'utilisateur par défaut est elastic et le mot de passe est changeme.

Dans PowerShell Universal, vous voudrez créer une cible de journalisation et envoyer les événements TCP à tcp://localhost:50000.

New-PSULoggingTarget -Type "TCP" -Level "Verbose" -Properties @{
    hostName = 'tcp://localhost'
    port     = '50000'
} -Scope "User"

La configuration ci-dessus enverra tous les messages de journal de portée User à Logstack. Naviguez vers Observe > Logging > Live Logs.

À partir d'ici, vous pourrez rechercher et consulter les messages de journal provenant de Universal.