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