From 4121d24dbd71c363ea6f9e5f4664044b17cfc704 Mon Sep 17 00:00:00 2001 From: Joseph Heck Date: Mon, 3 Nov 2025 11:26:54 -0800 Subject: [PATCH] documentation update and re-organization (#381) Provide organization (aka curation) and abstracts for all of the public types in the library. ### Motivation: Updates to the documentation to fill in the missing abstracts for the provided types, updating the language to follow Apple developer content guidelines, and fixing smaller typos and grammar issues. ### Modifications: Curation files added to provide organization for public types, ordering the content to align with the narrative content provided earlier. Updating API comments, adding abstracts and parameters where missing, and moving some of the getting started content that was previously in the main index into a separate article. ### Result: starting point ``` --- Experimental coverage output enabled. --- | Abstract | Curated | Code Listing Types | 69% (11/16) | 38% (6/16) | 25% (4/16) Members | 57% (54/94) | 3.2% (3/94) | 0.0% (0/94) Globals | 7.1% (1/14) | 7.1% (1/14) | 7.1% (1/14) ``` Updated: ``` | Abstract | Curated | Code Listing Types | 94% (15/16) | 94% (15/16) | 38% (6/16) Members | 85% (80/94) | 97% (91/94) | 0.0% (0/94) Globals | 14% (2/14) | 100% (14/14) | 7.1% (1/14) ``` --------- Co-authored-by: Honza Dvorsky Co-authored-by: Franz Busch --- Snippets/basic-usage.swift | 8 + .../Docs.docc/ImplementingALogHandler.md | 5 +- .../Logging/Docs.docc/Reference/LogHandler.md | 20 + .../Docs.docc/Reference/Logger-Level.md | 13 + .../Docs.docc/Reference/Logger-Message.md | 12 + .../Reference/Logger-MetadataProvider.md | 15 + .../Reference/Logger-MetadataValue.md | 11 + Sources/Logging/Docs.docc/Reference/Logger.md | 60 ++ .../Docs.docc/Reference/LoggingSystem.md | 13 + .../Reference/MultiplexLogHandler.md | 22 + .../Docs.docc/Reference/StreamLogHandler.md | 24 + .../Reference/SwiftLogNoOpLogHandler.md | 22 + .../Logging/Docs.docc/UnderstandingLoggers.md | 86 +++ Sources/Logging/Docs.docc/index.md | 82 +- Sources/Logging/LogHandler.swift | 110 ++- Sources/Logging/Logging.swift | 698 +++++++++++------- Sources/Logging/MetadataProvider.swift | 12 +- 17 files changed, 832 insertions(+), 381 deletions(-) create mode 100644 Snippets/basic-usage.swift create mode 100644 Sources/Logging/Docs.docc/Reference/LogHandler.md create mode 100644 Sources/Logging/Docs.docc/Reference/Logger-Level.md create mode 100644 Sources/Logging/Docs.docc/Reference/Logger-Message.md create mode 100644 Sources/Logging/Docs.docc/Reference/Logger-MetadataProvider.md create mode 100644 Sources/Logging/Docs.docc/Reference/Logger-MetadataValue.md create mode 100644 Sources/Logging/Docs.docc/Reference/Logger.md create mode 100644 Sources/Logging/Docs.docc/Reference/LoggingSystem.md create mode 100644 Sources/Logging/Docs.docc/Reference/MultiplexLogHandler.md create mode 100644 Sources/Logging/Docs.docc/Reference/StreamLogHandler.md create mode 100644 Sources/Logging/Docs.docc/Reference/SwiftLogNoOpLogHandler.md create mode 100644 Sources/Logging/Docs.docc/UnderstandingLoggers.md 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 ///