mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
This proposal adds task-local logger storage so that metadata can accumulate across async call stacks without threading a `Logger` through every function signature. ### Motivation: Metadata propagation requires threading a logger through every layer. Every function on the path from request ingress to the bottom of the call stack has to accept, mutate, and forward a `Logger`. Libraries must choose between polluting their public API with a `logger:` parameter and losing all the caller's context. There is no third option today. ### Modifications: - New API surface for reading and modifying the `@TaskLocal` `Logger` instance added. - Best practices on how to correctly propagate logger into libraries updated with `Logger.current` API. ### Result: Users can now automatically propagate accumulated metadata into libraries without explicitly passing loggers through the API boundaries. --------- Co-authored-by: Franz Busch <privat@franz-busch.de>
228 lines
9.4 KiB
Swift
228 lines
9.4 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
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
/// 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: Sendable {
|
|
private static let _factory = FactoryBox(
|
|
{ label, _ in StreamLogHandler.standardError(label: label) },
|
|
violationErrorMesage: "logging system can only be initialized once per process."
|
|
)
|
|
private static let _metadataProviderFactory = MetadataProviderBox(
|
|
nil,
|
|
violationErrorMesage: "logging system can only be initialized once per process."
|
|
)
|
|
|
|
#if DEBUG
|
|
private static let _warnOnceBox: WarnOnceBox = WarnOnceBox()
|
|
#endif
|
|
|
|
/// 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 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(
|
|
{ label, _ in
|
|
factory(label)
|
|
},
|
|
validate: true
|
|
)
|
|
}
|
|
|
|
/// 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:
|
|
/// - metadataProvider: The `MetadataProvider` used to inject runtime-generated metadata from the execution context.
|
|
/// - 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,
|
|
metadataProvider: Logger.MetadataProvider?
|
|
) {
|
|
self._metadataProviderFactory.replace(metadataProvider, validate: true)
|
|
self._factory.replace(factory, validate: true)
|
|
}
|
|
|
|
// for our testing we want to allow multiple bootstrapping
|
|
internal static func bootstrapInternal(_ factory: @escaping @Sendable (String) -> any LogHandler) {
|
|
self._metadataProviderFactory.replace(nil, validate: false)
|
|
self._factory.replace(
|
|
{ label, _ in
|
|
factory(label)
|
|
},
|
|
validate: false
|
|
)
|
|
}
|
|
|
|
// for our testing we want to allow multiple bootstrapping
|
|
internal static func bootstrapInternal(
|
|
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
|
|
metadataProvider: Logger.MetadataProvider?
|
|
) {
|
|
self._metadataProviderFactory.replace(metadataProvider, validate: false)
|
|
self._factory.replace(factory, validate: false)
|
|
}
|
|
|
|
internal static var factory: (String, Logger.MetadataProvider?) -> any LogHandler {
|
|
{ label, metadataProvider in
|
|
self._factory.underlying(label, metadataProvider)
|
|
}
|
|
}
|
|
|
|
/// `true` once a user has explicitly called ``bootstrap(_:)`` or the metadata-provider
|
|
/// overload; `false` while the system is still using the default `StreamLogHandler`.
|
|
internal static var isBootstrapped: Bool {
|
|
self._factory.isInitialized
|
|
}
|
|
|
|
/// System wide ``Logger/MetadataProvider`` that was configured during the logging system's `bootstrap`.
|
|
///
|
|
/// When creating a ``Logger`` using the plain ``Logger/init(label:)`` initializer, this metadata provider
|
|
/// will be provided to it.
|
|
///
|
|
/// When using custom log handler factories, make sure to provide the bootstrapped metadata provider to them,
|
|
/// or the metadata will not be filled in automatically using the provider on log-sites. While using a custom
|
|
/// factory to avoid using the bootstrapped metadata provider may sometimes be useful, usually it will lead to
|
|
/// un-expected behavior, so make sure to always propagate it to your handlers.
|
|
public static var metadataProvider: Logger.MetadataProvider? {
|
|
self._metadataProviderFactory.underlying
|
|
}
|
|
|
|
#if DEBUG
|
|
/// Used to warn only once about a specific ``LogHandler`` type when it does not support ``Logger/MetadataProvider``,
|
|
/// but an attempt was made to set a metadata provider on such handler. In order to avoid flooding the system with
|
|
/// warnings such warning is only emitted in debug mode, and even then at-most once for a handler type.
|
|
internal static func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(
|
|
_ type: Handler.Type
|
|
) -> Bool {
|
|
self._warnOnceBox.warnOnceLogHandlerNotSupportedMetadataProvider(type: type)
|
|
}
|
|
#endif
|
|
|
|
/// Protects an object such that it can only be accessed through a Reader-Writer lock.
|
|
final class RWLockedValueBox<Value: Sendable>: @unchecked Sendable {
|
|
private let lock = ReadWriteLock()
|
|
private var storage: Value
|
|
|
|
init(initialValue: Value) {
|
|
self.storage = initialValue
|
|
}
|
|
|
|
func withReadLock<Result>(_ operation: (Value) -> Result) -> Result {
|
|
self.lock.withReaderLock {
|
|
operation(self.storage)
|
|
}
|
|
}
|
|
|
|
func withWriteLock<Result>(_ operation: (inout Value) -> Result) -> Result {
|
|
self.lock.withWriterLock {
|
|
operation(&self.storage)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// 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<BoxedType: Sendable> {
|
|
private struct ReplaceOnce: Sendable {
|
|
private(set) var initialized = false
|
|
private var _underlying: BoxedType
|
|
private let violationErrorMessage: String
|
|
|
|
mutating func replaceUnderlying(_ underlying: BoxedType, validate: Bool) {
|
|
precondition(!validate || !self.initialized, self.violationErrorMessage)
|
|
self._underlying = underlying
|
|
self.initialized = true
|
|
}
|
|
|
|
var underlying: BoxedType {
|
|
self._underlying
|
|
}
|
|
|
|
init(underlying: BoxedType, violationErrorMessage: String) {
|
|
self._underlying = underlying
|
|
self.violationErrorMessage = violationErrorMessage
|
|
}
|
|
}
|
|
|
|
private let storage: RWLockedValueBox<ReplaceOnce>
|
|
|
|
init(_ underlying: BoxedType, violationErrorMesage: String) {
|
|
self.storage = .init(
|
|
initialValue: ReplaceOnce(
|
|
underlying: underlying,
|
|
violationErrorMessage: violationErrorMesage
|
|
)
|
|
)
|
|
}
|
|
|
|
func replace(_ newUnderlying: BoxedType, validate: Bool) {
|
|
self.storage.withWriteLock { $0.replaceUnderlying(newUnderlying, validate: validate) }
|
|
}
|
|
|
|
var underlying: BoxedType {
|
|
self.storage.withReadLock { $0.underlying }
|
|
}
|
|
|
|
var isInitialized: Bool {
|
|
self.storage.withReadLock { $0.initialized }
|
|
}
|
|
}
|
|
|
|
private typealias FactoryBox = ReplaceOnceBox<
|
|
@Sendable (_ label: String, _ provider: Logger.MetadataProvider?) -> any LogHandler
|
|
>
|
|
|
|
private typealias MetadataProviderBox = ReplaceOnceBox<Logger.MetadataProvider?>
|
|
}
|
|
|
|
// MARK: - Debug only warnings
|
|
|
|
#if DEBUG
|
|
/// Contains state to manage all kinds of "warn only once" warnings which the logging system may want to issue.
|
|
private final class WarnOnceBox: @unchecked Sendable {
|
|
private let lock: Lock = Lock()
|
|
private var warnOnceLogHandlerNotSupportedMetadataProviderPerType = Set<ObjectIdentifier>()
|
|
|
|
func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(type: Handler.Type) -> Bool {
|
|
self.lock.withLock {
|
|
let id = ObjectIdentifier(type)
|
|
let (inserted, _) = warnOnceLogHandlerNotSupportedMetadataProviderPerType.insert(id)
|
|
return inserted // warn about this handler type, it is the first time we encountered it
|
|
}
|
|
}
|
|
}
|
|
#endif
|