> 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/it/sviluppo/logging.md). # Logging Configuri il logging di PowerShell Universal con Serilog, con target di log di sistema e utente, Write-PSULog, livelli di log e streaming dei log verso uno stack ELK. ## Informazioni PowerShell Universal utilizza un framework di logging strutturato chiamato Serilog. Serilog consente di avere più target di logging (sink), proprietà degli eventi di log e l'archiviazione dei dati degli eventi di log. Per impostazione predefinita, PowerShell Universal registra due file di log differenti. Il primo è il log di sistema. Contiene dettagli di log sul server PowerShell Universal ed è impostato su verbose per impostazione predefinita. Il secondo è il log utente. Il log utente acquisisce informazioni su tutti gli script eseguiti all'interno di PowerShell Universal che sono creati dall'utente. Entrambi i file di log si trovano in `%ProgramData%\PowerShellUniversal`. ## Logging di sistema Il logging di sistema è configurato tramite le impostazioni dell'applicazione (appsettings.json) o le variabili d'ambiente. I log di sistema in genere contengono log interni utili per determinare cosa sta accadendo all'interno del server PowerShell Universal e non necessariamente nei suoi script. Le impostazioni del log di sistema si trovano nella radice di appsettings.json. ```json { "SystemLogPath": "%ProgramData%\\PowerShellUniversal", "SystemLogLevel": "Information" } ``` Il percorso del log di sistema può contenere variabili d'ambiente. I livelli di log validi includono: * Verbose * Debug * Information * Warning * Error Consigliamo di eseguire a livello Information o superiore negli ambienti di produzione e di scendere sotto tali livelli solo durante il debug dei problemi. ## Configurazione La configurazione del logging può essere modificata in **Observe > Logging > Logging Targets**. ### Target PowerShell Universal offre cinque target di logging integrati. * File * Database * TCP * HTTP * PowerShell Ogni target ha il proprio insieme di proprietà. Ad esempio, i file avranno una proprietà per il percorso del file. #### Ambito Ogni target può essere configurato per acquisire un insieme specifico di eventi di log in base a ciò che li genera. Questi includono: * Ambito - Messaggi di log di sistema o utente * Funzionalità - La funzionalità che genera il messaggio di log (ad es. API) * Risorsa - Una risorsa specifica che genera il log (ad es. Script1.ps1) Se non si specificano la funzionalità o la risorsa, il target di log riceverà tutti i messaggi per l'ambito. Ad esempio, se definisce un target con ambito Utente e funzionalità API, registrerà tutte le richieste API. #### Livello I livelli di log definiscono quali messaggi registrare in base al livello dei messaggi di log. Ad esempio, un target di logging configurato al livello Information riceverà i messaggi di log da Information fino a Error, ma non registrerà i messaggi debug o verbose. ### Target PowerShell Il target di logging PowerShell può essere utilizzato per creare un logger personalizzato con un blocco di script PowerShell che riceve i messaggi. Il blocco di script deve avere due parametri. Il primo è l'oggetto evento di log prodotto da Serilog e il secondo è la stringa del messaggio renderizzata. ```powershell New-PSULoggingTarget -Type 'PowerShell' -Level 'Information' -Scope User -Feature API -ScriptBlock { param($LogEvent, $Message) $Message | Out-File C:\logs\log.txt } ``` Consideri le prestazioni quando utilizza il target PowerShell, poiché PowerShell verrà eseguito per ogni messaggio di log. Un pool di runspace di logging viene utilizzato per fornire logging multithread per i target PowerShell. Non registri log all'interno del target PowerShell utilizzando Write-PSULog. ## Write-PSULog Può utilizzare il cmdlet `Write-PSULog` per scrivere nei log all'interno dei suoi script. Il cmdlet imposta automaticamente l'ambito Utente e può scegliere di fornire una funzionalità, una risorsa e un messaggio. ```powershell Write-PSULog -Feature 'MyFeature' -Message 'MyMessage' ``` ### Console Può consentire a `Write-PSULog` di inviare l'output ai flussi della sessione PowerShell corrente utilizzando il parametro switch `-Console`. In base al livello selezionato, i messaggi di log appariranno su tali flussi. {% 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 %} ### Runspace nidificati Se la sua soluzione crea i propri runspace, direttamente o tramite job, può continuare a utilizzare `Write-PSULog`, ma dovrà fornire la variabile globale `$UniversalClient` al runspace. {% 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 %} ## Visualizzazione dei log Può visualizzare i log in tempo reale in **Observe > Logging > Live Logs**. Il visualizzatore di log mostra per impostazione predefinita tutti i messaggi di log. Può utilizzare le opzioni di ordinamento e filtro per selezionare livelli, funzionalità e risorse specifici di cui visualizzare i log. La barra di ricerca cercherà i messaggi di log che contengono la stringa di ricerca. ## Esempio – stack ELK Può utilizzare il target di logging TCP per archiviare e analizzare i messaggi di log in ELK stack. Ai fini di questo esempio, utilizzeremo il [repository docker-elk](https://github.com/deviantony/docker-elk). Cloni il repository docker-elk ed esegua i seguenti comandi nel repository. ``` docker-compose up setup docker-compose up ``` Una volta eseguiti, avrà ELK stack in esecuzione. Può visitare la console web navigando a `http://localhost:5601`. Il nome utente predefinito è elastic e la password è changeme. In PowerShell Universal, dovrà creare un target di logging e inviare gli eventi TCP a `tcp://localhost:50000`. ```powershell New-PSULoggingTarget -Type "TCP" -Level "Verbose" -Properties @{ hostName = 'tcp://localhost' port = '50000' } -Scope "User" ``` La configurazione precedente invierà tutti i messaggi di log con ambito Utente a Logstack. Vada in **Observe > Logging > Live Logs**. Da qui potrà cercare e visualizzare i messaggi di log di Universal. --- # 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/it/sviluppo/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.