mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
When a module name (via `-module-alias`) is a raw identifier (SE-0451), `#fileID` formats the module component enclosed in backticks (for example, `` `/a/b/c`/File.swift ``). If the raw identifier contains '/', splitting on the first '/' in `#fileID` truncates the module name at the slash inside the backticks. When `#fileID` starts with a backtick, advance past the matching closing backtick before searching for the '/' separator that ends the module name, preserving the enclosing backticks.
1563 lines
65 KiB
Swift
1563 lines
65 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the Swift Logging API open source project
|
|
//
|
|
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
|
// Licensed under Apache License v2.0
|
|
//
|
|
// See LICENSE.txt for license information
|
|
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
|
//
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
/// A Logger emits log messages using methods that correspond to a log level.
|
|
///
|
|
/// `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:
|
|
///
|
|
/// ```swift
|
|
/// logger.info("Hello World!")
|
|
/// ```
|
|
public struct Logger {
|
|
/// Storage class to hold the label and log handler
|
|
// The storage implements CoW to become Sendable
|
|
@usableFromInline
|
|
internal final class Storage: @unchecked Sendable {
|
|
@usableFromInline
|
|
var label: String
|
|
|
|
@usableFromInline
|
|
var handler: any LogHandler
|
|
|
|
@usableFromInline
|
|
init(label: String, handler: any LogHandler) {
|
|
self.label = label
|
|
self.handler = handler
|
|
}
|
|
|
|
@inlinable
|
|
func copy() -> Storage {
|
|
Storage(label: self.label, handler: self.handler)
|
|
}
|
|
}
|
|
|
|
@usableFromInline
|
|
internal var _storage: Storage
|
|
public var label: String {
|
|
self._storage.label
|
|
}
|
|
|
|
/// The log handler.
|
|
///
|
|
/// This computed property provides access to the `LogHandler`.
|
|
@inlinable
|
|
public var handler: any LogHandler {
|
|
_read {
|
|
yield self._storage.handler
|
|
}
|
|
// Keep a setter for plain assignments, which is cheaper than going through `_modify`.
|
|
set {
|
|
if !isKnownUniquelyReferenced(&self._storage) {
|
|
self._storage = self._storage.copy()
|
|
}
|
|
self._storage.handler = newValue
|
|
}
|
|
// Yield the stored handler, so a metadata write does not copy the handler's metadata.
|
|
_modify {
|
|
if !isKnownUniquelyReferenced(&self._storage) {
|
|
self._storage = self._storage.copy()
|
|
}
|
|
yield &self._storage.handler
|
|
}
|
|
}
|
|
|
|
/// The metadata provider this logger was created with.
|
|
@inlinable
|
|
public var metadataProvider: Logger.MetadataProvider? {
|
|
self.handler.metadataProvider
|
|
}
|
|
|
|
@usableFromInline
|
|
internal init(label: String, _ handler: any LogHandler) {
|
|
self._storage = Storage(label: label, handler: handler)
|
|
}
|
|
}
|
|
|
|
extension Logger {
|
|
/// 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``, the library
|
|
/// logs the message, otherwise nothing will happen.
|
|
///
|
|
/// NOTE: This method adds a constant overhead over calling level-specific methods.
|
|
///
|
|
/// - parameters:
|
|
/// - level: The severity level of the `message`.
|
|
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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 log(
|
|
level: Logger.Level,
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if MaxLogLevelDebug || MaxLogLevelInfo || MaxLogLevelNotice || MaxLogLevelWarning || MaxLogLevelError || MaxLogLevelCritical || MaxLogLevelNone
|
|
// A constant overhead is added for dynamic log level calls if one of the traits is enabled.
|
|
// This allows picking the necessary implementation with compiled out body in runtime.
|
|
switch level {
|
|
case .trace:
|
|
self.trace(
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
case .debug:
|
|
self.debug(
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
case .info:
|
|
self.info(
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
case .notice:
|
|
self.notice(
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
case .warning:
|
|
self.warning(
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
case .error:
|
|
self.error(
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
case .critical:
|
|
self.critical(
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
#else
|
|
// If no logs are excluded in the compile time, we can avoid checking the log level that extra time and go log it.
|
|
self._log(
|
|
level: level,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// 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``, the library
|
|
/// logs the message, otherwise nothing will happen.
|
|
///
|
|
/// NOTE: This method adds a constant overhead over calling level-specific methods.
|
|
///
|
|
/// - parameters:
|
|
/// - 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 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,
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.log(
|
|
level: level,
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// 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``, the library
|
|
/// logs the message, otherwise nothing will happen.
|
|
///
|
|
/// - parameters:
|
|
/// - level: The severity level of the `message`.
|
|
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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
|
|
package func _log(
|
|
level: Logger.Level,
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
if self.logLevel <= level {
|
|
self.handler.log(
|
|
event: LogEvent(
|
|
level: level,
|
|
message: message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
)
|
|
}
|
|
}
|
|
|
|
/// Log a message using the log level you provide.
|
|
///
|
|
/// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library
|
|
/// logs the message, otherwise nothing will happen.
|
|
///
|
|
/// NOTE: This method adds a constant overhead over calling level-specific methods.
|
|
///
|
|
/// - 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: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.log(
|
|
level: level,
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: nil,
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message using the log level and attributed metadata that you provide.
|
|
///
|
|
/// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library
|
|
/// logs the message, otherwise nothing will happen.
|
|
///
|
|
/// 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 metadataKey: String) -> Logger.Metadata.Value? {
|
|
get {
|
|
self.handler[metadataKey: metadataKey]
|
|
}
|
|
set {
|
|
#if !MaxLogLevelNone
|
|
self.handler[metadataKey: metadataKey] = newValue
|
|
#endif
|
|
}
|
|
}
|
|
|
|
/// 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 {
|
|
self.handler.logLevel
|
|
}
|
|
set {
|
|
#if !MaxLogLevelNone
|
|
self.handler.logLevel = newValue
|
|
#endif
|
|
}
|
|
}
|
|
}
|
|
|
|
extension Logger {
|
|
/// Log a message at the 'trace' log level with the source that you provide.
|
|
///
|
|
/// 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. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if !MaxLogLevelDebug && !MaxLogLevelInfo && !MaxLogLevelNotice && !MaxLogLevelWarning && !MaxLogLevelError && !MaxLogLevelCritical && !MaxLogLevelNone
|
|
self._log(
|
|
level: .trace,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// Log a message at the 'trace' log level with the source that you provide.
|
|
///
|
|
/// 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. 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,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.trace(
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message at the 'trace' log level.
|
|
///
|
|
/// 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. 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,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.trace(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
|
}
|
|
|
|
/// Log a message at the 'debug' log level with the source that you provide.
|
|
///
|
|
/// 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. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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 debug(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if !MaxLogLevelInfo && !MaxLogLevelNotice && !MaxLogLevelWarning && !MaxLogLevelError && !MaxLogLevelCritical && !MaxLogLevelNone
|
|
self._log(
|
|
level: .debug,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// Log a message at the 'debug' log level with the source that you provide.
|
|
///
|
|
/// 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. 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 debug(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.debug(
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message at the 'debug' log level.
|
|
///
|
|
/// 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. 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 debug(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.debug(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
|
}
|
|
|
|
/// Log a message at the 'info' log level with the source that you provide.
|
|
///
|
|
/// 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. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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 info(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if !MaxLogLevelNotice && !MaxLogLevelWarning && !MaxLogLevelError && !MaxLogLevelCritical && !MaxLogLevelNone
|
|
self._log(
|
|
level: .info,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// Log a message at the 'info' log level with the source that you provide.
|
|
///
|
|
/// 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. 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 info(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.info(
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message at the 'info' log level.
|
|
///
|
|
/// 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. 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 info(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.info(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
|
}
|
|
|
|
/// Log a message at the 'notice' log level with the source that you provide.
|
|
///
|
|
/// 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. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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 notice(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if !MaxLogLevelWarning && !MaxLogLevelError && !MaxLogLevelCritical && !MaxLogLevelNone
|
|
self._log(
|
|
level: .notice,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// Log a message at the 'notice' log level with the source that you provide.
|
|
///
|
|
/// 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. 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 notice(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.notice(
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message at the 'notice' log level.
|
|
///
|
|
/// 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. 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 notice(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.notice(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
|
}
|
|
|
|
/// Log a message at the 'warning' log level with the source that you provide.
|
|
///
|
|
/// 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. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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 warning(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if !MaxLogLevelError && !MaxLogLevelCritical && !MaxLogLevelNone
|
|
self._log(
|
|
level: .warning,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// Log a message at the 'warning' log level with the source that you provide.
|
|
///
|
|
/// 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. 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 warning(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.warning(
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message at the 'warning' log level.
|
|
///
|
|
/// 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. 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 warning(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.warning(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
|
}
|
|
|
|
/// Log a message at the 'error' log level with the source that you provide.
|
|
///
|
|
/// 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. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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 error(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if !MaxLogLevelCritical && !MaxLogLevelNone
|
|
self._log(
|
|
level: .error,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// Log a message at the 'error' log level with the source that you provide.
|
|
///
|
|
/// 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. 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 error(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.error(
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message at the 'error' log level.
|
|
///
|
|
/// 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. 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 error(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.error(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
|
}
|
|
|
|
/// Log a message at the 'critical' log level with the source that you provide.
|
|
///
|
|
/// 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. The `message` parameter supports any string interpolation literal.
|
|
/// - error: An `Error` related to the event.
|
|
/// - 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 critical(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
error: @autoclosure () -> (any Error)? = nil,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
#if !MaxLogLevelNone
|
|
self._log(
|
|
level: .critical,
|
|
message(),
|
|
error: error(),
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
#endif
|
|
}
|
|
|
|
/// Log a message at the 'critical' log level with the source that you provide.
|
|
///
|
|
/// 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. 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 critical(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
source: @autoclosure () -> String? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.critical(
|
|
message(),
|
|
error: nil,
|
|
metadata: metadata(),
|
|
source: source(),
|
|
file: file,
|
|
function: function,
|
|
line: line
|
|
)
|
|
}
|
|
|
|
/// Log a message at the 'critical' log level.
|
|
///
|
|
/// 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. 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 critical(
|
|
_ message: @autoclosure () -> Logger.Message,
|
|
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
|
file: String = #fileID,
|
|
function: String = #function,
|
|
line: UInt = #line
|
|
) {
|
|
self.critical(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
|
}
|
|
}
|
|
|
|
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 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.
|
|
///
|
|
///
|
|
/// 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 string metadata value.
|
|
///
|
|
/// Because `MetadataValue` implements `ExpressibleByStringInterpolation`, and `ExpressibleByStringLiteral`,
|
|
/// you don't need to type `.string(someType.description)` instead the string interpolation `"\(someType)"`.
|
|
case string(String)
|
|
|
|
/// A metadata value that conforms to custom string convertible.
|
|
case stringConvertible(any CustomStringConvertible & Sendable)
|
|
|
|
/// 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)")])`, instead use the more natural `["foo": "bar \(buz)"]`.
|
|
case dictionary(Metadata)
|
|
|
|
/// An array of metadata values.
|
|
///
|
|
/// Because `MetadataValue` implements `ExpressibleByArrayLiteral`, you don't need to type
|
|
/// `.array([.string("foo"), .string("bar \(buz)")])`, instead use the more natural `["foo", "bar \(buz)"]`.
|
|
case array([Metadata.Value])
|
|
}
|
|
}
|
|
|
|
extension Logger {
|
|
|
|
/// The log level.
|
|
///
|
|
/// Log levels are ordered by their severity, with `.trace` being the least severe and
|
|
/// `.critical` being the most severe.
|
|
public enum Level: String, Codable, CaseIterable {
|
|
/// Appropriate for messages that contain information normally of use only when
|
|
/// tracing the execution of a program.
|
|
case trace
|
|
|
|
/// 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.
|
|
case 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.
|
|
///
|
|
/// 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
|
|
/// debugging.
|
|
case critical
|
|
}
|
|
|
|
/// 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 a datatype.
|
|
///
|
|
/// - parameters:
|
|
/// - label: An identifier for the creator of a `Logger`.
|
|
public init(label: String) {
|
|
self.init(label: label, LoggingSystem.factory(label, LoggingSystem.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`.
|
|
/// 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`.
|
|
/// - factory: A closure that creates a non-standard `LogHandler`.
|
|
public init(label: String, factory: (String) -> any LogHandler) {
|
|
self = Logger(label: label, factory(label))
|
|
}
|
|
|
|
/// 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`.
|
|
/// 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`.
|
|
/// - 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))
|
|
}
|
|
|
|
/// 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`.
|
|
/// The label can represent an application, a sub-system, or even a datatype.
|
|
///
|
|
/// - 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,
|
|
factory: { label in
|
|
var handler = LoggingSystem.factory(label, metadataProvider)
|
|
handler.metadataProvider = metadataProvider
|
|
return handler
|
|
}
|
|
)
|
|
}
|
|
}
|
|
|
|
extension Logger.Level {
|
|
internal var naturalIntegralValue: Int {
|
|
switch self {
|
|
case .trace:
|
|
return 0
|
|
case .debug:
|
|
return 1
|
|
case .info:
|
|
return 2
|
|
case .notice:
|
|
return 3
|
|
case .warning:
|
|
return 4
|
|
case .error:
|
|
return 5
|
|
case .critical:
|
|
return 6
|
|
}
|
|
}
|
|
}
|
|
|
|
extension Logger.Level: Comparable {
|
|
public static func < (lhs: Logger.Level, rhs: Logger.Level) -> Bool {
|
|
lhs.naturalIntegralValue < rhs.naturalIntegralValue
|
|
}
|
|
}
|
|
|
|
extension Logger.Level: CustomStringConvertible, LosslessStringConvertible {
|
|
/// A textual representation of the log level.
|
|
public var description: String {
|
|
self.rawValue
|
|
}
|
|
|
|
/// Creates a log level from its textual representation.
|
|
/// - Parameter description: A textual representation of the log level, case insensitive.
|
|
public init?(_ description: String) {
|
|
self.init(rawValue: description.lowercased())
|
|
}
|
|
}
|
|
|
|
// Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for
|
|
// https://bugs.swift.org/browse/SR-9687
|
|
// 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)):
|
|
return lhs == rhs
|
|
case (.stringConvertible(let lhs), .stringConvertible(let rhs)):
|
|
return lhs.description == rhs.description
|
|
case (.array(let lhs), .array(let rhs)):
|
|
return lhs == rhs
|
|
case (.dictionary(let lhs), .dictionary(let rhs)):
|
|
return lhs == rhs
|
|
default:
|
|
return false
|
|
}
|
|
}
|
|
}
|
|
|
|
extension Logger {
|
|
/// The content of log message.
|
|
///
|
|
/// It is usually created using string literals.
|
|
///
|
|
/// Example creating a `Logger.Message`:
|
|
///
|
|
/// let world: String = "world"
|
|
/// let myLogMessage: Logger.Message = "Hello \(world)"
|
|
///
|
|
/// Most commonly, `Logger.Message`s appear simply as the parameter to a logging method such as:
|
|
///
|
|
/// logger.info("Hello \(world)")
|
|
///
|
|
public struct Message: ExpressibleByStringLiteral, Equatable, CustomStringConvertible,
|
|
ExpressibleByStringInterpolation
|
|
{
|
|
public typealias StringLiteralType = String
|
|
|
|
private var value: String
|
|
|
|
public init(stringLiteral value: String) {
|
|
self.value = value
|
|
}
|
|
|
|
public var description: String {
|
|
self.value
|
|
}
|
|
}
|
|
}
|
|
|
|
extension Logger {
|
|
@inlinable
|
|
internal static func currentModule(filePath: String = #file) -> String {
|
|
let utf8All = filePath.utf8
|
|
return filePath.utf8.lastIndex(of: UInt8(ascii: "/")).flatMap { lastSlash -> Substring? in
|
|
utf8All[..<lastSlash].lastIndex(of: UInt8(ascii: "/")).map { secondLastSlash -> Substring in
|
|
filePath[utf8All.index(after: secondLastSlash)..<lastSlash]
|
|
}
|
|
}.map {
|
|
String($0)
|
|
} ?? "n/a"
|
|
}
|
|
|
|
@inlinable
|
|
internal static func currentModule(fileID: String = #fileID) -> String {
|
|
let utf8All = fileID.utf8
|
|
let searchStart: String.UTF8View.Index
|
|
if utf8All.first == UInt8(ascii: "`") {
|
|
guard let closingBacktickIndex = utf8All.dropFirst().firstIndex(of: UInt8(ascii: "`")) else {
|
|
// It should be impossible for a well-formed module to get here, so treat it as an "n/a" case.
|
|
return "n/a"
|
|
}
|
|
// Backticks are part of raw-identifier module names as written in source and mangled, so preserve them.
|
|
searchStart = utf8All.index(after: closingBacktickIndex)
|
|
} else {
|
|
searchStart = utf8All.startIndex
|
|
}
|
|
if let slashIndex = utf8All[searchStart...].firstIndex(of: UInt8(ascii: "/")) {
|
|
return String(fileID[..<slashIndex])
|
|
} else {
|
|
return "n/a"
|
|
}
|
|
}
|
|
}
|
|
|
|
// 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)
|
|
}
|
|
}
|
|
|
|
// 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 .string(let str):
|
|
return str
|
|
case .stringConvertible(let repr):
|
|
return repr.description
|
|
case .array(let list):
|
|
let items = list.map { $0.quotedAsCollectionElement }
|
|
return "[\(items.joined(separator: ", "))]"
|
|
case .dictionary(let dict):
|
|
guard !dict.isEmpty else { return "[:]" }
|
|
let entries = dict.map { key, value in "\(key.debugDescription): \(value.quotedAsCollectionElement)" }
|
|
return "[\(entries.joined(separator: ", "))]"
|
|
}
|
|
}
|
|
|
|
/// Only qute the leaf
|
|
private var quotedAsCollectionElement: String {
|
|
switch self {
|
|
case .string(let str):
|
|
return str.debugDescription
|
|
case .stringConvertible(let repr):
|
|
return repr.description.debugDescription
|
|
case .array, .dictionary:
|
|
return self.description
|
|
}
|
|
}
|
|
}
|
|
|
|
// 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))
|
|
}
|
|
}
|
|
|
|
// 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)
|
|
}
|
|
}
|
|
|
|
// MARK: - Task-local logger storage
|
|
|
|
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
|
extension Logger {
|
|
/// Task-local storage for implicit logger context propagation.
|
|
///
|
|
/// Implementation detail. Use ``Logger/current`` or the `withLogger` free functions instead.
|
|
///
|
|
/// The default value is a `Logger(label: "")` constructed via `LoggingSystem.factory`
|
|
/// the first time the task-local is touched (read or bound) anywhere in the process.
|
|
/// That means whichever backend is configured at first access becomes the unbound
|
|
/// default for the rest of the process — bootstrap before any logging for predictable
|
|
/// behavior.
|
|
@usableFromInline
|
|
static let taskLocalLogger: TaskLocal<Logger> = TaskLocal(wrappedValue: Logger(label: ""))
|
|
|
|
/// Thin wrapper over `TaskLocal.withValue` so call sites don't need to reach into
|
|
/// the task-local storage directly.
|
|
@inlinable
|
|
nonisolated(nonsending) static func withTaskLocalLogger<Return, Failure: Error>(
|
|
_ value: Logger,
|
|
operation: nonisolated(nonsending) () async throws(Failure) -> Return
|
|
) async throws(Failure) -> Return {
|
|
do {
|
|
return try await Self.taskLocalLogger.withValue(value, operation: operation)
|
|
} catch {
|
|
throw error as! Failure
|
|
}
|
|
}
|
|
|
|
@inlinable
|
|
static func withTaskLocalLogger<Return, Failure: Error>(
|
|
_ value: Logger,
|
|
operation: () throws(Failure) -> Return
|
|
) throws(Failure) -> Return {
|
|
do {
|
|
return try Self.taskLocalLogger.withValue(value, operation: operation)
|
|
} catch {
|
|
throw error as! Failure
|
|
}
|
|
}
|
|
|
|
/// The current task-local logger.
|
|
///
|
|
/// Returns the logger bound by the nearest enclosing
|
|
/// ``withLogger(_:_:)-70nli`` scope. If none is active, returns the
|
|
/// process-wide unbound default — a `Logger(label: "")` constructed via
|
|
/// `LoggingSystem.factory` the first time the task-local is touched, then reused for
|
|
/// the lifetime of the process. The empty label is the deliberate diagnostic signal
|
|
/// that no `withLogger` scope was set up before the read.
|
|
///
|
|
/// Because the unbound default is captured at first access, ``LoggingSystem/bootstrap(_:)``
|
|
/// must be called before any task-local logger API is exercised; otherwise the
|
|
/// unbound default uses the swift-log default ``StreamLogHandler`` and a later
|
|
/// bootstrap is not visible to ``current`` outside of a `withLogger` scope.
|
|
///
|
|
/// Task-local values propagate through structured concurrency (`async let`,
|
|
/// `withTaskGroup`, child `Task {}`) but are **not** inherited by `Task.detached`.
|
|
/// Capture the logger explicitly across detached boundaries.
|
|
@inlinable
|
|
public static var current: Logger {
|
|
Self.taskLocalLogger.get()
|
|
}
|
|
}
|
|
|
|
// MARK: - Sendable support helpers
|
|
|
|
extension Logger.MetadataValue: Sendable {}
|
|
|
|
extension Logger: Sendable {}
|
|
extension Logger.Level: Sendable {}
|
|
extension Logger.Message: Sendable {}
|