Add option to pass Errors to log functions

Motivation:

Addresses #291

Modifications:

Add new API to Logger, that allows the caller to pass an Error object to any log function. Extend LogHandler to allow an implementation to access the error, in order to format the log appropriately. Provide default implementaions to preserve backwards compatibility.

Result:

By providing default implementations, the change should be compatible between old and new code, both from the API and implementation side. I.e. a client can use the new API and it will still work with 'old' implementations, and vice versa.

Author: samuelmurray

Sources/Logging/LogHandler.swift

@@ -136,6 +136,20 @@ public protocol LogHandler: _SwiftLogSendableLogHandler {
     ///     - file: The file the log message was emitted from.
     ///     - function: The function the log line was emitted from.
     ///     - line: The line the log message was emitted from.
+    func log(
+        level: Logger.Level,
+        message: Logger.Message,
+        error: Error?,
+        metadata: Logger.Metadata?,
+        source: String,
+        file: String,
+        function: String,
+        line: UInt
+    )
+    
+    /// SwiftLog 1.6 compatibility method. Please do _not_ implement, implement
+    /// `log(level:message:error:metadata:source:file:function:line:)` instead.
+    @available(*, deprecated, renamed: "log(level:message:error:metadata:source:file:function:line:)")
     func log(
         level: Logger.Level,
         message: Logger.Message,
@@ -147,8 +161,8 @@ public protocol LogHandler: _SwiftLogSendableLogHandler {
     )
 
     /// SwiftLog 1.0 compatibility method. Please do _not_ implement, implement
-    /// `log(level:message:metadata:source:file:function:line:)` instead.
-    @available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
+    /// `log(level:message:error:metadata:source:file:function:line:)` instead.
+    @available(*, deprecated, renamed: "log(level:message:error:metadata:source:file:function:line:)")
     func log(
         level: Logging.Logger.Level,
         message: Logging.Logger.Message,
@@ -196,6 +210,7 @@ extension LogHandler {
                     level: .warning,
                     message:
                         "Attempted to set metadataProvider on \(Self.self) that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.",
+                    error: nil,
                     metadata: nil,
                     source: "Logging",
                     file: #file,
@@ -210,6 +225,20 @@ extension LogHandler {
 
 extension LogHandler {
     @available(*, deprecated, message: "You should implement this method instead of using the default implementation")
+    public func log(
+        level: Logger.Level,
+        message: Logger.Message,
+        error: Error?,
+        metadata: Logger.Metadata?,
+        source: String,
+        file: String,
+        function: String,
+        line: UInt
+    ) {
+        self.log(level: level, message: message, metadata: metadata, source: source, file: file, function: function, line: line)
+    }
+    
+    @available(*, deprecated, renamed: "log(level:message:error:metadata:source:file:function:line:)")
     public func log(
         level: Logger.Level,
         message: Logger.Message,
@@ -222,7 +251,7 @@ extension LogHandler {
         self.log(level: level, message: message, metadata: metadata, file: file, function: function, line: line)
     }
 
-    @available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
+    @available(*, deprecated, renamed: "log(level:message:error:metadata:source:file:function:line:)")
     public func log(
         level: Logging.Logger.Level,
         message: Logging.Logger.Message,
@@ -234,6 +263,7 @@ extension LogHandler {
         self.log(
             level: level,
             message: message,
+            error: nil,
             metadata: metadata,
             source: Logger.currentModule(filePath: file),
             file: file,