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>
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
- Avoid blocking: Don't block the calling thread for I/O operations.
- Lazy evaluation: Remember that messages and metadata are autoclosures.
- Memory efficiency: Don't hold onto large amounts of messages.
See Also
LogHandlerStreamLogHandlerMultiplexLogHandler