> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/entwicklung/logging.md). # Protokollierung Konfigurieren Sie die Protokollierung von PowerShell Universal mit Serilog – einschließlich System- und Benutzer-Protokollzielen, Write-PSULog, Protokollebenen und dem Streaming von Protokollen an ein ## Über PowerShell Universal verwendet ein strukturiertes Protokollierungs-Framework namens Serilog. Serilog ermöglicht mehrere Protokollierungsziele (Sinks), Eigenschaften von Protokollereignissen und die Speicherung von Protokollereignisdaten. Standardmäßig schreibt PowerShell Universal zwei verschiedene Protokolldateien. Die erste ist das Systemprotokoll. Es enthält Protokolldetails über den PowerShell Universal-Server und ist standardmäßig auf „verbose“ eingestellt. Die zweite ist das Benutzerprotokoll. Das Benutzerprotokoll erfasst Informationen über alle innerhalb von PowerShell Universal ausgeführten Skripte, die vom Benutzer erstellt wurden. Beide Protokolldateien befinden sich in `%ProgramData%\PowerShellUniversal`. ## Systemprotokollierung Die Systemprotokollierung wird über die Anwendungseinstellungen (appsettings.json) oder Umgebungsvariablen konfiguriert. Systemprotokolle enthalten typischerweise interne Protokollierung, die hilfreich ist, um festzustellen, was innerhalb des PowerShell Universal-Servers geschieht, und nicht unbedingt in Ihren Skripten. Die Einstellungen für das Systemprotokoll befinden sich im Stammverzeichnis von appsettings.json. ```json { "SystemLogPath": "%ProgramData%\\PowerShellUniversal", "SystemLogLevel": "Information" } ``` Der Pfad des Systemprotokolls kann Umgebungsvariablen enthalten. Gültige Protokollebenen sind: * Verbose * Debug * Information * Warning * Error Wir empfehlen, in Produktionsumgebungen auf Information oder höher zu arbeiten und nur beim Debuggen von Problemen unter diese Ebenen zu wechseln. ## Konfiguration Die Protokollierungskonfiguration kann unter **Observe > Logging > Logging Targets** geändert werden. ### Ziele PowerShell Universal bietet fünf integrierte Protokollierungsziele. * Datei * Datenbank * TCP * HTTP * PowerShell Jedes Ziel hat seinen eigenen Satz von Eigenschaften. Beispielsweise haben Dateien eine Dateipfad-Eigenschaft. #### Bereich Jedes Ziel kann so konfiguriert werden, dass es einen bestimmten Satz von Protokollereignissen basierend darauf erfasst, was sie erzeugt. Dazu gehören: * Scope – System- oder Benutzer-Protokollmeldungen * Feature – Die Funktion, die die Protokollmeldung erzeugt (z. B. API) * Resource – Eine bestimmte Ressource, die das Protokoll erzeugt (z. B. Script1.ps1) Wenn Feature oder Resource nicht angegeben sind, erhält das Protokollierungsziel alle Meldungen für den Bereich. Wenn Sie beispielsweise ein Ziel mit dem Bereich „User“ und dem Feature „API“ definieren, würden alle API-Anfragen protokolliert. #### Ebene Protokollebenen legen fest, welche Meldungen basierend auf der Ebene der Protokollmeldungen protokolliert werden. Beispielsweise erhält ein auf die Ebene Information konfiguriertes Protokollierungsziel Protokollmeldungen von Information bis Error, protokolliert aber keine Debug- oder Verbose-Meldungen. ### PowerShell-Ziel Das PowerShell-Protokollierungsziel 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 Protokollereignis-Objekt und der zweite die gerenderte Meldungszeichenfolge. ```powershell 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 Protokollmeldung ausgeführt wird. Ein Protokollierungs-Runspace-Pool wird verwendet, um eine mehrfädige Protokollierung 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 heraus in Protokolle zu schreiben. Das Cmdlet legt automatisch den Bereich „User“ fest, und Sie können ein Feature, eine Ressource und eine Nachricht angeben. ```powershell Write-PSULog -Feature 'MyFeature' -Message 'MyMessage' ``` ### Konsole Sie können `Write-PSULog` erlauben, in die Streams der aktuellen PowerShell-Sitzung auszugeben, indem Sie den Switch-Parameter `-Console` verwenden. Abhängig von der von Ihnen gewählten Ebene erscheinen die Protokollmeldungen auf diesen Streams. {% code overflow="wrap" %} ```powershell # 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 ``` {% endcode %} ### 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. {% code overflow="wrap" %} ```powershell $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() ``` {% endcode %} ## Protokolle anzeigen Sie können Live-Protokolle unter **Observe > Logging > Live Logs** anzeigen. Der Protokoll-Viewer zeigt standardmäßig alle Protokollmeldungen an. Sie können die Sortier- und Filteroptionen verwenden, um bestimmte Ebenen, Features und Ressourcen auszuwählen, für die Sie die Protokolle anzeigen möchten. Die Suchleiste sucht nach Protokollmeldungen, die die Suchzeichenfolge enthalten. ## Beispiel: ELK-Stack Sie können das TCP-Protokollierungsziel verwenden, um Protokollmeldungen im ELK-Stack zu speichern und zu analysieren. Für dieses Beispiel verwenden wir das [docker-elk-Repository](https://github.com/deviantony/docker-elk). 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 lautet elastic und das Passwort changeme. In PowerShell Universal möchten Sie ein Protokollierungsziel erstellen und TCP-Ereignisse an `tcp://localhost:50000` senden. ```powershell New-PSULoggingTarget -Type "TCP" -Level "Verbose" -Properties @{ hostName = 'tcp://localhost' port = '50000' } -Scope "User" ``` Die obige Konfiguration sendet alle Protokollmeldungen des Bereichs „User“ an Logstack. Navigieren Sie zu **Observe > Logging > Live Logs**. Von hier aus können Sie Protokollmeldungen von Universal durchsuchen und anzeigen. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/de/entwicklung/logging.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.