|
| 1 | +//===----------------------------------------------------------------------===// |
| 2 | +// |
| 3 | +// This source file is part of the Swift Logging API open source project |
| 4 | +// |
| 5 | +// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors |
| 6 | +// Licensed under Apache License v2.0 |
| 7 | +// |
| 8 | +// See LICENSE.txt for license information |
| 9 | +// See CONTRIBUTORS.txt for the list of Swift Logging API project authors |
| 10 | +// |
| 11 | +// SPDX-License-Identifier: Apache-2.0 |
| 12 | +// |
| 13 | +//===----------------------------------------------------------------------===// |
| 14 | + |
| 15 | +extension Logger { |
| 16 | + /// Merge additional metadata into this logger, returning a new instance. |
| 17 | + /// |
| 18 | + /// Creates a copy of this logger with additional metadata merged in. Values in `additionalMetadata` |
| 19 | + /// override existing values for the same keys. The original logger is not modified. |
| 20 | + /// |
| 21 | + /// ```swift |
| 22 | + /// let requestLogger = logger.with(additionalMetadata: ["request.id": "\(requestID)"]) |
| 23 | + /// requestLogger.info("Handling request") |
| 24 | + /// ``` |
| 25 | + /// |
| 26 | + /// - Parameter additionalMetadata: The metadata dictionary to merge. Values in `additionalMetadata` |
| 27 | + /// will override existing values for the same keys. |
| 28 | + /// - Returns: A new `Logger` instance with the merged metadata. |
| 29 | + @inlinable |
| 30 | + public func with(additionalMetadata: Logger.Metadata) -> Logger { |
| 31 | + var newLogger = self |
| 32 | + for (key, value) in additionalMetadata { |
| 33 | + newLogger[metadataKey: key] = value |
| 34 | + } |
| 35 | + return newLogger |
| 36 | + } |
| 37 | + |
| 38 | + /// Update this logger's optional properties in place. |
| 39 | + @usableFromInline |
| 40 | + internal mutating func update( |
| 41 | + logLevel: Logger.Level? = nil, |
| 42 | + mergingMetadata: Logger.Metadata? = nil, |
| 43 | + metadataProvider: Logger.MetadataProvider? = nil |
| 44 | + ) { |
| 45 | + if let logLevel { |
| 46 | + self.logLevel = logLevel |
| 47 | + } |
| 48 | + if let mergingMetadata { |
| 49 | + for (key, value) in mergingMetadata { |
| 50 | + self[metadataKey: key] = value |
| 51 | + } |
| 52 | + } |
| 53 | + if let metadataProvider { |
| 54 | + self.handler.metadataProvider = metadataProvider |
| 55 | + } |
| 56 | + } |
| 57 | +} |
| 58 | + |
| 59 | +// MARK: - withLogger() free functions for task-local logger |
| 60 | + |
| 61 | +// Note on throws(Failure) and Sendable: |
| 62 | +// The public API uses `rethrows` instead of `throws(Failure)` and does not constrain `Result: Sendable` |
| 63 | +// on async variants. This is because the underlying `TaskLocal.withValue` API uses untyped throws, |
| 64 | +// making it impossible to propagate typed throws through the closure chain. Once the standard library |
| 65 | +// adopts typed throws on TaskLocal, these signatures can be updated. |
| 66 | + |
| 67 | +// MARK: Bind a specific logger |
| 68 | + |
| 69 | +/// Runs the given closure with a logger bound to the task-local context. |
| 70 | +/// |
| 71 | +/// This is the primary way to set up a task-local logger. All code within the closure can access the logger |
| 72 | +/// via `Logger.current` without explicit parameter passing. |
| 73 | +/// |
| 74 | +/// ## Example: Setting up task-local logger at application entry point |
| 75 | +/// |
| 76 | +/// ```swift |
| 77 | +/// func main() async { |
| 78 | +/// let logger = Logger(label: "app") |
| 79 | +/// await withLogger(logger) { logger in |
| 80 | +/// logger.info("Application started") |
| 81 | +/// await handleRequests() // All nested code has access via Logger.current |
| 82 | +/// } |
| 83 | +/// } |
| 84 | +/// ``` |
| 85 | +/// |
| 86 | +/// ## Example: Bridging from explicit logger to task-local |
| 87 | +/// |
| 88 | +/// ```swift |
| 89 | +/// func handleRequest(logger: Logger) async { |
| 90 | +/// await withLogger(logger) { _ in |
| 91 | +/// await processRequest() // Now uses Logger.current |
| 92 | +/// } |
| 93 | +/// } |
| 94 | +/// ``` |
| 95 | +/// |
| 96 | +/// > Warning: When nesting `withLogger` calls, always use the closure's `logger` parameter — not a |
| 97 | +/// > captured variable from an outer scope. Using an outer `logger` variable silently loses any metadata |
| 98 | +/// > accumulated by inner `withLogger` calls: |
| 99 | +/// > ```swift |
| 100 | +/// > withLogger(someLogger) { outerLogger in |
| 101 | +/// > withLogger(mergingMetadata: ["key": "value"]) { innerLogger in |
| 102 | +/// > innerLogger.info("correct — has key") // ✓ uses inner logger |
| 103 | +/// > outerLogger.info("wrong — missing key") // ✗ stale outer reference |
| 104 | +/// > } |
| 105 | +/// > } |
| 106 | +/// > ``` |
| 107 | +/// |
| 108 | +/// - Parameters: |
| 109 | +/// - logger: The logger to bind to the task-local context. |
| 110 | +/// - operation: The closure to run with the logger bound. |
| 111 | +/// - Returns: The value returned by the closure. |
| 112 | +@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *) |
| 113 | +@inlinable |
| 114 | +public func withLogger<Result>( |
| 115 | + _ logger: Logger, |
| 116 | + _ operation: (Logger) throws -> Result |
| 117 | +) rethrows -> Result { |
| 118 | + try Logger.withTaskLocalLogger(logger) { |
| 119 | + try operation(logger) |
| 120 | + } |
| 121 | +} |
| 122 | + |
| 123 | +/// Runs the given async closure with a logger bound to the task-local context. |
| 124 | +/// |
| 125 | +/// Async variant of the synchronous `withLogger`. See that function for detailed documentation. |
| 126 | +/// |
| 127 | +/// - Parameters: |
| 128 | +/// - logger: The logger to bind to the task-local context. |
| 129 | +/// - operation: The async closure to run with the logger bound. |
| 130 | +/// - Returns: The value returned by the closure. |
| 131 | +@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *) |
| 132 | +@inlinable |
| 133 | +nonisolated(nonsending) |
| 134 | + public func withLogger<Result>( |
| 135 | + _ logger: Logger, |
| 136 | + _ operation: nonisolated(nonsending) (Logger) async throws -> Result |
| 137 | + ) async rethrows -> Result |
| 138 | +{ |
| 139 | + try await Logger.withTaskLocalLogger(logger) { |
| 140 | + try await operation(logger) |
| 141 | + } |
| 142 | +} |
| 143 | + |
| 144 | +// MARK: Modify current task-local logger |
| 145 | + |
| 146 | +/// Runs the given closure with a modified task-local logger. |
| 147 | +/// |
| 148 | +/// This function modifies the current task-local logger by specifying any combination of log level, |
| 149 | +/// metadata, and metadata provider. Only the specified parameters modify the current logger; `nil` parameters |
| 150 | +/// leave the current values unchanged. |
| 151 | +/// |
| 152 | +/// ## Example: Progressive metadata accumulation |
| 153 | +/// |
| 154 | +/// ```swift |
| 155 | +/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in |
| 156 | +/// logger.info("Handling request") |
| 157 | +/// |
| 158 | +/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in |
| 159 | +/// logger.info("Authenticated") // Has both request.id and user.id |
| 160 | +/// } |
| 161 | +/// } |
| 162 | +/// ``` |
| 163 | +/// |
| 164 | +/// ## Example: Changing log level in a scope |
| 165 | +/// |
| 166 | +/// ```swift |
| 167 | +/// withLogger(logLevel: .debug) { logger in |
| 168 | +/// logger.debug("Detailed debugging information") |
| 169 | +/// } |
| 170 | +/// ``` |
| 171 | +/// |
| 172 | +/// > Important: Task-local values are **not** inherited by detached tasks created with `Task.detached`. |
| 173 | +/// > If you need logger context in a detached task, capture the logger explicitly or use structured |
| 174 | +/// > concurrency (`async let`, `withTaskGroup`, etc.) instead. |
| 175 | +/// |
| 176 | +/// > Warning: The `metadataProvider` parameter **replaces** the logger's existing metadata provider — it does |
| 177 | +/// > not compose with it. If you need to combine multiple providers, use `Logger.MetadataProvider.multiplex()`: |
| 178 | +/// > ```swift |
| 179 | +/// > let combined = Logger.MetadataProvider.multiplex([existingProvider, newProvider]) |
| 180 | +/// > withLogger(metadataProvider: combined) { logger in ... } |
| 181 | +/// > ``` |
| 182 | +/// |
| 183 | +/// - Parameters: |
| 184 | +/// - logLevel: Optional log level. If provided, sets this log level on the logger. |
| 185 | +/// - mergingMetadata: Optional metadata to merge with the current logger's metadata. |
| 186 | +/// - metadataProvider: Optional metadata provider to set on the logger. |
| 187 | +/// - operation: The closure to run with the modified task-local logger. |
| 188 | +/// - Returns: The value returned by the closure. |
| 189 | +@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *) |
| 190 | +@inlinable |
| 191 | +public func withLogger<Result>( |
| 192 | + logLevel: Logger.Level? = nil, |
| 193 | + mergingMetadata: Logger.Metadata? = nil, |
| 194 | + metadataProvider: Logger.MetadataProvider? = nil, |
| 195 | + _ operation: (Logger) throws -> Result |
| 196 | +) rethrows -> Result { |
| 197 | + var logger = Logger.current |
| 198 | + logger.update(logLevel: logLevel, mergingMetadata: mergingMetadata, metadataProvider: metadataProvider) |
| 199 | + return try Logger.withTaskLocalLogger(logger) { |
| 200 | + try operation(logger) |
| 201 | + } |
| 202 | +} |
| 203 | + |
| 204 | +/// Runs the given async closure with a modified task-local logger. |
| 205 | +/// |
| 206 | +/// Async variant. See the synchronous `withLogger(logLevel:mergingMetadata:metadataProvider:_:)` |
| 207 | +/// for detailed documentation. |
| 208 | +/// |
| 209 | +/// - Parameters: |
| 210 | +/// - logLevel: Optional log level. If provided, sets this log level on the logger. |
| 211 | +/// - mergingMetadata: Optional metadata to merge with the current logger's metadata. |
| 212 | +/// - metadataProvider: Optional metadata provider to set on the logger. |
| 213 | +/// - operation: The async closure to run with the modified task-local logger. |
| 214 | +/// - Returns: The value returned by the closure. |
| 215 | +@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *) |
| 216 | +@inlinable |
| 217 | +nonisolated(nonsending) |
| 218 | + public func withLogger<Result>( |
| 219 | + logLevel: Logger.Level? = nil, |
| 220 | + mergingMetadata: Logger.Metadata? = nil, |
| 221 | + metadataProvider: Logger.MetadataProvider? = nil, |
| 222 | + _ operation: nonisolated(nonsending) (Logger) async throws -> Result |
| 223 | + ) async rethrows -> Result |
| 224 | +{ |
| 225 | + var logger = Logger.current |
| 226 | + logger.update(logLevel: logLevel, mergingMetadata: mergingMetadata, metadataProvider: metadataProvider) |
| 227 | + return try await Logger.withTaskLocalLogger(logger) { |
| 228 | + try await operation(logger) |
| 229 | + } |
| 230 | +} |
0 commit comments