diff --git a/Snippets/basic-usage.swift b/Snippets/basic-usage.swift new file mode 100644 index 0000000..a3274c2 --- /dev/null +++ b/Snippets/basic-usage.swift @@ -0,0 +1,8 @@ +// Import the logging API +import Logging + +// Create a logger with a label +let logger = Logger(label: "MyLogger") + +// Use it to log messages +logger.info("Hello World!") diff --git a/Sources/Logging/Docs.docc/ImplementingALogHandler.md b/Sources/Logging/Docs.docc/ImplementingALogHandler.md index cd4a17d..0b3a8bc 100644 --- a/Sources/Logging/Docs.docc/ImplementingALogHandler.md +++ b/Sources/Logging/Docs.docc/ImplementingALogHandler.md @@ -1,11 +1,10 @@ # Implementing a log handler -Create a custom logging backend that provides logging services for your apps -and libraries. +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, +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. diff --git a/Sources/Logging/Docs.docc/Reference/LogHandler.md b/Sources/Logging/Docs.docc/Reference/LogHandler.md new file mode 100644 index 0000000..2626ca0 --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/LogHandler.md @@ -0,0 +1,20 @@ +# ``Logging/LogHandler`` + +## Topics + +### Sending log messages + +- ``log(level:message:metadata:source:file:function:line:)-8kgt7`` +- ``log(level:message:metadata:source:file:function:line:)-69pez`` +- ``log(level:message:metadata:file:function:line:)-89rya`` +- ``log(level:message:metadata:file:function:line:)-1xdau`` + +### Updating metadata + +- ``subscript(metadataKey:)`` + +### Inspecting a log handler + +- ``logLevel`` +- ``metadata`` +- ``metadataProvider`` diff --git a/Sources/Logging/Docs.docc/Reference/Logger-Level.md b/Sources/Logging/Docs.docc/Reference/Logger-Level.md new file mode 100644 index 0000000..f7c4808 --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/Logger-Level.md @@ -0,0 +1,13 @@ +# ``Logging/Logger/Level`` + +## Topics + +### Log Levels + +- ``trace`` +- ``debug`` +- ``info`` +- ``notice`` +- ``warning`` +- ``error`` +- ``critical`` diff --git a/Sources/Logging/Docs.docc/Reference/Logger-Message.md b/Sources/Logging/Docs.docc/Reference/Logger-Message.md new file mode 100644 index 0000000..1ea82d1 --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/Logger-Message.md @@ -0,0 +1,12 @@ +# ``Logging/Logger/Message`` + +## Topics + +### Creating a log message + +- ``init(stringLiteral:)`` + +### Inspecting a log message + +- ``description`` + diff --git a/Sources/Logging/Docs.docc/Reference/Logger-MetadataProvider.md b/Sources/Logging/Docs.docc/Reference/Logger-MetadataProvider.md new file mode 100644 index 0000000..1d2a039 --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/Logger-MetadataProvider.md @@ -0,0 +1,15 @@ +# ``Logging/Logger/MetadataProvider`` + +## Topics + +### Creating a metadata provider + +- ``init(_:)`` + +### Invoking the provider + +- ``get()`` + +### Merging metadata + +- ``multiplex(_:)`` diff --git a/Sources/Logging/Docs.docc/Reference/Logger-MetadataValue.md b/Sources/Logging/Docs.docc/Reference/Logger-MetadataValue.md new file mode 100644 index 0000000..9b8e30f --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/Logger-MetadataValue.md @@ -0,0 +1,11 @@ +# ``Logging/Logger/MetadataValue`` + +## Topics + +### Types of metadata values + +- ``string(_:)`` +- ``stringConvertible(_:)`` +- ``array(_:)`` +- ``dictionary(_:)`` + diff --git a/Sources/Logging/Docs.docc/Reference/Logger.md b/Sources/Logging/Docs.docc/Reference/Logger.md new file mode 100644 index 0000000..ccd6089 --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/Logger.md @@ -0,0 +1,60 @@ +# ``Logging/Logger`` + +## Topics + +### Creating Loggers + +- ``init(label:)`` +- ``init(label:metadataProvider:)`` +- ``init(label:factory:)-9uiy2`` +- ``init(label:factory:)-6iktu`` +- ``MetadataProvider`` + +### Sending trace log messages + +- ``trace(_:metadata:file:function:line:)`` +- ``trace(_:metadata:source:file:function:line:)`` + +### Sending debug log messages +- ``debug(_:metadata:file:function:line:)`` +- ``debug(_:metadata:source:file:function:line:)`` + +### Sending info log messages +- ``info(_:metadata:file:function:line:)`` +- ``info(_:metadata:source:file:function:line:)`` + +### Sending notice log messages +- ``notice(_:metadata:file:function:line:)`` +- ``notice(_:metadata:source:file:function:line:)`` + +### Sending warning log messages +- ``warning(_:metadata:file:function:line:)`` +- ``warning(_:metadata:source:file:function:line:)`` + +### Sending error log messages +- ``error(_:metadata:file:function:line:)`` +- ``error(_:metadata:source:file:function:line:)`` + +### Sending critical log messages +- ``critical(_:metadata:file:function:line:)`` +- ``critical(_:metadata:source:file:function:line:)`` + +### Sending general log messages + +- ``log(level:_:metadata:file:function:line:)`` +- ``log(level:_:metadata:source:file:function:line:)`` +- ``Level`` +- ``Message`` +- ``Metadata`` + +### Adjusting logger metadata + +- ``subscript(metadataKey:)`` +- ``MetadataValue`` + +### Inspecting a logger + +- ``label`` +- ``logLevel`` +- ``handler`` +- ``metadataProvider`` diff --git a/Sources/Logging/Docs.docc/Reference/LoggingSystem.md b/Sources/Logging/Docs.docc/Reference/LoggingSystem.md new file mode 100644 index 0000000..c3ab6ff --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/LoggingSystem.md @@ -0,0 +1,13 @@ +# ``Logging/LoggingSystem`` + +## Topics + +### Initializing the logging system + +- ``bootstrap(_:)`` +- ``bootstrap(_:metadataProvider:)`` + +### Inspecting the logging system + +- ``metadataProvider`` + diff --git a/Sources/Logging/Docs.docc/Reference/MultiplexLogHandler.md b/Sources/Logging/Docs.docc/Reference/MultiplexLogHandler.md new file mode 100644 index 0000000..d336015 --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/MultiplexLogHandler.md @@ -0,0 +1,22 @@ +# ``Logging/MultiplexLogHandler`` + +## Topics + +### Creating a multiplex log handler + +- ``init(_:)`` +- ``init(_:metadataProvider:)`` + +### Sending log messages + +- ``log(level:message:metadata:source:file:function:line:)`` + +### Updating metadata + +- ``subscript(metadataKey:)`` + +### Inspecting a log handler + +- ``logLevel`` +- ``metadata`` +- ``metadataProvider`` diff --git a/Sources/Logging/Docs.docc/Reference/StreamLogHandler.md b/Sources/Logging/Docs.docc/Reference/StreamLogHandler.md new file mode 100644 index 0000000..74d12ca --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/StreamLogHandler.md @@ -0,0 +1,24 @@ +# ``Logging/StreamLogHandler`` + +## Topics + +### Creating a stream log handler + +- ``standardOutput(label:)`` +- ``standardOutput(label:metadataProvider:)`` +- ``standardError(label:)`` +- ``standardError(label:metadataProvider:)`` + +### Sending log messages + +- ``log(level:message:metadata:source:file:function:line:)`` + +### Updating metadata + +- ``subscript(metadataKey:)`` + +### Inspecting a log handler + +- ``logLevel`` +- ``metadata`` +- ``metadataProvider`` diff --git a/Sources/Logging/Docs.docc/Reference/SwiftLogNoOpLogHandler.md b/Sources/Logging/Docs.docc/Reference/SwiftLogNoOpLogHandler.md new file mode 100644 index 0000000..39fcf28 --- /dev/null +++ b/Sources/Logging/Docs.docc/Reference/SwiftLogNoOpLogHandler.md @@ -0,0 +1,22 @@ +# ``Logging/SwiftLogNoOpLogHandler`` + +## Topics + +### Creating a Swift Log no-op log handler + +- ``init()`` +- ``init(_:)`` + +### Sending log messages + +- ``log(level:message:metadata:source:file:function:line:)`` + +### Updating metadata + +- ``subscript(metadataKey:)`` + +### Inspecting a log handler + +- ``logLevel`` +- ``metadata`` +- ``metadataProvider`` diff --git a/Sources/Logging/Docs.docc/UnderstandingLoggers.md b/Sources/Logging/Docs.docc/UnderstandingLoggers.md new file mode 100644 index 0000000..a785385 --- /dev/null +++ b/Sources/Logging/Docs.docc/UnderstandingLoggers.md @@ -0,0 +1,86 @@ +# Understanding Loggers and Log Handlers + +Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages. + +## Overview + +Create or retrieve a logger to get an instance for logging messages. +Log messages have a level that you use to indicate the message's importance. + +SwiftLog defines seven log levels, represented by ``Logger/Level``, ordered from least to +most severe: + +- ``Logger/Level/trace`` +- ``Logger/Level/debug`` +- ``Logger/Level/info`` +- ``Logger/Level/notice`` +- ``Logger/Level/warning`` +- ``Logger/Level/error`` +- ``Logger/Level/critical`` + +Once a message is sent to a logger, a log handler processes it. +The app using the logger configures the handler, usually for the environment in which that app runs, processing messages appropriate to that environment. +If the app doesn't provide its own log handler, SwiftLog defaults to using a ``StreamLogHandler`` that outputs log messages to `STDOUT`. + +### Loggers + +Loggers are used to emit log messages at different severity levels: + +```swift +// Informational message +logger.info("Processing request") + +// Something went wrong +logger.error("Houston, we have a problem") +``` + +``Logger`` is a value type with value semantics, meaning that when you modify a +logger's configuration (like its log level or metadata), it only affects that +specific logger instance: + +```swift +let baseLogger = Logger(label: "MyApp") + +// Create a new logger with different configuration. +var requestLogger = baseLogger +requestLogger.logLevel = .debug +requestLogger[metadataKey: "request-id"] = "\(UUID())" + +// baseLogger is unchanged. It still has default log level and no metadata +// requestLogger has debug level and request-id metadata. +``` + +This value type behavior makes loggers safe to pass between functions and modify +without unexpected side effects. + +### Log Levels + +Log levels can be changed per logger without affecting others: + +```swift +var logger = Logger(label: "MyLogger") +logger.logLevel = .debug +``` + +For guidance on what level to use for a message, see . + +### Logging Metadata + +Metadata provides contextual information crucial for debugging: + +```swift +var logger = Logger(label: "com.example.server") +logger[metadataKey: "request.id"] = "\(UUID())" +logger.info("Processing request") +``` + +Output: +``` +2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request +``` + +### Source vs Label + +A ``Logger`` has an immutable `label` that identifies its creator, while each log +message carries a `source` parameter that identifies where the message originated. +Use `source` for filtering messages from specific subsystems. diff --git a/Sources/Logging/Docs.docc/index.md b/Sources/Logging/Docs.docc/index.md index dd45885..c8b047d 100644 --- a/Sources/Logging/Docs.docc/index.md +++ b/Sources/Logging/Docs.docc/index.md @@ -19,8 +19,8 @@ libraries. ## Getting Started -Use this If you are writing a cross-platform application (for example, Linux and -macOS) or library, target this logging API. +Use this package if you're writing a cross-platform application (for example, Linux and +macOS) or library, and want to target this logging API. ### Adding the Dependency @@ -56,7 +56,7 @@ logger.info("Hello World!") This outputs: ``` -2019-03-13T15:46:38+0000 info: Hello World! +2025-10-24T17:26:47-0700 info MyLogger: [your_app] Hello World! ``` ### Default Behavior @@ -72,83 +72,12 @@ LoggingSystem.bootstrap(StreamLogHandler.standardError) implement the ``LogHandler`` protocol directly or use a community-maintained backend. -## Core Concepts - -### Loggers - -Loggers are used to emit log messages at different severity levels: - -```swift -// Informational message -logger.info("Processing request") - -// Something went wrong -logger.error("Houston, we have a problem") -``` - -``Logger`` is a value type with value semantics, meaning that when you modify a -logger's configuration (like its log level or metadata), it only affects that -specific logger instance: - -```swift -let baseLogger = Logger(label: "MyApp") - -// Create a new logger with different configuration. -var requestLogger = baseLogger -requestLogger.logLevel = .debug -requestLogger[metadataKey: "request-id"] = "\(UUID())" - -// baseLogger is unchanged. It still has default log level and no metadata -// requestLogger has debug level and request-id metadata. -``` - -This value type behavior makes loggers safe to pass between functions and modify -without unexpected side effects. - -### Log Levels - -SwiftLog supports seven log levels (from least to most severe): -- ``Logger/Level/trace`` -- ``Logger/Level/debug`` -- ``Logger/Level/info`` -- ``Logger/Level/notice`` -- ``Logger/Level/warning`` -- ``Logger/Level/error`` -- ``Logger/Level/critical`` - -Log levels can be changed per logger without affecting others: - -```swift -var logger = Logger(label: "MyLogger") -logger.logLevel = .debug -``` - -### Logging Metadata - -Metadata provides contextual information crucial for debugging: - -```swift -var logger = Logger(label: "com.example.server") -logger[metadataKey: "request-uuid"] = "\(UUID())" -logger.info("Processing request") -``` - -Output: -``` -2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request -``` - -### Source vs Label - -A ``Logger`` has an immutable `label` identifying its creator, while each log -message carries a `source` parameter identifying where the message originated. -Use `source` for filtering messages from specific subsystems. - ## Topics ### Logging API +- - ``Logger`` - ``LoggingSystem`` @@ -162,5 +91,4 @@ Use `source` for filtering messages from specific subsystems. ### Best Practices - -- - +- diff --git a/Sources/Logging/LogHandler.swift b/Sources/Logging/LogHandler.swift index 709ceb4..8f3194f 100644 --- a/Sources/Logging/LogHandler.swift +++ b/Sources/Logging/LogHandler.swift @@ -12,19 +12,19 @@ // //===----------------------------------------------------------------------===// -/// A `LogHandler` is an implementation of a logging backend. +/// A log handler provides an implementation of a logging backend. /// -/// This type is an implementation detail and should not normally be used, unless implementing your own logging backend. +/// This type is an implementation detail and should not normally be used, unless you implement your own logging backend. /// To use the SwiftLog API, please refer to the documentation of ``Logger``. /// /// # Implementation requirements /// /// To implement your own `LogHandler` you should respect a few requirements that are necessary so applications work -/// as expected regardless of the selected `LogHandler` implementation. +/// as expected, regardless of the selected `LogHandler` implementation. /// /// - The ``LogHandler`` must be a `struct`. /// - The metadata and `logLevel` properties must be implemented so that setting them on a `Logger` does not affect -/// other `Logger`s. +/// other instances of `Logger`. /// /// ### Treat log level & metadata as values /// @@ -52,18 +52,21 @@ /// /// ### Special cases /// -/// In certain special cases, the log level behaving like a value on `Logger` might not be what you want. For example, -/// you might want to set the log level across _all_ `Logger`s to `.debug` when say a signal (eg. `SIGUSR1`) is received -/// to be able to debug special failures in production. This special case is acceptable but we urge you to create a -/// solution specific to your `LogHandler` implementation to achieve that. Please find an example implementation of this -/// behavior below, on reception of the signal you would call +/// In certain special cases, the log level behaving like a value on `Logger` might not be what you want. +/// For example, you might want to set the log level across _all_ `Logger`s to `.debug` when a signal +/// (for example `SIGUSR1`) is received to be able to debug special failures in production. +/// This special case is acceptable but please create a solution specific to your `LogHandler` implementation to achieve that. +/// +/// The following code illustrates an example implementation of this behavior. +/// On reception of the signal you would call /// `LogHandlerWithGlobalLogLevelOverride.overrideGlobalLogLevel = .debug`, for example. /// /// ```swift /// import class Foundation.NSLock /// /// public struct LogHandlerWithGlobalLogLevelOverride: LogHandler { -/// // the static properties hold the globally overridden log level (if overridden) +/// // The static properties hold the globally overridden +/// // log level (if overridden). /// private static let overrideLock = NSLock() /// private static var overrideLogLevel: Logger.Level? = nil /// @@ -78,21 +81,29 @@ /// } /// /// public var logLevel: Logger.Level { -/// // when we get asked for the log level, we check if it was globally overridden or not +/// // When asked for the log level, check +/// // if it was globally overridden or not. /// get { /// LogHandlerWithGlobalLogLevelOverride.overrideLock.lock() /// defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() } /// return LogHandlerWithGlobalLogLevelOverride.overrideLogLevel ?? self._logLevel /// } -/// // we set the log level whenever we're asked (note: this might not have an effect if globally -/// // overridden) +/// // Set the log level whenever asked +/// // (note: this might not have an effect if globally +/// // overridden). /// set { /// self._logLevel = newValue /// } /// } /// -/// public func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, -/// source: String, file: String, function: String, line: UInt) { +/// public func log( +/// level: Logger.Level, +/// message: Logger.Message, +/// metadata: Logger.Metadata?, +/// source: String, +/// file: String, +/// function: String, +/// line: UInt) { /// // [...] /// } /// @@ -105,7 +116,8 @@ /// } /// } /// -/// // this is the function to globally override the log level, it is not part of the `LogHandler` protocol +/// // This is the function to globally override the log level, +/// // it is not part of the `LogHandler` protocol. /// public static func overrideGlobalLogLevel(_ logLevel: Logger.Level) { /// LogHandlerWithGlobalLogLevelOverride.overrideLock.lock() /// defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() } @@ -114,28 +126,30 @@ /// } /// ``` /// -/// Please note that the above `LogHandler` will still pass the 'log level is a value' test above it iff the global log -/// level has not been overridden. And most importantly it passes the requirement listed above: A change to the log -/// level on one `Logger` should not affect the log level of another `Logger` variable. +/// > Note: The above `LogHandler` still passes the 'log level is a value' test above it if the global log +/// > level has not been overridden. Most importantly, it passes the requirement listed above: A change to the log +/// > level on one `Logger` should not affect the log level of another `Logger` variable. public protocol LogHandler: _SwiftLogSendableLogHandler { - /// The metadata provider this `LogHandler` will use when a log statement is about to be emitted. + /// The metadata provider this log handler uses when a log statement is about to be emitted. /// /// A ``Logger/MetadataProvider`` may add a constant set of metadata, /// or use task-local values to pick up contextual metadata and add it to emitted logs. var metadataProvider: Logger.MetadataProvider? { get set } - /// This method is called when a `LogHandler` must emit a log message. There is no need for the `LogHandler` to - /// check if the `level` is above or below the configured `logLevel` as `Logger` already performed this check and + /// The library calls this method when a log handler must emit a log message. + /// + /// There is no need for the `LogHandler` to check if the `level` is above or + /// below the configured `logLevel` as `Logger` already performed this check and /// determined that a message should be logged. /// - /// - parameters: - /// - level: The log level the message was logged at. - /// - message: The message to log. To obtain a `String` representation call `message.description`. - /// - metadata: The metadata associated to this log message. - /// - source: The source where the log message originated, for example the logging module. - /// - 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. + /// - Parameters: + /// - level: The log level of the message. + /// - message: The message to log. To obtain a `String` representation call `message.description`. + /// - metadata: The metadata associated to this log message. + /// - source: The source where the log message originated, for example the logging module. + /// - file: The file this log message originates from. + /// - function: The function this log message originates from. + /// - line: The line this log message originates from. func log( level: Logger.Level, message: Logger.Message, @@ -146,8 +160,18 @@ public protocol LogHandler: _SwiftLogSendableLogHandler { line: UInt ) - /// SwiftLog 1.0 compatibility method. Please do _not_ implement, implement - /// `log(level:message:metadata:source:file:function:line:)` instead. + /// SwiftLog 1.0 log compatibility method. + /// + /// Please do _not_ implement this method when you create a LogHandler implementation. + /// Implement `log(level:message:metadata:source:file:function:line:)` instead. + /// + /// - Parameters: + /// - level: The log level of the message. + /// - message: The message to log. To obtain a `String` representation call `message.description`. + /// - metadata: The metadata associated to this log message. + /// - file: The file this log message originates from. + /// - function: The function this log message originates from. + /// - line: The line this log message originates from. @available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)") func log( level: Logging.Logger.Level, @@ -183,8 +207,9 @@ public protocol LogHandler: _SwiftLogSendableLogHandler { } extension LogHandler { - /// Default implementation for `metadataProvider` which defaults to `nil`. - /// This default exists in order to facilitate source-compatible introduction of the `metadataProvider` protocol requirement. + /// Default implementation for a metadata provider that defaults to nil. + /// + /// This default exists in order to facilitate the source-compatible introduction of the `metadataProvider` protocol requirement. public var metadataProvider: Logger.MetadataProvider? { get { nil @@ -209,6 +234,15 @@ extension LogHandler { } extension LogHandler { + /// A default implementation for a log message handler that forwards the source location for the message. + /// - Parameters: + /// - level: The log level of the message. + /// - message: The message to log. To obtain a `String` representation call `message.description`. + /// - metadata: The metadata associated to this log message. + /// - source: The source where the log message originated, for example the logging module. + /// - file: The file this log message originates from. + /// - function: The function this log message originates from. + /// - line: The line this log message originates from. @available(*, deprecated, message: "You should implement this method instead of using the default implementation") public func log( level: Logger.Level, @@ -222,6 +256,14 @@ extension LogHandler { self.log(level: level, message: message, metadata: metadata, file: file, function: function, line: line) } + /// A default implementation for a log message handler. + /// - Parameters: + /// - level: The log level of the message. + /// - message: The message to log. To obtain a `String` representation call `message.description`. + /// - metadata: The metadata associated to this log message. + /// - file: The file this log message originates from. + /// - function: The function this log message originates from. + /// - line: The line this log message originates from. @available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)") public func log( level: Logging.Logger.Level, diff --git a/Sources/Logging/Logging.swift b/Sources/Logging/Logging.swift index 1622edb..cada241 100644 --- a/Sources/Logging/Logging.swift +++ b/Sources/Logging/Logging.swift @@ -28,14 +28,13 @@ import WASILibc #error("Unsupported runtime") #endif -/// A `Logger` is the central type in `SwiftLog`. Its central function is to emit log messages using one of the methods -/// corresponding to a log level. +/// A Logger emits log messages using methods that correspond to a log level. /// -/// `Logger`s are value types with respect to the ``Logger/Level`` and the ``Metadata`` (as well as the immutable `label` -/// and the selected ``LogHandler``). Therefore, `Logger`s are suitable to be passed around between libraries if you want -/// to preserve metadata across libraries. +/// `Logger` is a value type with respect to the ``Logger/Level`` and the ``Metadata`` (as well as the immutable `label` +/// and the selected ``LogHandler``). +/// Therefore, you can pass an instance of `Logger` between libraries to preserve metadata across libraries. /// -/// The most basic usage of a `Logger` is +/// The most basic usage of a `Logger` is: /// /// ```swift /// logger.info("Hello World!") @@ -69,7 +68,9 @@ public struct Logger { self._storage.label } - /// A computed property to access the `LogHandler`. + /// The log handler. + /// + /// This computed property provides access to the `LogHandler`. @inlinable public var handler: any LogHandler { get { @@ -96,23 +97,23 @@ public struct Logger { } extension Logger { - /// Log a message passing the log level as a parameter. + /// Log a message using the log level and source that you provide. /// - /// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, it will be logged, - /// otherwise nothing will happen. + /// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library + /// logs the message, otherwise nothing will happen. /// /// - parameters: - /// - level: The log level to log `message` at. For the available log levels, see `Logger.Level`. - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - level: The severity level of the `message`. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func log( level: Logger.Level, @@ -136,21 +137,21 @@ extension Logger { } } - /// Log a message passing the log level as a parameter. + /// Log a message using the log level you provide. /// - /// If the ``logLevel`` passed to this method is more severe than the `Logger`'s ``logLevel``, it will be logged, - /// otherwise nothing will happen. + /// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library + /// logs the message, otherwise nothing will happen. /// /// - parameters: - /// - level: The log level to log `message` at. For the available log levels, see `Logger.Level`. - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - level: The log level to log the `message`. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func log( level: Logger.Level, @@ -165,8 +166,7 @@ extension Logger { /// Add, change, or remove a logging metadata item. /// - /// - note: Logging metadata behaves as a value that means a change to the logging metadata will only affect the - /// very `Logger` it was changed on. + /// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it. @inlinable public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? { get { @@ -179,10 +179,10 @@ extension Logger { /// Get or set the log level configured for this `Logger`. /// - /// - note: `Logger`s treat `logLevel` as a value. This means that a change in `logLevel` will only affect this - /// very `Logger`. It is acceptable for logging backends to have some form of global log level override - /// that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in - /// certain cases have no effect. + /// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it. + /// > It is acceptable for logging backends to have some form of global log level override + /// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in + /// > certain cases have no effect. @inlinable public var logLevel: Logger.Level { get { @@ -195,22 +195,22 @@ extension Logger { } extension Logger { - /// Log a message passing with the ``Logger/Level/trace`` log level. + /// Log a message at the 'trace' log level with the source that you provide. /// - /// If `.trace` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/trace`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. - /// - metadata: One-off metadata to attach to this log message - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. + /// - metadata: One-off metadata to attach to this log message. + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func trace( _ message: @autoclosure () -> Logger.Message, @@ -231,20 +231,20 @@ extension Logger { ) } - /// Log a message passing with the ``Logger/Level/trace`` log level. + /// Log a message at the 'trace' log level. /// - /// If `.trace` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/trace`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. - /// - metadata: One-off metadata to attach to this log message - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. + /// - metadata: One-off metadata to attach to this log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func trace( _ message: @autoclosure () -> Logger.Message, @@ -256,22 +256,22 @@ extension Logger { self.trace(message(), metadata: metadata(), source: nil, file: file, function: function, line: line) } - /// Log a message passing with the ``Logger/Level/debug`` log level. + /// Log a message at the 'debug' log level with the source that you provide. /// - /// If `.debug` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/debug`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func debug( _ message: @autoclosure () -> Logger.Message, @@ -292,20 +292,20 @@ extension Logger { ) } - /// Log a message passing with the ``Logger/Level/debug`` log level. + /// Log a message at the 'debug' log level. /// - /// If `.debug` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/debug`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func debug( _ message: @autoclosure () -> Logger.Message, @@ -317,22 +317,22 @@ extension Logger { self.debug(message(), metadata: metadata(), source: nil, file: file, function: function, line: line) } - /// Log a message passing with the ``Logger/Level/info`` log level. + /// Log a message at the 'info' log level with the source that you provide. /// - /// If `.info` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/info`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func info( _ message: @autoclosure () -> Logger.Message, @@ -353,20 +353,20 @@ extension Logger { ) } - /// Log a message passing with the ``Logger/Level/info`` log level. + /// Log a message at the 'info' log level. /// - /// If `.info` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/info`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func info( _ message: @autoclosure () -> Logger.Message, @@ -378,22 +378,22 @@ extension Logger { self.info(message(), metadata: metadata(), source: nil, file: file, function: function, line: line) } - /// Log a message passing with the ``Logger/Level/notice`` log level. + /// Log a message at the 'notice' log level with the source that you provide. /// - /// If `.notice` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/notice`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func notice( _ message: @autoclosure () -> Logger.Message, @@ -414,20 +414,20 @@ extension Logger { ) } - /// Log a message passing with the ``Logger/Level/notice`` log level. + /// Log a message at the 'notice' log level. /// - /// If `.notice` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/notice`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func notice( _ message: @autoclosure () -> Logger.Message, @@ -439,22 +439,22 @@ extension Logger { self.notice(message(), metadata: metadata(), source: nil, file: file, function: function, line: line) } - /// Log a message passing with the ``Logger/Level/warning`` log level. + /// Log a message at the 'warning' log level with the source that you provide. /// - /// If `.warning` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/warning`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func warning( _ message: @autoclosure () -> Logger.Message, @@ -475,20 +475,20 @@ extension Logger { ) } - /// Log a message passing with the ``Logger/Level/warning`` log level. + /// Log a message at the 'warning' log level. /// - /// If `.warning` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/warning`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func warning( _ message: @autoclosure () -> Logger.Message, @@ -500,22 +500,22 @@ extension Logger { self.warning(message(), metadata: metadata(), source: nil, file: file, function: function, line: line) } - /// Log a message passing with the ``Logger/Level/error`` log level. + /// Log a message at the 'error' log level with the source that you provide. /// - /// If `.error` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/error`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func error( _ message: @autoclosure () -> Logger.Message, @@ -536,20 +536,20 @@ extension Logger { ) } - /// Log a message passing with the ``Logger/Level/error`` log level. + /// Log a message at the 'error' log level. /// - /// If `.error` is at least as severe as the `Logger`'s ``logLevel``, it will be logged, + /// If ``Level/error`` is at least as severe as this logger's ``logLevel`` the system logs the message; /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func error( _ message: @autoclosure () -> Logger.Message, @@ -561,21 +561,22 @@ extension Logger { self.error(message(), metadata: metadata(), source: nil, file: file, function: function, line: line) } - /// Log a message passing with the ``Logger/Level/critical`` log level. + /// Log a message at the 'critical' log level with the source that you provide. /// - /// `.critical` messages will always be logged. + /// If ``Level/critical`` is at least as severe as this logger's ``logLevel`` the system logs the message; + /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - source: The source this log messages originates from. Defaults - /// to the module emitting the log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func critical( _ message: @autoclosure () -> Logger.Message, @@ -596,19 +597,20 @@ extension Logger { ) } - /// Log a message passing with the ``Logger/Level/critical`` log level. + /// Log a message at the 'critical' log level. /// - /// `.critical` messages will always be logged. + /// If ``Level/critical`` is at least as severe as this logger's ``logLevel`` the system logs the message; + /// otherwise nothing will happen. /// /// - parameters: - /// - message: The message to be logged. `message` can be used with any string interpolation literal. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. /// - metadata: One-off metadata to attach to this log message. - /// - file: The file this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#fileID`). - /// - function: The function this log message originates from (there's usually no need to pass it explicitly as - /// it defaults to `#function`). - /// - line: The line this log message originates from (there's usually no need to pass it explicitly as it - /// defaults to `#line`). + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func critical( _ message: @autoclosure () -> Logger.Message, @@ -621,9 +623,19 @@ extension Logger { } } -/// The `LoggingSystem` is a global facility where the default logging backend implementation (`LogHandler`) can be -/// configured. `LoggingSystem` is set up just once in a given program to set up the desired logging backend -/// implementation. +/// The logging system is a global facility where you can configure the default logging backend implementation. +/// +/// `LoggingSystem` is set up just once in a given program to set up the desired logging backend implementation. +/// The default behavior, if you don't define otherwise, sets the ``LogHandler`` to use a ``StreamLogHandler`` that presents its output to `STDOUT`. +/// +/// You can configure that handler to present the output to `STDERR` instead using the following code: +/// +/// ```swift +/// LoggingSystem.bootstrap(StreamLogHandler.standardError) +/// ``` +/// +/// The default (``StreamLogHandler``) is intended to be a convenience. +/// For production applications, implement the ``LogHandler`` protocol directly, or use a community-maintained backend. public enum LoggingSystem { private static let _factory = FactoryBox( { label, _ in StreamLogHandler.standardError(label: label) }, @@ -638,12 +650,14 @@ public enum LoggingSystem { private static let _warnOnceBox: WarnOnceBox = WarnOnceBox() #endif - /// `bootstrap` is a one-time configuration function which globally selects the desired logging backend - /// implementation. `bootstrap` can be called at maximum once in any given program, calling it more than once will - /// lead to undefined behavior, most likely a crash. + /// A one-time configuration function that globally selects the implementation for your desired logging backend. + /// + /// > Warning: + /// > `bootstrap` can be called at maximum once in any given program, calling it more than once will + /// > lead to undefined behavior, most likely a crash. /// /// - parameters: - /// - factory: A closure that given a `Logger` identifier, produces an instance of the `LogHandler`. + /// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``. @preconcurrency public static func bootstrap(_ factory: @escaping @Sendable (String) -> any LogHandler) { self._factory.replace( @@ -654,16 +668,15 @@ public enum LoggingSystem { ) } - /// `bootstrap` is a one-time configuration function which globally selects the desired logging backend - /// implementation. + /// A one-time configuration function that globally selects the implementation for your desired logging backend. /// - /// - Warning: - /// `bootstrap` can be called at maximum once in any given program, calling it more than once will - /// lead to undefined behavior, most likely a crash. + /// > Warning: + /// > `bootstrap` can be called at maximum once in any given program, calling it more than once will + /// > lead to undefined behavior, most likely a crash. /// /// - parameters: /// - metadataProvider: The `MetadataProvider` used to inject runtime-generated metadata from the execution context. - /// - factory: A closure that given a `Logger` identifier, produces an instance of the `LogHandler`. + /// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``. @preconcurrency public static func bootstrap( _ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler, @@ -745,7 +758,7 @@ public enum LoggingSystem { } } - /// Protects an object applying the constraints that it can only be accessed through a Reader-Writer lock + /// Protects an object by applying the constraints that it can only be accessed through a Reader-Writer lock /// and can only be updated once from the initial value given. private struct ReplaceOnceBox { private struct ReplaceOnce: Sendable { @@ -797,42 +810,98 @@ public enum LoggingSystem { } extension Logger { + /// The type of the metadata storage. + /// /// `Metadata` is a typealias for `[String: Logger.MetadataValue]` the type of the metadata storage. public typealias Metadata = [String: MetadataValue] - /// A logging metadata value. `Logger.MetadataValue` is string, array, and dictionary literal convertible. + /// A logging metadata value. + /// + /// `Logger.MetadataValue` is a string, array, or a dictionary literal convertible. /// /// `MetadataValue` provides convenient conformances to `ExpressibleByStringInterpolation`, /// `ExpressibleByStringLiteral`, `ExpressibleByArrayLiteral`, and `ExpressibleByDictionaryLiteral` which means /// that when constructing `MetadataValue`s you should default to using Swift's usual literals. /// - /// Examples: - /// - prefer `logger.info("user logged in", metadata: ["user-id": "\(user.id)"])` over - /// `..., metadata: ["user-id": .string(user.id.description)])` - /// - prefer `logger.info("user selected colors", metadata: ["colors": ["\(user.topColor)", "\(user.secondColor)"]])` - /// over `..., metadata: ["colors": .array([.string("\(user.topColor)"), .string("\(user.secondColor)")])` - /// - prefer `logger.info("nested info", metadata: ["nested": ["fave-numbers": ["\(1)", "\(2)", "\(3)"], "foo": "bar"]])` - /// over `..., metadata: ["nested": .dictionary(["fave-numbers": ...])])` + /// + /// Prefer using string interpolation for convenience, for example: + /// ```swift + /// logger.info( + /// "user logged in", + /// metadata: ["user-id": "\(user.id)"] + /// ) + /// ``` + /// over: + /// ```swift + /// logger.info( + /// "user logged in", + /// metadata: ["user-id": .string(user.id.description)] + /// ) + /// ``` + /// + /// Rather than explicitly asserting that the metadata is an array or dictionary, use the string literal to interpolate into the result: + /// ```swift + /// logger.info( + /// "user selected colors", + /// metadata: ["colors": ["\(user.topColor)", "\(user.secondColor)"]]) + /// ``` + /// over: + /// ```swift + /// logger.info( + /// "user selected colors", + /// metadata: [ + /// "colors": .array([.string("\(user.topColor)"), .string("\(user.secondColor)") + /// ] + /// ) + /// ``` + /// + /// and an example that illustrates presenting a dictionary: + /// + /// ```swift + /// logger.info( + /// "nested info", + /// metadata: [ + /// "nested": [ + /// "fave-numbers": ["\(1)", "\(2)", "\(3)"], + /// "foo": "bar" + /// ] + /// ] + /// ) + /// ``` + /// over + /// ```swift + /// logger.info( + /// "nested info", + /// metadata: [ + /// "nested": .dictionary([ + /// "fave-numbers": ["\(1)", "\(2)", "\(3)"], + /// "foo": "bar" + /// ]) + /// ]) + /// ``` + /// public enum MetadataValue { - /// A metadata value which is a `String`. + /// A string metadata value. /// /// Because `MetadataValue` implements `ExpressibleByStringInterpolation`, and `ExpressibleByStringLiteral`, - /// you don't need to type `.string(someType.description)` you can use the string interpolation `"\(someType)"`. + /// you don't need to type `.string(someType.description)` instead the string interpolation `"\(someType)"`. case string(String) - /// A metadata value which is some `CustomStringConvertible`. + /// A metadata value that conforms to custom string convertible. case stringConvertible(any CustomStringConvertible & Sendable) - /// A metadata value which is a dictionary from `String` to `Logger.MetadataValue`. + /// A metadata value which is a dictionary keyed with strings and storing metadata values. + /// + /// The type signature of the dictionary is `[String: Logger.MetadataValue]`. /// /// Because `MetadataValue` implements `ExpressibleByDictionaryLiteral`, you don't need to type - /// `.dictionary(["foo": .string("bar \(buz)")])`, you can just use the more natural `["foo": "bar \(buz)"]`. + /// `.dictionary(["foo": .string("bar \(buz)")])`, instead use the more natural `["foo": "bar \(buz)"]`. case dictionary(Metadata) - /// A metadata value which is an array of `Logger.MetadataValue`s. + /// An array of metadata values. /// /// Because `MetadataValue` implements `ExpressibleByArrayLiteral`, you don't need to type - /// `.array([.string("foo"), .string("bar \(buz)")])`, you can just use the more natural `["foo", "bar \(buz)"]`. + /// `.array([.string("foo"), .string("bar \(buz)")])`, instead use the more natural `["foo", "bar \(buz)"]`. case array([Metadata.Value]) } @@ -845,26 +914,22 @@ extension Logger { /// tracing the execution of a program. case trace - /// Appropriate for messages that contain information normally of use only when - /// debugging a program. + /// Appropriate for messages that contain information normally of use only when debugging a program. case debug /// Appropriate for informational messages. case info - /// Appropriate for conditions that are not error conditions, but that may require - /// special handling. + /// Appropriate for conditions that are not error conditions, but that may require special handling. case notice - /// Appropriate for messages that are not error conditions, but more severe than - /// `.notice`. + /// Appropriate for messages that are not error conditions, but more severe than notice. case warning /// Appropriate for error conditions. case error - /// Appropriate for critical error conditions that usually require immediate - /// attention. + /// Appropriate for critical error conditions that usually require immediate attention. /// /// When a `critical` message is logged, the logging backend (`LogHandler`) is free to perform /// more heavy-weight operations to capture system state (such as capturing stack traces) to facilitate @@ -872,10 +937,10 @@ extension Logger { case critical } - /// Construct a `Logger` given a `label` identifying the creator of the `Logger`. + /// Construct a logger with the label you provide to identify the creator of the logger. /// - /// The `label` should identify the creator of the `Logger`. This can be an application, a sub-system, or even - /// a datatype. + /// The `label` should identify the creator of the `Logger`. + /// This can be an application, a sub-system, or a datatype. /// /// - parameters: /// - label: An identifier for the creator of a `Logger`. @@ -883,48 +948,45 @@ extension Logger { self.init(label: label, LoggingSystem.factory(label, LoggingSystem.metadataProvider)) } - /// Construct a `Logger` given a `label` identifying the creator of the `Logger` or a non-standard `LogHandler`. + /// Creates a logger using the label that identifies the creator of the logger or a non-standard log handler. /// - /// The `label` should identify the creator of the `Logger`. This can be an application, a sub-system, or even - /// a datatype. + /// The `label` should identify the creator of the `Logger`. + /// The label can represent an application, a sub-system, or even a datatype. /// /// This initializer provides an escape hatch in case the global default logging backend implementation (set up - /// using `LoggingSystem.bootstrap` is not appropriate for this particular logger. + /// using `LoggingSystem.bootstrap`) is not appropriate for this particular logger. /// /// - parameters: /// - label: An identifier for the creator of a `Logger`. - /// - factory: A closure creating non-standard `LogHandler`s. + /// - factory: A closure that creates a non-standard `LogHandler`. public init(label: String, factory: (String) -> any LogHandler) { self = Logger(label: label, factory(label)) } - /// Construct a `Logger` given a `label` identifying the creator of the `Logger` or a non-standard `LogHandler`. + /// Creates a logger using the label that identifies the creator of the logger or a non-standard log handler. /// - /// The `label` should identify the creator of the `Logger`. This can be an application, a sub-system, or even - /// a datatype. + /// The `label` should identify the creator of the `Logger`. + /// The label can represent an application, a sub-system, or even a datatype. /// /// This initializer provides an escape hatch in case the global default logging backend implementation (set up - /// using `LoggingSystem.bootstrap` is not appropriate for this particular logger. + /// using `LoggingSystem.bootstrap`) is not appropriate for this particular logger. /// /// - parameters: /// - label: An identifier for the creator of a `Logger`. - /// - factory: A closure creating non-standard `LogHandler`s. + /// - factory: A closure that creates a non-standard `LogHandler`. public init(label: String, factory: (String, Logger.MetadataProvider?) -> any LogHandler) { self = Logger(label: label, factory(label, LoggingSystem.metadataProvider)) } - /// Construct a `Logger` given a `label` identifying the creator of the `Logger` and a non-standard ``Logger/MetadataProvider``. + /// Creates a logger using the label that identifies the creator of the logger or a non-standard log handler. /// - /// The `label` should identify the creator of the `Logger`. This can be an application, a sub-system, or even - /// a datatype. + /// The `label` should identify the creator of the `Logger`. + /// The label can represent an application, a sub-system, or even a datatype. /// - /// This initializer provides an escape hatch in case the global default logging backend implementation (set up - /// using `LoggingSystem.bootstrap` is not appropriate for this particular logger. - /// - /// - parameters: - /// - label: An identifier for the creator of a `Logger`. - /// - metadataProvider: The custom metadata provider this logger should invoke, - /// instead of the system wide bootstrapped one, when a log statement is about to be emitted. + /// - Parameters: + /// - label: An identifier for the creator of a `Logger`. + /// - metadataProvider: The custom metadata provider this logger should invoke, + /// instead of the system wide bootstrapped one, when a log statement is about to be emitted. public init(label: String, metadataProvider: MetadataProvider) { self = Logger( label: label, @@ -969,6 +1031,11 @@ extension Logger.Level: Comparable { // Then we could write it as follows and it would work under Swift 5 and not only 4 as it does currently: // extension Logger.Metadata.Value: Equatable { extension Logger.MetadataValue: Equatable { + /// Returns a Boolean value that indicates whether two metadata values are equal. + /// - Parameters: + /// - lhs: The first metadata value. + /// - rhs: The second metadata value. + /// - Returns: Returns `true` if the metadata values are equivalent; otherwise `false`. public static func == (lhs: Logger.Metadata.Value, rhs: Logger.Metadata.Value) -> Bool { switch (lhs, rhs) { case (.string(let lhs), .string(let rhs)): @@ -986,7 +1053,9 @@ extension Logger.MetadataValue: Equatable { } extension Logger { - /// `Logger.Message` represents a log message's text. It is usually created using string literals. + /// The content of log message. + /// + /// It is usually created using string literals. /// /// Example creating a `Logger.Message`: /// @@ -1014,21 +1083,22 @@ extension Logger { } } -/// A pseudo-`LogHandler` that can be used to send messages to multiple other `LogHandler`s. +/// A pseudo log handler that sends messages to multiple other log handlers. /// /// ### Effective Logger.Level /// -/// When first initialized the multiplex log handlers' log level is automatically set to the minimum of all the -/// passed in log handlers. This ensures that each of the handlers will be able to log at their appropriate level +/// When first initialized, the multiplex log handlers' log level is automatically set to the minimum of all the +/// provided log handlers. +/// This ensures that each of the handlers are able to log at their appropriate level /// any log events they might be interested in. /// /// Example: -/// If log handler `A` is logging at `.debug` level, and log handler `B` is logging at `.info` level, the constructed -/// `MultiplexLogHandler([A, B])`'s effective log level will be set to `.debug`, meaning that debug messages will be -/// handled by this handler, while only logged by the underlying `A` log handler (since `B`'s log level is `.info` +/// If log handler `A` is logging at `.debug` level, and log handler `B` is logging at `.info` level, the log level of the constructed +/// `MultiplexLogHandler([A, B])` is set to `.debug`. This means that this handler will operate on debug messages, +/// while only logged by the underlying `A` log handler (since `B`'s log level is `.info` /// and thus it would not actually log that log message). /// -/// If the log level is _set_ on a `Logger` backed by an `MultiplexLogHandler` the log level will apply to *all* +/// If the log level is _set_ on a `Logger` backed by an `MultiplexLogHandler` the log level applies to *all* /// underlying log handlers, allowing a logger to still select at what level it wants to log regardless of if the underlying /// handler is a multiplex or a normal one. If for some reason one might want to not allow changing a log level of a specific /// handler passed into the multiplex log handler, this is possible by wrapping it in a handler which ignores any log level changes. @@ -1042,11 +1112,11 @@ extension Logger { /// proxying writes that users made on a `Logger` instance backed by this handler. /// /// Setting metadata is always proxied through to _all_ underlying handlers, meaning that if a modification like -/// `logger[metadataKey: "x"] = "y"` is made, all underlying log handlers that this multiplex handler was initiated with -/// will observe this change. +/// `logger[metadataKey: "x"] = "y"` is made, all the underlying log handlers used to create the multiplex handler +/// observe this change. /// /// Reading metadata from the multiplex log handler MAY need to pick one of conflicting values if the underlying log handlers -/// were already initiated with some metadata before passing them into the multiplex handler. The multiplex handler uses +/// were previously initiated with metadata before passing them into the multiplex handler. The multiplex handler uses /// the order in which the handlers were passed in during its initialization as a priority indicator - the first handler's /// values are more important than the next handlers values, etc. /// @@ -1056,16 +1126,17 @@ extension Logger { /// has values for keys `two` and `all`. /// /// A query through the multiplex log handler the key `one` naturally returns `handler1`'s value, and a query for `two` -/// naturally returns `handler2`'s value. Querying for the key `all` will return `handler1`'s value, as that handler was indicated -/// "more important" than the second handler. The same rule applies when querying for the `metadata` property of the -/// multiplex log handler - it constructs `Metadata` uniquing values. +/// naturally returns `handler2`'s value. +/// Querying for the key `all` will return `handler1`'s value, as that handler has a high priority, +/// as indicated by its earlier position in the initialization, than the second handler. +/// The same rule applies when querying for the `metadata` property of the multiplex log handler; it constructs `Metadata` uniquing values. public struct MultiplexLogHandler: LogHandler { private var handlers: [any LogHandler] private var effectiveLogLevel: Logger.Level /// This metadata provider runs after all metadata providers of the multiplexed handlers. private var _metadataProvider: Logger.MetadataProvider? - /// Create a `MultiplexLogHandler`. + /// Create a multiplex log handler. /// /// - parameters: /// - handlers: An array of `LogHandler`s, each of which will receive the log messages sent to this `Logger`. @@ -1076,6 +1147,11 @@ public struct MultiplexLogHandler: LogHandler { self.effectiveLogLevel = handlers.map { $0.logLevel }.min() ?? .trace } + /// Create a multiplex log handler with the metadata provider you provide. + /// - Parameters: + /// - handlers: An array of `LogHandler`s, each of which will receive every log message sent to this `Logger`. + /// The array must not be empty. + /// - metadataProvider: The metadata provider that adds metadata to log messages for this handler. public init(_ handlers: [any LogHandler], metadataProvider: Logger.MetadataProvider?) { assert(!handlers.isEmpty, "MultiplexLogHandler.handlers MUST NOT be empty") self.handlers = handlers @@ -1083,6 +1159,12 @@ public struct MultiplexLogHandler: LogHandler { self._metadataProvider = metadataProvider } + /// Get or set the log level configured for this `Logger`. + /// + /// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it. + /// > It is acceptable for logging backends to have some form of global log level override + /// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in + /// > certain cases have no effect. public var logLevel: Logger.Level { get { self.effectiveLogLevel @@ -1093,6 +1175,7 @@ public struct MultiplexLogHandler: LogHandler { } } + /// The metadata provider. public var metadataProvider: Logger.MetadataProvider? { get { if self.handlers.count == 1 { @@ -1130,6 +1213,20 @@ public struct MultiplexLogHandler: LogHandler { } } + /// Log a message using the log level and source that you provide. + /// + /// - parameters: + /// - level: The log level to log the `message`. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. + /// - metadata: One-off metadata to attach to this log message. + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. public func log( level: Logger.Level, message: Logger.Message, @@ -1151,7 +1248,7 @@ public struct MultiplexLogHandler: LogHandler { ) } } - + /// Get or set the entire metadata storage as a dictionary. public var metadata: Logger.Metadata { get { var effective: Logger.Metadata = [:] @@ -1178,6 +1275,9 @@ public struct MultiplexLogHandler: LogHandler { } } + /// Add, change, or remove a logging metadata item. + /// + /// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it. public subscript(metadataKey metadataKey: Logger.Metadata.Key) -> Logger.Metadata.Value? { get { for handler in self.handlers { @@ -1295,7 +1395,9 @@ internal struct StdioOutputStream: TextOutputStream, @unchecked Sendable { } } -/// `StreamLogHandler` is a simple implementation of `LogHandler` for directing +/// Stream log handler presents log messages to STDERR or STDOUT. +/// +/// This is a simple implementation of `LogHandler` that directs /// `Logger` output to either `stderr` or `stdout` via the factory methods. /// /// Metadata is merged in the following order: @@ -1305,7 +1407,7 @@ internal struct StdioOutputStream: TextOutputStream, @unchecked Sendable { public struct StreamLogHandler: LogHandler { internal typealias _SendableTextOutputStream = TextOutputStream & Sendable - /// Factory that makes a `StreamLogHandler` to directs its output to `stdout` + /// Creates a stream log handler that directs its output to STDOUT. public static func standardOutput(label: String) -> StreamLogHandler { StreamLogHandler( label: label, @@ -1314,12 +1416,12 @@ public struct StreamLogHandler: LogHandler { ) } - /// Factory that makes a `StreamLogHandler` that directs its output to `stdout` + /// Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide. public static func standardOutput(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler { StreamLogHandler(label: label, stream: StdioOutputStream.stdout, metadataProvider: metadataProvider) } - /// Factory that makes a `StreamLogHandler` that directs its output to `stderr` + /// Creates a stream log handler that directs its output to STDERR. public static func standardError(label: String) -> StreamLogHandler { StreamLogHandler( label: label, @@ -1328,7 +1430,7 @@ public struct StreamLogHandler: LogHandler { ) } - /// Factory that makes a `StreamLogHandler` that direct its output to `stderr` + /// Creates a stream log handler that directs its output to STDERR using the metadata provider you provide. public static func standardError(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler { StreamLogHandler(label: label, stream: StdioOutputStream.stderr, metadataProvider: metadataProvider) } @@ -1336,17 +1438,28 @@ public struct StreamLogHandler: LogHandler { private let stream: any _SendableTextOutputStream private let label: String + /// Get the log level configured for this `Logger`. + /// + /// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it. + /// > It is acceptable for logging backends to have some form of global log level override + /// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in + /// > certain cases have no effect. public var logLevel: Logger.Level = .info + /// The metadata provider. public var metadataProvider: Logger.MetadataProvider? private var prettyMetadata: String? + /// Get or set the entire metadata storage as a dictionary. public var metadata = Logger.Metadata() { didSet { self.prettyMetadata = self.prettify(self.metadata) } } + /// Add, change, or remove a logging metadata item. + /// + /// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it. public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? { get { self.metadata[metadataKey] @@ -1368,6 +1481,20 @@ public struct StreamLogHandler: LogHandler { self.metadataProvider = metadataProvider } + /// Log a message using the log level and source that you provide. + /// + /// - parameters: + /// - level: The log level to log the `message`. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. + /// - explicitMetadata: One-off metadata to attach to this log message. + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. public func log( level: Logger.Level, message: Logger.Message, @@ -1454,12 +1581,26 @@ public struct StreamLogHandler: LogHandler { } } -/// No operation LogHandler, used when no logging is required +/// A no-operation log handler, used when no logging is required public struct SwiftLogNoOpLogHandler: LogHandler { + /// Creates a no-op log handler. public init() {} + /// Creates a no-op log handler. public init(_: String) {} + /// A proxy that discards every log message it receives. + /// + /// - parameters: + /// - level: The log level to log the `message`. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. + /// - metadata: One-off metadata to attach to this log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. @inlinable public func log( level: Logger.Level, message: Logger.Message, @@ -1469,6 +1610,20 @@ public struct SwiftLogNoOpLogHandler: LogHandler { line: UInt ) {} + /// A proxy that discards every log message that you provide. + /// + /// - parameters: + /// - level: The log level to log the `message`. + /// - message: The message to be logged. The `message` parameter supports any string interpolation literal. + /// - metadata: One-off metadata to attach to this log message. + /// - source: The source this log message originates from. The value defaults + /// to the module that emits the log message. + /// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#fileID`. + /// - function: The function this log message originates from. There's usually no need to pass it explicitly, as + /// it defaults to `#function`. + /// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it + /// defaults to `#line`. public func log( level: Logger.Level, message: Logger.Message, @@ -1479,6 +1634,9 @@ public struct SwiftLogNoOpLogHandler: LogHandler { line: UInt ) {} + /// Add, change, or remove a logging metadata item. + /// + /// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it. @inlinable public subscript(metadataKey _: String) -> Logger.Metadata.Value? { get { nil @@ -1486,6 +1644,7 @@ public struct SwiftLogNoOpLogHandler: LogHandler { set {} } + /// Get or set the entire metadata storage as a dictionary. @inlinable public var metadata: Logger.Metadata { get { [:] @@ -1493,6 +1652,12 @@ public struct SwiftLogNoOpLogHandler: LogHandler { set {} } + /// Get or set the log level configured for this `Logger`. + /// + /// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it. + /// > It is acceptable for logging backends to have some form of global log level override + /// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in + /// > certain cases have no effect. @inlinable public var logLevel: Logger.Level { get { .critical @@ -1528,8 +1693,11 @@ extension Logger { // Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for // https://bugs.swift.org/browse/SR-9686 extension Logger.MetadataValue: ExpressibleByStringLiteral { + /// The type that represents a string literal. public typealias StringLiteralType = String + /// Create a new metadata value from the string literal value that you provide. + /// - Parameter value: The metadata value. public init(stringLiteral value: String) { self = .string(value) } @@ -1538,6 +1706,7 @@ extension Logger.MetadataValue: ExpressibleByStringLiteral { // Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for // https://bugs.swift.org/browse/SR-9686 extension Logger.MetadataValue: CustomStringConvertible { + /// A string representation of the metadata value. public var description: String { switch self { case .dictionary(let dict): @@ -1559,9 +1728,13 @@ extension Logger.MetadataValue: ExpressibleByStringInterpolation {} // Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for // https://bugs.swift.org/browse/SR-9686 extension Logger.MetadataValue: ExpressibleByDictionaryLiteral { + /// The type of a metadata value key. public typealias Key = String + /// The type of the value for a metadata value. public typealias Value = Logger.Metadata.Value + /// Create a new metadata value from the dictionary literal that you provide. + /// - Parameter elements: A dictionary literal of metadata values. public init(dictionaryLiteral elements: (String, Logger.Metadata.Value)...) { self = .dictionary(.init(uniqueKeysWithValues: elements)) } @@ -1570,8 +1743,11 @@ extension Logger.MetadataValue: ExpressibleByDictionaryLiteral { // Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for // https://bugs.swift.org/browse/SR-9686 extension Logger.MetadataValue: ExpressibleByArrayLiteral { + /// The type that the array literal element represents. public typealias ArrayLiteralElement = Logger.Metadata.Value + /// Create a new metadata value from the array literal that you provide. + /// - Parameter elements: A array literal of metadata values. public init(arrayLiteral elements: Logger.Metadata.Value...) { self = .array(elements) } diff --git a/Sources/Logging/MetadataProvider.swift b/Sources/Logging/MetadataProvider.swift index d2daa1a..0c52e88 100644 --- a/Sources/Logging/MetadataProvider.swift +++ b/Sources/Logging/MetadataProvider.swift @@ -31,7 +31,7 @@ import WASILibc @preconcurrency protocol _SwiftLogSendable: Sendable {} extension Logger { - /// A `MetadataProvider` is used to automatically inject runtime-generated metadata + /// A MetadataProvider automatically injects runtime-generated metadata /// to all logs emitted by a logger. /// /// ### Example @@ -58,18 +58,18 @@ extension Logger { /// possible to make use of metadata providers independently of tracing and instruments provided by that library, /// if necessary. public struct MetadataProvider: _SwiftLogSendable { - /// Provide ``Logger.Metadata`` from current context. + /// Provide ``Logger.Metadata`` from the current context. @usableFromInline internal let _provideMetadata: @Sendable () -> Metadata - /// Create a new `MetadataProvider`. + /// Creates a new metadata provider. /// - /// - Parameter provideMetadata: A closure extracting metadata from the current execution context. + /// - Parameter provideMetadata: A closure that extracts metadata from the current execution context. public init(_ provideMetadata: @escaping @Sendable () -> Metadata) { self._provideMetadata = provideMetadata } - /// Invoke the metadata provider and return the generated contextual ``Logger/Metadata``. + /// Invokes the metadata provider and returns the generated contextual metadata. public func get() -> Metadata { self._provideMetadata() } @@ -77,7 +77,7 @@ extension Logger { } extension Logger.MetadataProvider { - /// A pseudo-`MetadataProvider` that can be used to merge metadata from multiple other `MetadataProvider`s. + /// A pseudo metadata provider that merges metadata from multiple other metadata providers. /// /// ### Merging conflicting keys ///