Files
swift-log/Sources/Logging/Docs.docc/ImplementingALogHandler.md
T
4121d24dbd documentation update and re-organization (#381)
Provide organization (aka curation) and abstracts for all of the public
types in the library.

### Motivation:

Updates to the documentation to fill in the missing abstracts for the
provided types, updating the language to follow Apple developer content
guidelines, and fixing smaller typos and grammar issues.

### Modifications:

Curation files added to provide organization for public types, ordering
the content to align with the narrative content provided earlier.
Updating API comments, adding abstracts and parameters where missing,
and moving some of the getting started content that was previously in
the main index into a separate article.

### Result:

starting point

```
   --- Experimental coverage output enabled. ---
                | Abstract        | Curated         | Code Listing
Types           | 69% (11/16)     | 38% (6/16)      | 25% (4/16)
Members         | 57% (54/94)     | 3.2% (3/94)     | 0.0% (0/94)
Globals         | 7.1% (1/14)     | 7.1% (1/14)     | 7.1% (1/14)
```

Updated:

```
                | Abstract        | Curated         | Code Listing
Types           | 94% (15/16)     | 94% (15/16)     | 38% (6/16)
Members         | 85% (80/94)     | 97% (91/94)     | 0.0% (0/94)
Globals         | 14% (2/14)      | 100% (14/14)    | 7.1% (1/14)
```

---------

Co-authored-by: Honza Dvorsky <honza@apple.com>
Co-authored-by: Franz Busch <privat@franz-busch.de>
2025-11-03 11:26:54 -08:00

6.0 KiB

Implementing a log handler

Create a custom logging backend that provides logging services for your apps and libraries.

Overview

To become a compatible logging backend that any SwiftLog consumer can use, you need to fulfill a few requirements, primarily conforming to the LogHandler protocol.

Implement with value type semantics

Your log handler must be a struct and exhibit value semantics. This ensures that changes to one logger don't affect others.

To verify that your handler reflects value semantics ensure that it passes this test:

@Test
func logHandlerValueSemantics() {
    LoggingSystem.bootstrap(MyLogHandler.init)
    var logger1 = Logger(label: "first logger")
    logger1.logLevel = .debug
    logger1[metadataKey: "only-on"] = "first"
    
    var logger2 = logger1
    logger2.logLevel = .error                  // Must not affect logger1
    logger2[metadataKey: "only-on"] = "second" // Must not affect logger1
    
    // These expectations must pass
    #expect(logger1.logLevel == .debug)
    #expect(logger2.logLevel == .error)
    #expect(logger1[metadataKey: "only-on"] == "first")
    #expect(logger2[metadataKey: "only-on"] == "second")
}

Note: In special cases, it is acceptable for a log handler to provide global log level overrides that may affect all log handlers created.

Example implementation

Here's a complete example of a simple print-based log handler:

import Foundation
import Logging

public struct PrintLogHandler: LogHandler {
    private let label: String
    public var logLevel: Logger.Level = .info
    public var metadata: Logger.Metadata = [:]
    
    public init(label: String) {
        self.label = label
    }
    
    public func log(
        level: Logger.Level,
        message: Logger.Message,
        metadata: Logger.Metadata?,
        source: String,
        file: String,
        function: String,
        line: UInt
    ) {
        let timestamp = ISO8601DateFormatter().string(from: Date())
        let levelString = level.rawValue.uppercased()
        
        // Merge handler metadata with message metadata
        let combinedMetadata = Self.prepareMetadata(
            base: self.metadata
            explicit: metadata
        )
        
        // Format metadata
        let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
        
        // Create log line and print to console
        let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
        print(logLine)
    }
    
    public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
        get {
            return self.metadata[key]
        }
        set {
            self.metadata[key] = newValue
        }
    }

    static func prepareMetadata(
        base: Logger.Metadata,
        explicit: Logger.Metadata?
    ) -> Logger.Metadata? {
        var metadata = base

        guard let explicit else {
            // all per-log-statement values are empty
            return metadata
        }

        metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })

        return metadata
    }
}

Advanced features

Metadata providers

Metadata providers allow you to dynamically add contextual information to all log messages without explicitly passing it each time. Common use cases include request IDs, user sessions, or trace contexts that should be included in logs throughout a request's lifecycle.

import Foundation
import Logging

public struct PrintLogHandler: LogHandler {
    private let label: String
    public var logLevel: Logger.Level = .info
    public var metadata: Logger.Metadata = [:]
    public var metadataProvider: Logger.MetadataProvider?
    
    public init(label: String) {
        self.label = label
    }
    
    public func log(
        level: Logger.Level,
        message: Logger.Message,
        metadata: Logger.Metadata?,
        source: String,
        file: String,
        function: String,
        line: UInt
    ) {
        let timestamp = ISO8601DateFormatter().string(from: Date())
        let levelString = level.rawValue.uppercased()
        
        // Get provider metadata
        let providerMetadata = metadataProvider?.get() ?? [:]

        // Merge handler metadata with message metadata
        let combinedMetadata = Self.prepareMetadata(
            base: self.metadata,
            provider: self.metadataProvider,
            explicit: metadata
        )
        
        // Format metadata
        let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
        
        // Create log line and print to console
        let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
        print(logLine)
    }
    
    public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
        get {
            return self.metadata[key]
        }
        set {
            self.metadata[key] = newValue
        }
    }

    static func prepareMetadata(
        base: Logger.Metadata,
        provider: Logger.MetadataProvider?,
        explicit: Logger.Metadata?
    ) -> Logger.Metadata? {
        var metadata = base

        let provided = provider?.get() ?? [:]

        guard !provided.isEmpty || !((explicit ?? [:]).isEmpty) else {
            // all per-log-statement values are empty
            return metadata
        }

        if !provided.isEmpty {
            metadata.merge(provided, uniquingKeysWith: { _, provided in provided })
        }

        if let explicit = explicit, !explicit.isEmpty {
            metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
        }

        return metadata
    }
}

Performance considerations

  1. Avoid blocking: Don't block the calling thread for I/O operations.
  2. Lazy evaluation: Remember that messages and metadata are autoclosures.
  3. Memory efficiency: Don't hold onto large amounts of messages.

See Also

  • LogHandler
  • StreamLogHandler
  • MultiplexLogHandler