Registro

Acerca de

PowerShell Universal utiliza un marco de registro estructurado llamado Serilog. Serilog permite múltiples destinos de registro (sinks), propiedades de eventos de registro y almacenamiento de los datos de los eventos de registro. De forma predeterminada, PowerShell Universal registra dos ficheros de registro diferentes. El primero es el registro del sistema. Este contiene detalles de registro sobre el servidor de PowerShell Universal y está configurado como verbose de forma predeterminada. El segundo es el registro de usuario. El registro de usuario captura información sobre todos los scripts ejecutados dentro de PowerShell Universal que han sido creados por el usuario.

Ambos ficheros de registro se encuentran en %ProgramData%\PowerShellUniversal.

Registro del sistema

El registro del sistema se configura mediante la configuración de la aplicación (appsettings.json) o variables de entorno. Los registros del sistema normalmente contienen el registro interno que resulta útil para determinar qué está ocurriendo dentro del servidor de PowerShell Universal y no necesariamente en sus scripts.

La configuración del registro del sistema se encuentra en la raíz de appsettings.json.

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

La ruta del registro del sistema puede contener variables de entorno. Los niveles de registro válidos incluyen:

• Verbose
• Debug
• Information
• Warning
• Error

Recomendamos ejecutar en Information o superior en entornos de producción y bajar de esos niveles únicamente al depurar problemas.

Configuración

La configuración del registro se puede cambiar en Observar > Registro > Destinos de registro.

Destinos

PowerShell Universal ofrece cinco destinos de registro integrados.

• Fichero
• Base de datos
• TCP
• HTTP
• PowerShell

Cada destino tiene su propio conjunto de propiedades. Por ejemplo, los ficheros tendrán una propiedad de ruta de fichero.

Ámbito

Cada destino se puede configurar para capturar un conjunto específico de eventos de registro en función de lo que los genera. Estos incluyen:

• Scope - Mensajes de registro del sistema o de usuario
• Feature - La función que genera el mensaje de registro (p. ej., API)
• Resource - Un recurso específico que genera el registro (p. ej., Script1.ps1)

Si no se especifica feature o resource, el destino de registro recibirá todos los mensajes del ámbito. Por ejemplo, si define un destino con un ámbito User y una función API, registraría todas las solicitudes de API.

Nivel

Los niveles de registro definen qué mensajes registrar en función del nivel de los mensajes de registro. Por ejemplo, un destino de registro configurado en el nivel Information recibirá mensajes de registro desde Information hasta Error, pero no registrará mensajes debug o verbose.

Destino de PowerShell

El destino de registro de PowerShell se puede utilizar para crear un registrador personalizado con un bloque de script de PowerShell que reciba los mensajes. El bloque de script debe tener dos parámetros. El primero es el objeto de evento de registro producido por Serilog y el segundo es la cadena del mensaje renderizado.

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

Tenga en cuenta el rendimiento al utilizar el destino de PowerShell, ya que PowerShell se ejecutará para cada mensaje de registro. Se utiliza un grupo de runspaces de registro para proporcionar registro multihilo a los destinos de PowerShell.

No registre dentro de su destino de PowerShell utilizando Write-PSULog.

Write-PSULog

Puede utilizar el cmdlet Write-PSULog para escribir en los registros desde sus scripts. El cmdlet establece automáticamente el ámbito User y puede elegir proporcionar una función, un recurso y un mensaje.

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

Consola

Puede permitir que Write-PSULog genere salida en los flujos de la sesión de PowerShell actual utilizando el parámetro de conmutador -Console. Según el nivel que seleccione, los mensajes de registro aparecerán en esos flujos.

# 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 anidados

Si su solución crea sus propios espacios de ejecución (runspaces), ya sea directamente o mediante trabajos, puede seguir utilizando Write-PSULog, pero deberá proporcionar la variable global $UniversalClient al espacio de ejecución.

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

Visualización de registros

Puede ver los registros en directo en Observar > Registro > Registros en directo. El visor de registros mostrará todos los mensajes de registro de forma predeterminada. Puede utilizar las opciones de ordenación y filtrado para seleccionar niveles, funciones y recursos concretos para los que ver los registros.

La barra de búsqueda buscará mensajes de registro que contengan la cadena de búsqueda.

Visor de registros

Ejemplo: ELK Stack

Puede utilizar el destino de registro TCP para almacenar y analizar mensajes de registro en ELK stack. A efectos de este ejemplo, utilizaremos el repositorio docker-elk.

Clone el repositorio docker-elk y ejecute los siguientes comandos en el repositorio.

docker-compose up setup
docker-compose up

Una vez ejecutado, tendrá ELK stack en funcionamiento. Puede visitar la consola web navegando a http://localhost:5601.

El nombre de usuario predeterminado es elastic y la contraseña es changeme.

En PowerShell Universal, querrá crear un destino de registro y enviar los eventos TCP a tcp://localhost:50000.

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

La configuración anterior enviará todos los mensajes de registro del ámbito de usuario a Logstack. Vaya a Observar > Registro > Registros en directo.

Desde aquí podrá buscar y ver los mensajes de registro de Universal.