Logging

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 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 i dettagli di log relativi al server PowerShell Universal ed è impostato su verbose per impostazione predefinita. Il secondo è il log utente. Il log utente acquisisce le informazioni su tutti gli script eseguiti all'interno di PowerShell Universal creati dall'utente.

Entrambi i file di log si trovano in %ProgramData%\PowerShellUniversal.

Logging di sistema

Il logging di sistema viene configurato tramite le impostazioni dell'applicazione (appsettings.json) o le variabili di ambiente. I log di sistema contengono in genere il logging interno utile 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.

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

Il percorso del log di sistema può contenere variabili di ambiente. I livelli di log validi includono:

• Verbose
• Debug
• Information
• Warning
• Error

Consigliamo di eseguire con il livello Information o superiore negli ambienti di produzione e di scendere al di sotto di tali livelli solo durante il debug dei problemi.

Configurazione

La configurazione del logging può essere modificata nella pagina Impostazioni \ Logging.

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à relativa al percorso del file.

Ambito

Ogni target può essere configurato per acquisire uno specifico insieme di eventi di log in base a ciò che li genera. Questi includono:

• Scope - Messaggi di log di sistema o utente
• Feature - La funzionalità che genera il messaggio di log (ad es. API)
• Resource - Una risorsa specifica che genera il log (ad es. Script1.ps1)

Se non vengono specificate la funzionalità o la risorsa, il target di log riceverà tutti i messaggi relativi all'ambito. Ad esempio, se definisse un target con ambito User e funzionalità API, verrebbero registrate 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 sul 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 renderizzato.

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

Tenga conto delle prestazioni quando utilizza il target PowerShell, poiché PowerShell verrà eseguito per ogni messaggio di log. Viene utilizzato un pool di runspace di logging per fornire un logging multithread per i target PowerShell.

Non registri log all'interno del suo target PowerShell utilizzando Write-PSULog.

Write-PSULog

Può utilizzare il cmdlet Write-PSULog per scrivere nei log dall'interno dei suoi script. Il cmdlet imposta automaticamente l'ambito User e lei può scegliere di fornire una funzionalità, una risorsa e un messaggio.

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

Console

Può consentire a Write-PSULog di inviare l'output agli stream della sessione PowerShell corrente utilizzando il parametro switch -Console. A seconda del livello selezionato, i messaggi di log appariranno su tali stream.

# 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

Runspace annidati

Se la sua soluzione crea i propri runspace, direttamente o tramite job, può continuare a utilizzare Write-PSULog, ma dovrà fornire al runspace la variabile globale $UniversalClient.

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

Visualizzazione dei log

Può visualizzare i log accedendo a Platform \ Logging. Il visualizzatore di log mostrerà tutti i messaggi di log per impostazione predefinita. 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 contenenti la stringa di ricerca.

Visualizzatore di log

Esempio: stack ELK

Può utilizzare il target di logging TCP per archiviare e analizzare i messaggi di log nello stack ELK. Ai fini di questo esempio, utilizzeremo il repository docker-elk.

Cloni il repository docker-elk ed esegua i comandi seguenti nel repository.

docker-compose up setup
docker-compose up

Una volta eseguiti, avrà lo stack ELK in esecuzione. Può accedere alla 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.

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

La configurazione sopra riportata invierà tutti i messaggi di log dell'ambito User a Logstack con la connessione TCP. Nella sezione Observability della console, navighi alla pagina Logs \ Stream.

Da qui potrà cercare e visualizzare i messaggi di log di Universal.