documentation update and re-organization (#381)

Provide organization (aka curation) and abstracts for all of the public
types in the library.

### Motivation:

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

### Modifications:

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

### Result:

starting point

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

Updated:

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

---------

Co-authored-by: Honza Dvorsky <honza@apple.com>
Co-authored-by: Franz Busch <privat@franz-busch.de>
This commit is contained in:
authored and GitHub committed 2025-11-03 11:26:54 -08:00
1 parent a90a3d1c37
commit 4121d24dbd
17 files changed
+832 -381

No files matched your search

+8
View File
@@ -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!")
@@ -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.
@@ -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``
@@ -0,0 +1,13 @@
# ``Logging/Logger/Level``
## Topics
### Log Levels
- ``trace``
- ``debug``
- ``info``
- ``notice``
- ``warning``
- ``error``
- ``critical``
@@ -0,0 +1,12 @@
# ``Logging/Logger/Message``
## Topics
### Creating a log message
- ``init(stringLiteral:)``
### Inspecting a log message
- ``description``
@@ -0,0 +1,15 @@
# ``Logging/Logger/MetadataProvider``
## Topics
### Creating a metadata provider
- ``init(_:)``
### Invoking the provider
- ``get()``
### Merging metadata
- ``multiplex(_:)``
@@ -0,0 +1,11 @@
# ``Logging/Logger/MetadataValue``
## Topics
### Types of metadata values
- ``string(_:)``
- ``stringConvertible(_:)``
- ``array(_:)``
- ``dictionary(_:)``
@@ -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``
@@ -0,0 +1,13 @@
# ``Logging/LoggingSystem``
## Topics
### Initializing the logging system
- ``bootstrap(_:)``
- ``bootstrap(_:metadataProvider:)``
### Inspecting the logging system
- ``metadataProvider``
@@ -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``
@@ -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``
@@ -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``
@@ -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 <doc:001-ChoosingLogLevels>.
### 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.
+5 -77
View File
@@ -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
- <doc:UnderstandingLoggers>
- ``Logger``
- ``LoggingSystem``
@@ -162,5 +91,4 @@ Use `source` for filtering messages from specific subsystems.
### Best Practices
- <doc:LoggingBestPractices>
- <doc:001-ChoosingLogLevels>
- <doc:ImplementingALogHandler>
+76 -34
View File
@@ -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,
File diff suppressed because it is too large. Load diff
+6 -6
View File
@@ -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
///