| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Logs a message with the specified log level and parameters. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | This function logs a message using the specified log level and parameters. |
| | | 6 | | It supports various log levels and can output the formatted message to the pipeline if requested. |
| | | 7 | | .PARAMETER Level |
| | | 8 | | The log level to use for the log event. |
| | | 9 | | .PARAMETER Message |
| | | 10 | | The message template describing the event. |
| | | 11 | | .PARAMETER LoggerName |
| | | 12 | | The name of the logger to use. |
| | | 13 | | If both LoggerName and Logger are not specified, the default logger is used. |
| | | 14 | | If neither is available, the message is broadcast to all known loggers (best-effort). |
| | | 15 | | .PARAMETER Logger |
| | | 16 | | The Serilog logger instance to use for logging. |
| | | 17 | | If not specified, the logger with the specified LoggerName or the default logger is used. |
| | | 18 | | if both Logger and LoggerName are not specified, the default logger is used. |
| | | 19 | | If neither is available, the message is broadcast to all known loggers (best-effort). |
| | | 20 | | .PARAMETER Exception |
| | | 21 | | The exception related to the event. |
| | | 22 | | .PARAMETER ErrorRecord |
| | | 23 | | The error record related to the event. |
| | | 24 | | .PARAMETER Values |
| | | 25 | | Objects positionally formatted into the message template. |
| | | 26 | | .PARAMETER PassThru |
| | | 27 | | If specified, outputs the formatted message into the pipeline. |
| | | 28 | | .INPUTS |
| | | 29 | | Message - Message template describing the event. |
| | | 30 | | .OUTPUTS |
| | | 31 | | None or Message populated with Properties into pipeline if PassThru specified. |
| | | 32 | | .EXAMPLE |
| | | 33 | | PS> Write-KrLog -Level Information -Message 'Info log message |
| | | 34 | | This example logs a simple information message. |
| | | 35 | | .EXAMPLE |
| | | 36 | | PS> Write-KrLog -Level Warning -Message 'Processed {@Position} in {Elapsed:000} ms.' -Values $position, $elapsed |
| | | 37 | | This example logs a warning message with formatted properties. |
| | | 38 | | .EXAMPLE |
| | | 39 | | PS> Write-KrLog -Level Error -Message 'Error occurred' -Exception ([System.Exception]::new('Some exception')) |
| | | 40 | | This example logs an error message with an exception. |
| | | 41 | | .NOTES |
| | | 42 | | This function is part of the Kestrun logging framework and is used to log messages at various levels. |
| | | 43 | | It can be used in scripts and modules that utilize Kestrun for logging. |
| | | 44 | | #> |
| | | 45 | | function Write-KrLog { |
| | | 46 | | [KestrunRuntimeApi('Everywhere')] |
| | | 47 | | [CmdletBinding(DefaultParameterSetName = 'LoggerName_MsgTemp')] |
| | | 48 | | param( |
| | | 49 | | [Parameter(Mandatory = $true)] |
| | | 50 | | [Serilog.Events.LogEventLevel]$Level, |
| | | 51 | | |
| | | 52 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerName_MsgTemp')] |
| | | 53 | | [Parameter(Mandatory = $false, ParameterSetName = 'LoggerName_ErrRec')] |
| | | 54 | | [Parameter(Mandatory = $false, ParameterSetName = 'LoggerName_Exception')] |
| | | 55 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerManager_MsgTemp')] |
| | | 56 | | [Parameter(Mandatory = $false, ParameterSetName = 'LoggerManager_ErrRec')] |
| | | 57 | | [Parameter(Mandatory = $false, ParameterSetName = 'LoggerManager_Exception')] |
| | | 58 | | [AllowEmptyString()] |
| | | 59 | | [AllowNull()] |
| | | 60 | | [string]$Message, |
| | | 61 | | [Parameter(Mandatory = $false, ParameterSetName = 'LoggerName_MsgTemp')] |
| | | 62 | | [Parameter(Mandatory = $false, ParameterSetName = 'LoggerName_ErrRec')] |
| | | 63 | | [Parameter(Mandatory = $false, ParameterSetName = 'LoggerName_Exception')] |
| | | 64 | | [string]$LoggerName, |
| | | 65 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerManager_MsgTemp')] |
| | | 66 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerManager_ErrRec')] |
| | | 67 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerManager_Exception')] |
| | | 68 | | [Serilog.ILogger]$Logger, |
| | | 69 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerManager_Exception')] |
| | | 70 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerName_Exception')] |
| | | 71 | | [AllowNull()] |
| | | 72 | | [System.Exception]$Exception, |
| | | 73 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerManager_ErrRec')] |
| | | 74 | | [Parameter(Mandatory = $true, ParameterSetName = 'LoggerName_ErrRec')] |
| | | 75 | | [AllowNull()] |
| | | 76 | | [System.Management.Automation.ErrorRecord]$ErrorRecord, |
| | | 77 | | [Parameter(Mandatory = $false)] |
| | | 78 | | [AllowNull()] |
| | | 79 | | [object[]]$Values, |
| | | 80 | | [Parameter(Mandatory = $false)] |
| | | 81 | | [switch]$PassThru |
| | | 82 | | ) |
| | | 83 | | process { |
| | | 84 | | try { |
| | | 85 | | # If ErrorRecord is available wrap it into RuntimeException |
| | 0 | 86 | | if ($null -ne $ErrorRecord) { |
| | | 87 | | |
| | 0 | 88 | | if ($null -eq $Exception) { |
| | | 89 | | # If Exception is not provided, use the ErrorRecord's Exception |
| | 0 | 90 | | $Exception = $ErrorRecord.Exception |
| | | 91 | | } |
| | | 92 | | |
| | 0 | 93 | | $Exception = [Kestrun.Logging.Exceptions.WrapperException]::new($Exception, $ErrorRecord) |
| | | 94 | | } |
| | 0 | 95 | | if ($Null -eq $Logger) { |
| | 0 | 96 | | if ([string]::IsNullOrEmpty($LoggerName)) { |
| | | 97 | | # If LoggerName is not specified, use the default logger |
| | 0 | 98 | | if ([Kestrun.Logging.LoggerManager]::DefaultLogger.GetType().FullName -eq 'Serilog.Core.Pipeline.Sil |
| | | 99 | | # If the default logger is a SilentLogger, it means no logger is configured |
| | | 100 | | return |
| | | 101 | | } |
| | 0 | 102 | | $Logger = [Kestrun.Logging.LoggerManager]::DefaultLogger |
| | | 103 | | } else { |
| | | 104 | | # If LoggerName is specified, get the logger with that name |
| | 0 | 105 | | $Logger = [Kestrun.Logging.LoggerManager]::Get($LoggerName) |
| | | 106 | | } |
| | | 107 | | } |
| | | 108 | | # If still no concrete logger resolve: broadcast to all known loggers (best-effort) |
| | 0 | 109 | | if ($null -eq $Logger) { |
| | 0 | 110 | | $all = [Kestrun.Logging.LoggerManager]::ListLoggers() |
| | 0 | 111 | | if ($all.Length -eq 0) { return } |
| | 0 | 112 | | foreach ($l in $all) { |
| | 0 | 113 | | if ($null -ne $l) { |
| | 0 | 114 | | switch ($Level) { |
| | 0 | 115 | | Verbose { $l.Verbose($Exception, $Message, $Values) } |
| | 0 | 116 | | Debug { $l.Debug($Exception, $Message, $Values) } |
| | 0 | 117 | | Information { $l.Information($Exception, $Message, $Values) } |
| | 0 | 118 | | Warning { $l.Warning($Exception, $Message, $Values) } |
| | 0 | 119 | | Error { $l.Error($Exception, $Message, $Values) } |
| | 0 | 120 | | Fatal { $l.Fatal($Exception, $Message, $Values) } |
| | | 121 | | } |
| | | 122 | | } |
| | | 123 | | } |
| | 0 | 124 | | if ($PassThru) { Get-KrFormattedMessage -Logger ([Kestrun.Logging.LoggerManager]::DefaultLogger) -Level |
| | | 125 | | return |
| | | 126 | | } |
| | | 127 | | # Log the message using the specified log level and parameters |
| | 0 | 128 | | switch ($Level) { |
| | | 129 | | Verbose { |
| | 0 | 130 | | $Logger.Verbose($Exception, $Message, $Values) |
| | | 131 | | } |
| | | 132 | | Debug { |
| | 0 | 133 | | $Logger.Debug($Exception, $Message, $Values) |
| | | 134 | | } |
| | | 135 | | Information { |
| | 0 | 136 | | $Logger.Information($Exception, $Message, $Values) |
| | | 137 | | } |
| | | 138 | | Warning { |
| | 0 | 139 | | $Logger.Warning($Exception, $Message, $Values) |
| | | 140 | | } |
| | | 141 | | Error { |
| | 0 | 142 | | $Logger.Error($Exception, $Message, $Values) |
| | | 143 | | } |
| | | 144 | | Fatal { |
| | 0 | 145 | | $Logger.Fatal($Exception, $Message, $Values) |
| | | 146 | | } |
| | | 147 | | } |
| | | 148 | | # If PassThru is specified, output the formatted message into the pipeline |
| | | 149 | | # This allows the caller to capture the formatted message if needed |
| | 0 | 150 | | if ($PassThru) { |
| | 0 | 151 | | Get-KrFormattedMessage -Logger $Logger -Level $Level -Message $Message -Values $Values -Exception $Excep |
| | | 152 | | } |
| | | 153 | | } catch { |
| | | 154 | | # If an error occurs while logging, write to the default logger |
| | 0 | 155 | | $defaultLogger = [Kestrun.Logging.LoggerManager]::DefaultLogger |
| | 0 | 156 | | if ($null -ne $defaultLogger) { |
| | 0 | 157 | | $defaultLogger.Error($_, 'Error while logging message: {Message}', $Message) |
| | | 158 | | } else { |
| | 0 | 159 | | Write-Error "Error while logging message: $_" |
| | | 160 | | } |
| | 0 | 161 | | throw $_ |
| | | 162 | | } |
| | | 163 | | } |
| | | 164 | | } |