Protokollierung

Über

PowerShell Universal verwendet ein strukturiertes Logging-Framework namens Serilog. Serilog erlaubt mehrere Logging-Ziele (Sinks), Log-Event-Eigenschaften und die Speicherung von Log-Event-Daten. Standardmäßig protokolliert PowerShell Universal zwei verschiedene Logdateien. Die erste ist das Systemlog. Dieses enthält Logdetails über den PowerShell Universal-Server und ist standardmäßig auf verbose eingestellt. Die zweite ist das Benutzerlog. Das Benutzerlog erfasst Informationen über alle Skripte, die innerhalb von PowerShell Universal ausgeführt werden und vom Benutzer erstellt wurden.

Beide Logdateien befinden sich in %ProgramData%\PowerShellUniversal.

System-Logging

Das System-Logging wird über die Anwendungseinstellungen (appsettings.json) oder Umgebungsvariablen konfiguriert. Systemlogs enthalten typischerweise internes Logging, das hilfreich ist, um festzustellen, was innerhalb des PowerShell Universal-Servers passiert, und nicht notwendigerweise in Ihren Skripten.

Die Systemlog-Einstellungen befinden sich im Stammverzeichnis von appsettings.json.

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

Der Systemlog-Pfad kann Umgebungsvariablen enthalten. Gültige Log-Level sind:

• Verbose
• Debug
• Information
• Warning
• Error

Wir empfehlen, in Produktionsumgebungen auf Information oder höher zu laufen und nur beim Debuggen von Problemen unter diese Level zu wechseln.

Konfiguration

Die Logging-Konfiguration kann auf der Seite Einstellungen \ Logging geändert werden.

Ziele

PowerShell Universal bietet fünf integrierte Logging-Ziele.

• Datei
• Datenbank
• TCP
• HTTP
• PowerShell

Jedes Ziel hat seinen eigenen Satz von Eigenschaften. Zum Beispiel haben Dateien eine Dateipfad-Eigenschaft.

Scope

Jedes Ziel kann so konfiguriert werden, dass es einen bestimmten Satz von Log-Ereignissen erfasst, basierend darauf, was sie erzeugt. Dazu gehören:

• Scope - System- oder Benutzer-Logmeldungen
• Feature - Die Funktion, die die Logmeldung erzeugt (z. B. API)
• Resource - Eine bestimmte Ressource, die das Log erzeugt (z. B. Script1.ps1)

Wenn Feature oder Resource nicht angegeben sind, empfängt das Logziel alle Meldungen für den Scope. Wenn Sie zum Beispiel ein Ziel mit einem User-Scope und einem API-Feature definieren, würde es alle API-Anfragen protokollieren.

Level

Log-Level legen fest, welche Meldungen basierend auf dem Level der Logmeldungen protokolliert werden. Zum Beispiel empfängt ein Logging-Ziel, das auf das Level Information konfiguriert ist, Logmeldungen von Information bis Error, protokolliert aber keine Debug- oder Verbose-Meldungen.

PowerShell-Ziel

Das PowerShell-Logging-Ziel kann verwendet werden, um einen benutzerdefinierten Logger mit einem PowerShell-Skriptblock zu erstellen, der die Meldungen empfängt. Der Skriptblock sollte zwei Parameter haben. Der erste ist das von Serilog erzeugte Log-Event-Objekt und der zweite die gerenderte Meldungszeichenfolge.

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

Berücksichtigen Sie die Leistung bei der Verwendung des PowerShell-Ziels, da PowerShell für jede Logmeldung ausgeführt wird. Ein Logging-Runspace-Pool wird verwendet, um Multithread-Logging für PowerShell-Ziele bereitzustellen.

Protokollieren Sie innerhalb Ihres PowerShell-Ziels nicht mit Write-PSULog.

Write-PSULog

Sie können das Cmdlet Write-PSULog verwenden, um aus Ihren Skripten in Logs zu schreiben. Das Cmdlet setzt automatisch den User-Scope und Sie können wählen, ein Feature, eine Resource und eine Nachricht anzugeben.

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

Konsole

Sie können Write-PSULog erlauben, in die Streams der aktuellen PowerShell-Sitzung auszugeben, indem Sie den Schalterparameter -Console verwenden. Je nach gewähltem Level erscheinen die Logmeldungen auf diesen Streams.

# 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

Verschachtelte Runspaces

Wenn Ihre Lösung eigene Runspaces erstellt, entweder direkt oder über Jobs, können Sie Write-PSULog weiterhin verwenden, müssen dem Runspace jedoch die globale Variable $UniversalClient bereitstellen.

$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()

Logs anzeigen

Sie können Logs anzeigen, indem Sie Platform \ Logging aufrufen. Der Log-Viewer zeigt standardmäßig alle Logmeldungen an. Sie können die Sortier- und Filteroptionen verwenden, um bestimmte Level, Features und Ressourcen auszuwählen, für die die Logs angezeigt werden sollen.

Die Suchleiste sucht nach Logmeldungen, die die Suchzeichenfolge enthalten.

Log-Viewer

Beispiel: ELK-Stack

Sie können das TCP-Logging-Ziel verwenden, um Logmeldungen im ELK-Stack zu speichern und zu parsen. Für dieses Beispiel verwenden wir das docker-elk-Repository.

Klonen Sie das docker-elk-Repository und führen Sie die folgenden Befehle im Repository aus.

docker-compose up setup
docker-compose up

Nach der Ausführung läuft der ELK-Stack. Sie können die Web-Konsole aufrufen, indem Sie zu http://localhost:5601 navigieren.

Der Standardbenutzername ist elastic und das Passwort ist changeme.

In PowerShell Universal möchten Sie ein Logging-Ziel erstellen und TCP-Ereignisse an tcp://localhost:50000 senden.

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

Die obige Konfiguration sendet alle Logmeldungen des User-Scope über die TCP-Verbindung an Logstack. Navigieren Sie unter dem Abschnitt Observability in der Konsole zur Seite Logs \ Stream.

Von hier aus können Sie Logmeldungen von Universal suchen und anzeigen.