mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
c9c6bb9d27 | ||
|
|
6404842475 | ||
|
|
fcd893317d | ||
|
|
65b3417512 | ||
|
|
666b45a252 | ||
|
|
4038b6a4f7 | ||
|
|
109c380c23 | ||
|
|
c29472f010 | ||
|
|
bca880e799 | ||
|
|
c581740960 | ||
|
|
9c9acde6dc | ||
|
|
cf3e828428 | ||
|
|
3be27be290 | ||
|
|
9c6fb14227 | ||
|
|
53d00853e6 | ||
|
|
c5ece24786 | ||
|
|
172948a4b5 | ||
|
|
47a917767f | ||
|
|
f054da4c19 | ||
|
|
3ffafb9722 | ||
|
|
7af2de138f | ||
|
|
e83726cb15 | ||
|
|
8056dbfb08 | ||
|
|
1032aed8a5 | ||
|
|
1895d78a91 | ||
|
|
8a6b9eab84 | ||
|
|
c4e96785bf | ||
|
|
54ec9e35cd | ||
|
|
e3b5d65fc9 | ||
|
|
a878e7f8f4 | ||
|
|
2c52ee25d2 | ||
|
|
ca61184698 |
No files matched your search
@@ -14,19 +14,21 @@ jobs:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_1_enabled: false
|
||||
linux_6_4_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_1_enabled: true
|
||||
windows_6_1_enabled: false
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_6_4_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_4_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
|
||||
@@ -36,6 +38,7 @@ jobs:
|
||||
with:
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
macos_swift_6_3_enabled: true
|
||||
macos_swift_6_4_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
@@ -52,8 +55,11 @@ jobs:
|
||||
with:
|
||||
runner_pool: nightly
|
||||
build_scheme: swift-log-Package
|
||||
debug_output_enabled: true
|
||||
macos_xcode_test_enabled: false
|
||||
swift_6_1_enabled: false
|
||||
swift_6_2_enabled: true
|
||||
swift_6_3_enabled: true
|
||||
swift_6_4_enabled: true
|
||||
macos_xcode_test_enabled: true
|
||||
ios_xcode_test_enabled: false
|
||||
watchos_xcode_test_enabled: false
|
||||
tvos_xcode_test_enabled: false
|
||||
@@ -74,8 +80,9 @@ jobs:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_1_enabled: true
|
||||
windows_6_1_enabled: false
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_6_4_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
@@ -10,7 +10,7 @@ on:
|
||||
jobs:
|
||||
soundness:
|
||||
name: Soundness
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.11
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.16
|
||||
with:
|
||||
license_header_check_project_name: "Swift Logging API"
|
||||
|
||||
@@ -18,19 +18,21 @@ jobs:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_1_enabled: false
|
||||
linux_6_4_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_1_enabled: true
|
||||
windows_6_1_enabled: false
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_6_4_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_4_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
|
||||
@@ -41,6 +43,7 @@ jobs:
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
macos_runner_pool: general
|
||||
macos_swift_6_3_enabled: true
|
||||
macos_swift_6_4_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
@@ -58,6 +61,15 @@ jobs:
|
||||
runner_pool: general
|
||||
build_scheme: swift-log-Package
|
||||
swift_test_enabled: true
|
||||
swift_6_1_enabled: false
|
||||
swift_6_2_enabled: true
|
||||
swift_6_3_enabled: true
|
||||
swift_6_4_enabled: true
|
||||
macos_xcode_test_enabled: true
|
||||
ios_xcode_test_enabled: false
|
||||
watchos_xcode_test_enabled: false
|
||||
tvos_xcode_test_enabled: false
|
||||
visionos_xcode_test_enabled: false
|
||||
|
||||
android:
|
||||
name: Android Swift SDK
|
||||
@@ -68,9 +80,10 @@ jobs:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_1_enabled: true
|
||||
windows_6_1_enabled: false
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_6_4_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
|
||||
@@ -79,3 +92,16 @@ jobs:
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
with:
|
||||
nightly_next_enabled: false
|
||||
|
||||
cmake-lists:
|
||||
name: Check CMake Lists
|
||||
uses: apple/swift-nio/.github/workflows/cmake_tests.yml@main
|
||||
with:
|
||||
image: "swift:6.2-jammy"
|
||||
update_cmake_lists_config: >-
|
||||
{
|
||||
"targets": [
|
||||
{ "name": "Logging", "type": "source", "exceptions": [] },
|
||||
{ "name": "InMemoryLogging", "type": "source", "exceptions": [] }
|
||||
]
|
||||
}
|
||||
@@ -14,7 +14,7 @@ jobs:
|
||||
timeout-minutes: 1
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v6
|
||||
uses: actions/checkout@v7
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Check for Semantic Version label
|
||||
|
||||
@@ -19,19 +19,19 @@ let package = Package(
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "MaxLogLevelNone",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/MaxLogLevelNoneBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
.plugin(name: "BenchmarkPlugin", package: "benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"instructions" : 734,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"instructions" : 734,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"instructions" : 734,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"instructions" : 710,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 810,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 803,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 803,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 803,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -19,19 +19,19 @@ let package = Package(
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "MaxLogLevelWarning",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/MaxLogLevelWarningBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
.plugin(name: "BenchmarkPlugin", package: "benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 662,
|
||||
"instructions" : 734,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 662,
|
||||
"instructions" : 734,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"instructions" : 689,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1892,
|
||||
"instructions" : 1993,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1892,
|
||||
"instructions" : 1968,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 815,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 970,
|
||||
"instructions" : 750,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 775,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 2008,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 2002,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -18,12 +18,38 @@ import Foundation
|
||||
import Logging
|
||||
|
||||
public let benchmarks: @Sendable () -> Void = {
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_generic") { logger in
|
||||
logger.log(level: .error, "hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_generic") { logger in
|
||||
logger.log(level: .debug, "hello, benchmarking world")
|
||||
}
|
||||
|
||||
// MARK: - Task-local logger benchmarks
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_current_read_fallback") { _ in
|
||||
blackHole(Logger.current)
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_current_read_inside_scope") {
|
||||
logger in
|
||||
blackHole(Logger.current)
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_withLogger_mergingMetadata") {
|
||||
logger in
|
||||
withLogger(mergingMetadata: ["key": "value"]) { inner in
|
||||
blackHole(inner)
|
||||
}
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_withLogger_handler") { logger in
|
||||
withLogger(handler: logger.handler) { inner in
|
||||
blackHole(inner)
|
||||
}
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_1_attribute") { logger in
|
||||
logger.log(
|
||||
level: .error,
|
||||
@@ -60,4 +86,21 @@ public let benchmarks: @Sendable () -> Void = {
|
||||
]
|
||||
)
|
||||
}
|
||||
|
||||
// MARK: - metadata serialization performance
|
||||
|
||||
func nestedArrayMetadataValue(depth: Int) -> Logger.MetadataValue {
|
||||
var value: Logger.MetadataValue = .string("leaf")
|
||||
for _ in 0..<depth {
|
||||
value = .array([value])
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
for depth in [1, 5, 20, 1_000] {
|
||||
let nested = nestedArrayMetadataValue(depth: depth)
|
||||
makeBenchmark(loggerLevel: .info, logLevel: .debug, "_metadata_nesting_depth_\(depth)") { _ in
|
||||
blackHole(nested.description)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -18,19 +18,19 @@ let package = Package(
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "NoTraits",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/NoTraitsBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
.plugin(name: "BenchmarkPlugin", package: "benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 985,
|
||||
"instructions" : 1050,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 985,
|
||||
"instructions" : 1050,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 970,
|
||||
"instructions" : 1046,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5483,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 4939775,
|
||||
"objectAllocCount" : 2016
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 82239,
|
||||
"objectAllocCount" : 37
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 18351,
|
||||
"objectAllocCount" : 6
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 5855,
|
||||
"instructions" : 6200,
|
||||
"objectAllocCount" : 2
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 7075,
|
||||
"instructions" : 7600,
|
||||
"objectAllocCount" : 3
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 970,
|
||||
"instructions" : 1005,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1017,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1890,
|
||||
"instructions" : 1966,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 4551,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 9623,
|
||||
"objectAllocCount" : 4
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1119,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1119,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1117,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5327,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 4263935,
|
||||
"objectAllocCount" : 2016
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 69119,
|
||||
"objectAllocCount" : 37
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 15471,
|
||||
"objectAllocCount" : 6
|
||||
}
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 5851,
|
||||
"instructions" : 6851,
|
||||
"objectAllocCount" : 2
|
||||
}
|
||||
}
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 7055,
|
||||
"instructions" : 8399,
|
||||
"objectAllocCount" : 3
|
||||
}
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1095,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1038,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1972,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 4171,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 10231,
|
||||
"objectAllocCount" : 4
|
||||
}
|
||||
@@ -12,14 +12,14 @@ let package = Package(
|
||||
.library(name: "BenchmarksFactory", targets: ["BenchmarksFactory"])
|
||||
],
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
|
||||
.package(path: "../"), // swift-log
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "BenchmarksFactory",
|
||||
dependencies: [
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
]
|
||||
)
|
||||
|
||||
@@ -19,6 +19,7 @@ import Logging
|
||||
public func makeBenchmark(
|
||||
loggerLevel: Logger.Level,
|
||||
logLevel: Logger.Level,
|
||||
setScopedLogger: Bool = false,
|
||||
_ suffix: String = "",
|
||||
_ body: @escaping (Logger) -> Void
|
||||
) {
|
||||
@@ -49,7 +50,17 @@ public func makeBenchmark(
|
||||
),
|
||||
]
|
||||
)
|
||||
) { _ in
|
||||
body(logger)
|
||||
) { benchmark in
|
||||
if setScopedLogger {
|
||||
withLogger(logger) { logger in
|
||||
benchmark.startMeasurement()
|
||||
body(logger)
|
||||
benchmark.stopMeasurement()
|
||||
}
|
||||
} else {
|
||||
benchmark.startMeasurement()
|
||||
body(logger)
|
||||
benchmark.stopMeasurement()
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,72 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 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
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
cmake_minimum_required(VERSION 3.19)
|
||||
|
||||
# Initialize C language first to inspect the compiler environment
|
||||
project(swift-log LANGUAGES C)
|
||||
|
||||
# Set Swift compiler target from C compiler target if not manually set for Windows
|
||||
if(WIN32 AND NOT CMAKE_Swift_COMPILER_TARGET)
|
||||
if(CMAKE_C_COMPILER_ARCHITECTURE_ID MATCHES "(ARM64|arm64|aarch64)")
|
||||
set(CMAKE_Swift_COMPILER_TARGET "aarch64-unknown-windows-msvc" CACHE STRING "Swift compiler target triple")
|
||||
elseif(CMAKE_C_COMPILER_ARCHITECTURE_ID MATCHES "(X86|x64|AMD64|x86_64)")
|
||||
set(CMAKE_Swift_COMPILER_TARGET "x86_64-unknown-windows-msvc" CACHE STRING "Swift compiler target triple")
|
||||
endif()
|
||||
endif()
|
||||
|
||||
# Enable Swift after C defines the architecture
|
||||
enable_language(Swift)
|
||||
|
||||
option(BUILD_SHARED_LIBS "Build shared libraries by default" YES)
|
||||
|
||||
set(CMAKE_Swift_LANGUAGE_VERSION 6)
|
||||
|
||||
if(CMAKE_Swift_COMPILER_VERSION VERSION_LESS "6.2")
|
||||
message(FATAL_ERROR "swift-log requires Swift compiler version 6.2 or newer. Detected version: ${CMAKE_Swift_COMPILER_VERSION}")
|
||||
endif()
|
||||
|
||||
set(SWIFT_LOG_COMMON_COMPILE_OPTIONS
|
||||
"SHELL:-enable-upcoming-feature ExistentialAny"
|
||||
"SHELL:-enable-upcoming-feature MemberImportVisibility"
|
||||
"SHELL:-enable-upcoming-feature InternalImportsByDefault"
|
||||
"SHELL:-enable-upcoming-feature NonisolatedNonsendingByDefault"
|
||||
"SHELL:-Xfrontend -require-explicit-sendable"
|
||||
"SHELL:-package-name swift_log")
|
||||
|
||||
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
|
||||
|
||||
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
|
||||
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
|
||||
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
|
||||
|
||||
set(CMAKE_Swift_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/swift)
|
||||
|
||||
if(MSVC)
|
||||
message(STATUS "MSVC condition triggered successfully!")
|
||||
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
|
||||
set(CMAKE_Swift_COMPILE_OPTIONS_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
|
||||
endif()
|
||||
|
||||
include(GNUInstallDirs)
|
||||
include(SwiftSupport)
|
||||
|
||||
if(NOT APPLE)
|
||||
find_package(dispatch QUIET)
|
||||
find_package(Foundation QUIET)
|
||||
endif()
|
||||
|
||||
add_subdirectory(Sources)
|
||||
|
||||
add_subdirectory(cmake/modules)
|
||||
+4
-4
@@ -87,15 +87,15 @@ directory, for example:
|
||||
## Benchmarks
|
||||
|
||||
Benchmarks for `swift-log` are in a separate Swift Package in the `Benchmarks` subfolder of this repository.
|
||||
They use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin.
|
||||
Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `package-benchmark` to capture memory allocation statistics.
|
||||
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `package-benchmark`.
|
||||
They use the [`benchmark`](https://github.com/ordo-one/benchmark) plugin.
|
||||
On Swift versions prior to 6.3 Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `benchmark` to capture memory allocation statistics.
|
||||
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `benchmark`.
|
||||
Afterwards you can run the benchmarks from CLI by going to the `Benchmarks` subfolder (e.g. `cd Benchmarks`) and invoking:
|
||||
```
|
||||
swift package benchmark
|
||||
```
|
||||
|
||||
For more information please refer to `swift package benchmark --help` or the [documentation of `package-benchmark`](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark).
|
||||
For more information please refer to `swift package benchmark --help` or the [documentation of `benchmark`](https://swiftpackageindex.com/ordo-one/benchmark/documentation/benchmark).
|
||||
|
||||
|
||||
## How to contribute your work
|
||||
|
||||
+4
-2
@@ -29,11 +29,13 @@ let package = Package(
|
||||
targets: [
|
||||
.target(
|
||||
name: "Logging",
|
||||
dependencies: []
|
||||
dependencies: [],
|
||||
exclude: ["CMakeLists.txt"]
|
||||
),
|
||||
.target(
|
||||
name: "InMemoryLogging",
|
||||
dependencies: ["Logging"]
|
||||
dependencies: ["Logging"],
|
||||
exclude: ["CMakeLists.txt"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "LoggingTests",
|
||||
|
||||
@@ -1,66 +0,0 @@
|
||||
// swift-tools-version:6.1
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-log",
|
||||
products: [
|
||||
.library(name: "Logging", targets: ["Logging"]),
|
||||
.library(name: "InMemoryLogging", targets: ["InMemoryLogging"]),
|
||||
],
|
||||
traits: [
|
||||
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
|
||||
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
|
||||
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
|
||||
.trait(
|
||||
name: "MaxLogLevelWarning",
|
||||
description: "Warning and above available (compiles out trace, debug, info, notice)"
|
||||
),
|
||||
.trait(
|
||||
name: "MaxLogLevelError",
|
||||
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
|
||||
),
|
||||
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
|
||||
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
|
||||
|
||||
// By default, no traits are enabled (all log levels available)
|
||||
.default(enabledTraits: []),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "Logging",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "InMemoryLogging",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "LoggingTests",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "InMemoryLoggingTests",
|
||||
dependencies: ["InMemoryLogging", "Logging"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
for target in package.targets
|
||||
where [.executable, .test, .regular].contains(
|
||||
target.type
|
||||
) {
|
||||
var settings = target.swiftSettings ?? []
|
||||
|
||||
// https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md
|
||||
// Require `any` for existential types.
|
||||
settings.append(.enableUpcomingFeature("ExistentialAny"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
|
||||
settings.append(.enableUpcomingFeature("MemberImportVisibility"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
|
||||
settings.append(.enableUpcomingFeature("InternalImportsByDefault"))
|
||||
|
||||
target.swiftSettings = settings
|
||||
}
|
||||
@@ -22,7 +22,7 @@ choose from the many
|
||||
The following snippet shows how to add SwiftLog to your Swift Package:
|
||||
|
||||
```swift
|
||||
// swift-tools-version: 6.1
|
||||
// swift-tools-version: 6.2
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
@@ -67,3 +67,8 @@ The community has built numerous specialized logging backends.
|
||||
A great way to discover available log backend implementations is searching the
|
||||
[Swift Package Index](https://swiftpackageindex.com/search?query=swift-log)
|
||||
for the `swift-log` keyword.
|
||||
|
||||
## Building with CMake
|
||||
|
||||
While Swift Package Manager (SPM) is the primary build system for development and testing, CMake build support is also available for integrated or mixed build environments if needed. Note that tests are not included in the CMake build, they are managed through Swift Package Manager with `swift test`.
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 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
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
add_subdirectory(Logging)
|
||||
add_subdirectory(InMemoryLogging)
|
||||
@@ -0,0 +1,28 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 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
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
add_library(InMemoryLogging
|
||||
"InMemoryLogHandler.swift"
|
||||
)
|
||||
|
||||
set_target_properties(InMemoryLogging PROPERTIES
|
||||
INTERFACE_INCLUDE_DIRECTORIES "$<BUILD_INTERFACE:$<TARGET_PROPERTY:Swift_MODULE_DIRECTORY>>;$<BUILD_INTERFACE:$<TARGET_FILE_DIR:InMemoryLogging>>")
|
||||
|
||||
target_compile_options(InMemoryLogging PRIVATE
|
||||
${SWIFT_LOG_COMMON_COMPILE_OPTIONS})
|
||||
|
||||
target_link_libraries(InMemoryLogging PRIVATE Logging)
|
||||
|
||||
_install_target(InMemoryLogging)
|
||||
set_property(GLOBAL APPEND PROPERTY SwiftLog_EXPORTS InMemoryLogging)
|
||||
@@ -0,0 +1,36 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 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
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
add_library(Logging
|
||||
"Handlers/MultiplexLogHandler.swift"
|
||||
"Handlers/StreamLogHandler.swift"
|
||||
"Handlers/SwiftLogNoOpLogHandler.swift"
|
||||
"Locks.swift"
|
||||
"LogEvent.swift"
|
||||
"LogHandler.swift"
|
||||
"Logger+Attributes.swift"
|
||||
"Logger+With.swift"
|
||||
"Logger.swift"
|
||||
"LoggingSystem.swift"
|
||||
"MetadataProvider.swift"
|
||||
)
|
||||
|
||||
set_target_properties(Logging PROPERTIES
|
||||
INTERFACE_INCLUDE_DIRECTORIES "$<BUILD_INTERFACE:$<TARGET_PROPERTY:Swift_MODULE_DIRECTORY>>;$<BUILD_INTERFACE:$<TARGET_FILE_DIR:Logging>>")
|
||||
|
||||
target_compile_options(Logging PRIVATE
|
||||
${SWIFT_LOG_COMMON_COMPILE_OPTIONS})
|
||||
|
||||
_install_target(Logging)
|
||||
set_property(GLOBAL APPEND PROPERTY SwiftLog_EXPORTS Logging)
|
||||
@@ -1,29 +1,88 @@
|
||||
# 003: Accepting loggers in libraries
|
||||
# 003: Logger propagation in libraries
|
||||
|
||||
Accept loggers through method parameters to ensure proper metadata propagation.
|
||||
Propagate caller context by accepting a `Logger` parameter or reading the task-local
|
||||
``Logger/current`` — never by constructing your own logger.
|
||||
|
||||
## Overview
|
||||
|
||||
Libraries should accept logger instances through method parameters rather than
|
||||
storing them as instance variables. This practice ensures metadata (such as
|
||||
correlation IDs) is properly propagated down the call stack, while giving
|
||||
applications control over logging configuration.
|
||||
Libraries should obtain a `Logger` in one of two ways: accept one through a method
|
||||
parameter or read ``Logger/current`` from the task-local. Both approaches
|
||||
preserve the caller's metadata, log level, and handler choice. Constructing a logger
|
||||
inside a library — via ``Logger/init(label:)`` — takes those choices away from the
|
||||
application and breaks metadata propagation.
|
||||
|
||||
### Motivation
|
||||
|
||||
When libraries accept loggers as method parameters, they enable automatic
|
||||
propagation of contextual metadata attached to the logger instance. This is
|
||||
especially important for distributed systems where correlation IDs must flow
|
||||
through the entire request processing pipeline.
|
||||
The application controls logging: which backend, which log level, which metadata
|
||||
travels with each request. Libraries that participate in this picture obtain a logger
|
||||
the application has set up, rather than constructing their own from scratch. This
|
||||
ensures correlation IDs and other contextual metadata flow through the entire call
|
||||
stack, and gives the application a single place to redirect or filter all log output.
|
||||
|
||||
Two propagation mechanisms are available, and they coexist. Choose the explicit
|
||||
parameter when the library's API already accepts a `Logger` (or it's natural to add
|
||||
one) — the call site stays declarative about what gets logged where. Choose the
|
||||
task-local when adding a `logger:` parameter would pollute an API that otherwise has
|
||||
no logging concern in its signature. Application code binds the initial task-local;
|
||||
library code reads it and updates the metadata.
|
||||
|
||||
### Example
|
||||
|
||||
#### Recommended: Accept logger through method parameters
|
||||
#### Recommended: Read ``Logger/current`` from the task-local
|
||||
|
||||
When there is no `logger:` parameter in the API, read the
|
||||
task-local. The application's accumulated metadata (`request.id`, etc.) flows in
|
||||
automatically without an explicit hand-off.
|
||||
|
||||
```swift
|
||||
// ✅ Good: Pass the logger through method parameters.
|
||||
// ✅ Good: Library reads Logger.current; caller scopes context via withLogger.
|
||||
public struct AnalyticsClient {
|
||||
public func track(_ event: String) {
|
||||
Logger.current.info("event", metadata: ["event.name": "\(event)"])
|
||||
}
|
||||
}
|
||||
|
||||
// Application binds at @main and scopes per-request metadata.
|
||||
@main
|
||||
struct MyServer {
|
||||
static func main() async throws {
|
||||
let logger = Logger(label: "my-server")
|
||||
try await withLogger(logger) { _ in
|
||||
try await runServices()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func handleRequest(_ req: HTTPRequest) async throws {
|
||||
try await withLogger(mergingMetadata: ["request.id": "\(req.id)"]) { _ in
|
||||
AnalyticsClient().track("request.received") // sees request.id automatically
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For per-statement metadata, pass it via the `metadata:` parameter on the log call:
|
||||
|
||||
```swift
|
||||
Logger.current.info("step", metadata: ["step.name": "validate"])
|
||||
```
|
||||
|
||||
For a few back-to-back lines, take a local copy and stamp metadata there — also no
|
||||
propagation:
|
||||
|
||||
```swift
|
||||
var local = Logger.current
|
||||
local[metadataKey: "step.name"] = "validate"
|
||||
local.info("entering")
|
||||
local.info("done")
|
||||
```
|
||||
|
||||
#### Alternative: Accept logger through method parameters
|
||||
|
||||
```swift
|
||||
// ✅ Good: Pass the logger through method parameters,
|
||||
// default to Logger.current in the public API.
|
||||
struct RequestProcessor {
|
||||
func processRequest(_ request: HTTPRequest, logger: Logger) async throws -> HTTPResponse {
|
||||
func processRequest(_ request: HTTPRequest, logger: Logger = Logger.current) async throws -> HTTPResponse {
|
||||
// Add structured metadata that every log statement should contain.
|
||||
var logger = logger
|
||||
logger[metadataKey: "request.method"] = "\(request.method)"
|
||||
@@ -31,44 +90,40 @@ struct RequestProcessor {
|
||||
logger[metadataKey: "request.id"] = "\(request.id)"
|
||||
|
||||
logger.debug("Processing request")
|
||||
|
||||
|
||||
// Pass the logger down to maintain metadata context.
|
||||
let validatedData = try validateRequest(request, logger: logger)
|
||||
let result = try await executeBusinessLogic(validatedData, logger: logger)
|
||||
|
||||
|
||||
logger.debug("Request processed successfully")
|
||||
return result
|
||||
}
|
||||
|
||||
|
||||
private func validateRequest(_ request: HTTPRequest, logger: Logger) throws -> ValidatedRequest {
|
||||
logger.debug("Validating request parameters")
|
||||
// Include validation logic that uses the same logger context.
|
||||
return ValidatedRequest(request)
|
||||
}
|
||||
|
||||
|
||||
private func executeBusinessLogic(_ data: ValidatedRequest, logger: Logger) async throws -> HTTPResponse {
|
||||
logger.debug("Executing business logic")
|
||||
|
||||
// Further propagate the logger to other services.
|
||||
let dbResult = try await databaseService.query(data.query, logger: logger)
|
||||
|
||||
logger.debug("Business logic completed")
|
||||
return HTTPResponse(data: dbResult)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Alternative: Accept logger through initializer when appropriate
|
||||
#### Alternative: Accept logger through initializer for long-lived components
|
||||
|
||||
```swift
|
||||
// ✅ Acceptable: Logger through initializer for long-lived components
|
||||
// ⚠️ Acceptable: Logger through initializer for long-lived components
|
||||
final class BackgroundJobProcessor {
|
||||
private let logger: Logger
|
||||
|
||||
|
||||
init(logger: Logger) {
|
||||
self.logger = logger
|
||||
}
|
||||
|
||||
|
||||
func run() async {
|
||||
// Execute some long running work
|
||||
logger.debug("Update about long running work")
|
||||
@@ -79,22 +134,52 @@ final class BackgroundJobProcessor {
|
||||
|
||||
#### Avoid: Libraries creating their own loggers
|
||||
|
||||
Libraries might create their own loggers; however, this leads to two problems.
|
||||
First, users of the library can't inject their own loggers which means they have
|
||||
no control in customizing the log level or log handler. Secondly, it breaks the
|
||||
metadata propagation since users can't pass in a logger with already attached
|
||||
metadata.
|
||||
Constructing ``Logger/init(label:)`` inside a library takes control over the handler, log
|
||||
level, and base metadata away from the application. The application cannot redirect,
|
||||
filter, or silence the library's output.
|
||||
|
||||
```swift
|
||||
// ❌ Bad: Library creates its own logger
|
||||
// ❌ Bad: Library creates its own logger — loses caller's context.
|
||||
final class MyLibrary {
|
||||
private let logger = Logger(label: "MyLibrary") // Loses all context
|
||||
}
|
||||
|
||||
// ✅ Good: Library accepts logger from caller
|
||||
final class MyLibrary {
|
||||
func operation(logger: Logger) {
|
||||
// Maintains caller's context and metadata
|
||||
}
|
||||
private let logger = Logger(label: "MyLibrary")
|
||||
}
|
||||
```
|
||||
|
||||
``Logger/init(label:)`` is for the application — typically at `@main` paired with `.withLogger()`.
|
||||
Library code, including internal application modules, should not construct loggers.
|
||||
If they do, setting up the global factory with ``LoggingSystem/bootstrap(_:)`` allows
|
||||
enforcing a specific factory on all the loggers constructed in the process. This
|
||||
does not necessary need to be the same factory as was used to create the task-local
|
||||
logger.
|
||||
|
||||
#### Avoid: Relying on ``Logger/current`` across non-Task boundaries
|
||||
|
||||
``Logger/current`` is backed by a `TaskLocal` and propagates through Swift's structured
|
||||
concurrency model only. Callbacks invoked on non-Task threads — GCD blocks,
|
||||
`URLSession` completion handlers, delegate methods dispatched onto specific queues,
|
||||
`NotificationCenter` observers, C-API callbacks — see the *default* fallback logger,
|
||||
not the bound one. Metadata bound by the calling `Task` is invisible inside those
|
||||
callbacks.
|
||||
|
||||
```swift
|
||||
// ❌ Bad: completion handler runs without the Task context; Logger.current is the fallback.
|
||||
try await withLogger(mergingMetadata: ["request.id": "r1"]) { _ in
|
||||
URLSession.shared.dataTask(with: req) { data, _, _ in
|
||||
Logger.current.info("response") // empty-label fallback, no request.id
|
||||
}.resume()
|
||||
}
|
||||
```
|
||||
|
||||
For libraries with async completion-handler APIs, accept an explicit `Logger` parameter.
|
||||
If capturing and rebinding across the boundary is the only option:
|
||||
|
||||
```swift
|
||||
// ✅ Good: capture before the boundary, rebind on the other side.
|
||||
try await withLogger(mergingMetadata: ["request.id": "r1"]) { captured in
|
||||
URLSession.shared.dataTask(with: req) { data, _, _ in
|
||||
withLogger(captured) { _ in // Bind Logger.current inside the callback
|
||||
Logger.current.info("response") // Logger.current now has request.id
|
||||
}
|
||||
}.resume()
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,81 @@
|
||||
# 004: Testing code that logs
|
||||
|
||||
Validate what you code logs by capturing entries in memory rather than bootstrapping a process-wide backend.
|
||||
|
||||
## Overview
|
||||
|
||||
Import and use `InMemoryLogging`, which provides an `InMemoryLogHandler` that collects every emitted record into an array you can inspect.
|
||||
Keep a handler you create local to each test.
|
||||
Each handler that you create in a test has no shared state, so the test stays isolated is safe to run on parallel with other tests.
|
||||
Don't use ``LoggingSystem/bootstrap(_:)`` in a test, it sets one process-wide backend and traps if called twice.
|
||||
|
||||
Add the product to your test target:
|
||||
|
||||
```swift
|
||||
.product(name: "InMemoryLogging", package: "swift-log")
|
||||
```
|
||||
|
||||
### Capture logs from a logger you pass in
|
||||
|
||||
When the code under test accepts a `Logger` (see <doc:003-AcceptingLoggers>), back it with
|
||||
an `InMemoryLogHandler` and validate the results on `entries`.
|
||||
|
||||
The following code illustrates how to set up and validate a handler using `InMemoryLogging` to check the expected results:
|
||||
|
||||
```swift
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct RequestProcessor {
|
||||
func handle(id: String, logger: Logger) {
|
||||
logger.info("request received", metadata: ["request.id": "\(id)"])
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func stampsRequestID() {
|
||||
let handler = InMemoryLogHandler()
|
||||
let logger = Logger(label: "test", factory: { _ in handler })
|
||||
|
||||
RequestProcessor().handle(id: "42", logger: logger)
|
||||
|
||||
#expect(handler.entries.count == 1)
|
||||
#expect(handler.entries[0].message == "request received")
|
||||
#expect(handler.entries[0].metadata["request.id"] == "42")
|
||||
}
|
||||
```
|
||||
|
||||
Each `Entry` is equatable and exposes `level`, `message`, `metadata`, and `error`.
|
||||
The handler log level defaults to ``Logger/Level/info``; set `handler.logLevel = .trace` before you use it to
|
||||
capture lower levels.
|
||||
|
||||
### Capture logs from code that reads `Logger.current`
|
||||
|
||||
When the code you want to test reads the task-local ``Logger/current`` instead of taking a parameter, bind an `InMemoryLogHandler` for the scope of that by using ``withLogger(logLevel:handler:metadata:_:)-2pd9p``.
|
||||
The handler shares its storage by reference, so the copy you hold sees what was logged.
|
||||
|
||||
Bind the handler for the scope of the call and validate the captured entry:
|
||||
|
||||
```swift
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct AnalyticsClient {
|
||||
func track(_ event: String) {
|
||||
Logger.current.info("event", metadata: ["event.name": "\(event)"])
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func tracksEvent() {
|
||||
let handler = InMemoryLogHandler()
|
||||
withLogger(handler: handler) { _ in
|
||||
AnalyticsClient().track("signup") // calls Logger.current.info(...)
|
||||
}
|
||||
|
||||
#expect(handler.entries.count == 1)
|
||||
#expect(handler.entries[0].metadata["event.name"] == "signup")
|
||||
}
|
||||
```
|
||||
@@ -102,6 +102,136 @@ public struct PrintLogHandler: LogHandler {
|
||||
|
||||
```
|
||||
|
||||
### Constructing handlers that need more than a label
|
||||
|
||||
Many log handler backends need more than a `label` in order to construct them: a file path, a remote address, credentials, or
|
||||
a buffer. A handler is an ordinary value that you construct, so nothing constrains its
|
||||
initializer — it can take any parameters it needs, and it can `throw`. There is no
|
||||
protocol-required `init(label:)`. The single `label` argument on factory methods such as
|
||||
`StreamLogHandler.standardOutput(label:)` is a convention, not a requirement.
|
||||
|
||||
Open expensive or fallible resources, such as a file, a socket, early and up front in your own initializer that can `throw`, so that failures surface at setup time.
|
||||
``LogHandler/log(event:)`` cannot throw, so an error deferred to logging time has nowhere to go.
|
||||
Keep the handler `struct` cheap and copyable by placing any shared resource behind a thread-safe reference type.
|
||||
Value semantics apply to a handler's *configuration* — its level and metadata — not its *destination*, so copies writing to
|
||||
the same file are correct and expected.
|
||||
|
||||
The `FileLogHandler` below opens its file once, in an initializer that throws and exception when you create it with an overlapping `Destination`.
|
||||
The handler `struct` itself stays a cheap, copyable value:
|
||||
|
||||
```swift
|
||||
import Foundation
|
||||
import Logging
|
||||
import Synchronization
|
||||
|
||||
/// A log handler that appends formatted log lines to a file on disk.
|
||||
public struct FileLogHandler: LogHandler {
|
||||
/// The shared, thread-safe destination. Open it once, then share it across handlers: because
|
||||
/// the destination is a reference type, all those value-semantic handlers write through a single
|
||||
/// locked file handle.
|
||||
public final class Destination: @unchecked Sendable {
|
||||
private let fileHandle: Mutex<FileHandle>
|
||||
|
||||
/// Opens `url` for appending. All validation happens here, at setup time.
|
||||
public init(writingTo url: URL) throws {
|
||||
let fileManager = FileManager.default
|
||||
if !fileManager.fileExists(atPath: url.path) {
|
||||
guard fileManager.createFile(atPath: url.path, contents: nil) else {
|
||||
throw Failure.cannotCreateFile(url)
|
||||
}
|
||||
}
|
||||
self.fileHandle = .init(try FileHandle(forWritingTo: url))
|
||||
_ = try self.fileHandle.withLock { try $0.seekToEnd() }
|
||||
}
|
||||
|
||||
func write(_ line: String) {
|
||||
// `log(event:)` cannot throw, so a write failure is handled here, not propagated.
|
||||
do {
|
||||
try self.fileHandle.withLock { try $0.write(contentsOf: Data(line.utf8)) }
|
||||
} catch {
|
||||
// Surface the failure without crashing the application.
|
||||
try? FileHandle.standardError.write(contentsOf: Data("FileLogHandler: \(error)\n".utf8))
|
||||
}
|
||||
}
|
||||
|
||||
/// Flushes and closes the file. Call this during shutdown.
|
||||
public func close() {
|
||||
self.fileHandle.withLock { try? $0.close() }
|
||||
}
|
||||
}
|
||||
|
||||
/// Errors thrown while opening a ``Destination``.
|
||||
public enum Failure: Error {
|
||||
case cannotCreateFile(URL)
|
||||
}
|
||||
|
||||
private let label: String
|
||||
private let destination: Destination
|
||||
|
||||
// Per-logger configuration — this is what must carry value semantics.
|
||||
public var logLevel: Logger.Level = .info
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
/// Cheap and non-throwing, so it is safe to call from a bootstrap factory closure per label.
|
||||
public init(label: String, destination: Destination, metadataProvider: Logger.MetadataProvider? = nil) {
|
||||
self.label = label
|
||||
self.destination = destination
|
||||
self.metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
public func log(event: LogEvent) {
|
||||
var merged = self.metadata
|
||||
if let provided = self.metadataProvider?.get() {
|
||||
merged.merge(provided, uniquingKeysWith: { _, new in new })
|
||||
}
|
||||
if let explicit = event.metadata {
|
||||
merged.merge(explicit, uniquingKeysWith: { _, new in new })
|
||||
}
|
||||
let renderedMetadata =
|
||||
merged.isEmpty
|
||||
? ""
|
||||
: " " + merged.sorted { $0.key < $1.key }.map { "\($0.key)=\($0.value)" }.joined(separator: " ")
|
||||
self.destination.write("\(event.level) \(self.label):\(renderedMetadata) \(event.message)\n")
|
||||
}
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[key] }
|
||||
set { self.metadata[key] = newValue }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Using your log handler
|
||||
|
||||
Construct the destination where you can use `try` to build a logger backed by your handler, then bind it
|
||||
as ``Logger/current`` for the application's lifetime using `withLogger`:
|
||||
|
||||
```swift
|
||||
// Open the file once, where setup can throw.
|
||||
let destination = try FileLogHandler.Destination(writingTo: URL(fileURLWithPath: "/var/log/myapp.log"))
|
||||
defer { destination.close() }
|
||||
|
||||
// Build a logger backed by the handler, then bind it for the scope.
|
||||
let logger = Logger(label: "app") { label in
|
||||
FileLogHandler(label: label, destination: destination)
|
||||
}
|
||||
try await withLogger(logger) { logger in
|
||||
logger.info("Application started")
|
||||
// Code in this scope reads the handler through Logger.current.
|
||||
}
|
||||
```
|
||||
|
||||
The `try` on `Destination` is where setup fails if the path is unwritable: validation happens
|
||||
before the logger is constructed, so you never need a throwing factory overload.
|
||||
Use the same pattern for handlers that connect to a remote service:
|
||||
- validate and connect up front
|
||||
- keep ``LogHandler/log(event:)`` non-blocking by buffering onto a background task
|
||||
- provide a `close()` or `shutdown()` (or use [Swift Service Lifecycle](https://github.com/swift-server/swift-service-lifecycle) service) to flush on shutdown
|
||||
|
||||
For runtime failures the handler can't avoid, such as a full disk or a broken pipe, degrade gracefully inside `log(event:)` by dropping the log message, retrying, or reporting to `stderr`.
|
||||
Never call `fatalError` on the logging path.
|
||||
|
||||
### Advanced features
|
||||
|
||||
#### Metadata providers
|
||||
|
||||
@@ -41,3 +41,4 @@ practice includes:
|
||||
- <doc:001-ChoosingLogLevels>
|
||||
- <doc:002-StructuredLogging>
|
||||
- <doc:003-AcceptingLoggers>
|
||||
- <doc:004-TestingLogging>
|
||||
@@ -35,4 +35,15 @@ If you have any questions, ask in an issue on GitHub.
|
||||
|
||||
## Topics
|
||||
|
||||
### Implemented Proposals
|
||||
|
||||
- <doc:SLG-0001-metadata-providers>
|
||||
- <doc:SLG-0002>
|
||||
- <doc:SLG-0003>
|
||||
- <doc:SLG-0004-metadata-value-attributes>
|
||||
- <doc:SLG-0005-log-event-LogHandler-API>
|
||||
- <doc:SLG-0006-task-local-logger>
|
||||
|
||||
### Proposal Template
|
||||
|
||||
- <doc:SLG-NNNN>
|
||||
@@ -6,7 +6,7 @@ Add an extensible per-value attribute mechanism for metadata.
|
||||
|
||||
- Proposal: SLG-0004
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Ready for Implementation**
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#204](https://github.com/apple/swift-log/issues/204)
|
||||
- Implementation:
|
||||
- [apple/swift-log#453](https://github.com/apple/swift-log/pull/453)
|
||||
|
||||
@@ -0,0 +1,439 @@
|
||||
# SLG-0006: Task-local logger with automatic metadata propagation
|
||||
|
||||
Accumulate structured logging metadata across async call stacks using task-local storage.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0006
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#261](https://github.com/apple/swift-log/issues/261)
|
||||
- Implementation: [apple/swift-log#459](https://github.com/apple/swift-log/pull/459)
|
||||
- Feature flag: none
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
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`:
|
||||
|
||||
```swift
|
||||
func handleHTTPRequest(_ request: HTTPRequest, logger: Logger) async throws {
|
||||
var logger = logger
|
||||
logger[metadataKey: "request.id"] = "\(request.id)"
|
||||
try await processBusinessLogic(request, logger: 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.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Use Swift's `@TaskLocal` to propagate a logger with accumulated metadata. The caller sets up
|
||||
a scope, callees read `Logger.current`:
|
||||
|
||||
```swift
|
||||
func handleRequest(_ request: HTTPRequest) async throws -> HTTPResponse {
|
||||
try await withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
logger.info("Handling request") // Has request.id automatically
|
||||
return try await processRequest(request) // no logger parameter needed
|
||||
}
|
||||
}
|
||||
|
||||
func processRequest(_ request: HTTPRequest) async throws -> User {
|
||||
Logger.current.debug("Processing...") // Has request.id automatically
|
||||
DatabaseClient.query(request.sqlQuery)
|
||||
}
|
||||
```
|
||||
|
||||
Libraries keep their APIs clean while still emitting logs with the caller's full context.
|
||||
A library reads `Logger.current` directly — the caller's accumulated metadata flows in
|
||||
automatically without a `logger:` parameter:
|
||||
|
||||
```swift
|
||||
public struct DatabaseClient {
|
||||
public static func query(_ sql: String) async throws -> [Row] {
|
||||
Logger.current.debug("Executing", metadata: ["sql": "\(sql)"])
|
||||
return try await performQuery(sql)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Wiring it up with swift-service-lifecycle.** At the application entry point, bind the
|
||||
bootstrapped logger once; service lifecycle propagates the task-local through the
|
||||
`ServiceGroup` and into every task spawned from its `run()`:
|
||||
|
||||
```swift
|
||||
@main
|
||||
struct MyServer {
|
||||
static func main() async throws {
|
||||
let logger = Logger(label: "my-server")
|
||||
try await withLogger(logger) { _ in
|
||||
let serviceGroup = ServiceGroup(
|
||||
configuration: .init(
|
||||
services: [HTTPServer(), BackgroundWorker()],
|
||||
gracefulShutdownSignals: [.sigint],
|
||||
cancellationSignals: [.sigterm],
|
||||
logger: logger
|
||||
)
|
||||
)
|
||||
try await serviceGroup.run()
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Metadata accumulates through nesting and task-local values propagate through structured
|
||||
concurrency (`async let`, `withTaskGroup`, child `Task {}`). `Task.detached` does not
|
||||
inherit context — capture the logger explicitly if needed.
|
||||
|
||||
### Detailed design
|
||||
|
||||
#### `Logger.current`
|
||||
|
||||
Returns the logger bound by the nearest enclosing `withLogger` 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.
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
/// The current task-local logger.
|
||||
///
|
||||
/// Returns the logger bound by the nearest enclosing ``withLogger(_:_:)`` scope.
|
||||
/// If none is active, returns the process-wide unbound default: a
|
||||
/// `Logger(label: "")` cached from the first time the task-local is touched.
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// For many log calls in a tight scope, prefer extracting the logger once —
|
||||
/// either `let logger = Logger.current` or the closure's `logger` parameter
|
||||
/// from `withLogger { logger in ... }` — instead of re-reading the task-local
|
||||
/// on every call.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
public static var current: Logger { get }
|
||||
}
|
||||
```
|
||||
|
||||
The per-symbol `@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)` mirrors
|
||||
`@TaskLocal`'s own runtime availability.
|
||||
|
||||
#### `withLogger` free functions
|
||||
|
||||
Three overload groups, each with sync and async variants. The closure receives the logger
|
||||
as a parameter to avoid repeated task-local lookups inside the closure body.
|
||||
|
||||
**Bind a specific logger:**
|
||||
|
||||
```swift
|
||||
/// Runs `operation` with `logger` bound to the task-local context.
|
||||
///
|
||||
/// Code called within `operation` can read the logger via ``Logger/current`` without an
|
||||
/// explicit parameter. Binding a different logger with this overload **replaces** the
|
||||
/// current task-local logger; any metadata accumulated by an outer
|
||||
/// ``withLogger(mergingMetadata:_:)`` or
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)`` scope is not carried over.
|
||||
///
|
||||
/// This overload is the application-bootstrap binding mechanism: pass a `Logger`
|
||||
/// constructed via ``Logger/init(label:)`` at your application entry point. Because
|
||||
/// ``Logger/init(label:)`` consults ``LoggingSystem/factory``, the constructed `Logger`
|
||||
/// only carries a useful handler once ``LoggingSystem/bootstrap(_:)`` has been called.
|
||||
/// For mid-call-tree backend swaps that should work without bootstrap (tests, scoped
|
||||
/// routing), use ``withLogger(logLevel:handler:metadata:_:)`` instead — it modifies the
|
||||
/// current logger's handler in place without constructing a new one.
|
||||
///
|
||||
/// let logger = Logger(label: "app")
|
||||
/// await withLogger(logger) { logger in
|
||||
/// logger.info("Application started")
|
||||
/// await handleRequests() // reads Logger.current
|
||||
/// }
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The closure to run with `logger` bound. Receives `logger` as a
|
||||
/// parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result
|
||||
|
||||
/// Runs `operation` with `logger` bound to the task-local context. Async variant of
|
||||
/// ``withLogger(_:_:)``; see that function for full semantics.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The async closure to run with `logger` bound. Receives `logger` as
|
||||
/// a parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result
|
||||
```
|
||||
|
||||
**Append metadata for a scope:**
|
||||
|
||||
```swift
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` **layered on
|
||||
/// top of** the inherited base metadata. Keys present in `metadata` override existing
|
||||
/// keys with the same name; other inherited metadata is preserved. Handler and log
|
||||
/// level are unchanged.
|
||||
///
|
||||
/// Use this overload at request boundaries and any point where context should
|
||||
/// accumulate. Nested ``withLogger(mergingMetadata:_:)`` scopes layer on top of each
|
||||
/// other.
|
||||
///
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
/// logger.info("Handling request")
|
||||
/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in
|
||||
/// logger.info("Authenticated") // sees both request.id and user.id
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` layered on
|
||||
/// top of the inherited base metadata. Async variant of ``withLogger(mergingMetadata:_:)``;
|
||||
/// see that function for full semantics.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The async closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result
|
||||
```
|
||||
|
||||
**Replace aspects of the current logger:**
|
||||
|
||||
```swift
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are **replaced** by
|
||||
/// the provided arguments. `nil` parameters leave the corresponding aspect unchanged.
|
||||
///
|
||||
/// Unlike ``withLogger(mergingMetadata:_:)``, which layers metadata on top of the
|
||||
/// inherited base, this overload **replaces** the base metadata when `metadata` is
|
||||
/// non-nil. Pass `metadata: [:]` to wipe the inherited metadata entirely.
|
||||
///
|
||||
/// With no arguments, this overload re-binds ``Logger/current`` unchanged — a convenient
|
||||
/// way to extract it into a local variable for repeated use inside the closure.
|
||||
///
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { _ in
|
||||
/// // Background job: start a scope with metadata unrelated to the request.
|
||||
/// withLogger(metadata: ["job.id": "\(job.id)"]) { logger in
|
||||
/// logger.info("running") // metadata: job.id only — request.id wiped
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When
|
||||
/// `nil`, the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for
|
||||
/// the scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to
|
||||
/// start a scope from a known state. When `nil`, the inherited base metadata is
|
||||
/// preserved.
|
||||
/// - operation: The closure to run with the modified logger bound. Receives the
|
||||
/// modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are replaced by
|
||||
/// the provided arguments. Async variant of
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)``; see that function for full semantics.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When
|
||||
/// `nil`, the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for
|
||||
/// the scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to
|
||||
/// start a scope from a known state. When `nil`, the inherited base metadata is
|
||||
/// preserved.
|
||||
/// - operation: The async closure to run with the modified logger bound. Receives
|
||||
/// the modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result
|
||||
```
|
||||
|
||||
Calling `withLogger { logger in ... }` with no arguments is the single-lookup idiom for
|
||||
extracting `Logger.current` into a local variable for repeated use inside the closure —
|
||||
analogous to `withSpan { span in ... }` in `swift-distributed-tracing`.
|
||||
|
||||
|
||||
#### Relationship to `MetadataProvider`
|
||||
|
||||
Metadata merged via `withLogger(mergingMetadata:)` is written into the handler's base
|
||||
metadata on the per-task logger copy. If a handler has a `MetadataProvider` attached — for
|
||||
example a bootstrapped OpenTelemetry provider that reads `trace.id` from `ServiceContext` —
|
||||
the provider still runs at log-emission time and follows the handler's conventional merge
|
||||
order (base < provider < per-statement).
|
||||
|
||||
This proposal does **not** add a `metadataProvider:` parameter to the modifying overload.
|
||||
Application code that wants to swap the provider for a scope should construct a new `Logger`
|
||||
and use the binding overload. Keeping the two concerns separate avoids shipping the
|
||||
replace-vs-compose question as part of the core API.
|
||||
|
||||
### API stability
|
||||
|
||||
**For existing `Logger` users:** no changes. The new API is purely additive.
|
||||
|
||||
**For existing `LogHandler` implementations:** no changes required. Task-local loggers use
|
||||
the same `LogHandler` interface; no new protocol requirements are added.
|
||||
|
||||
**Package platform minimums.** `Package.swift` intentionally does not gain a `platforms:`
|
||||
clause. Each new symbol carries `@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)`
|
||||
to match `@TaskLocal`'s runtime availability. Callers targeting older deployment versions
|
||||
keep working; they just can't call the task-local API.
|
||||
|
||||
**ABI and resilience.** The `withLogger` overloads are `@inlinable`: their bodies are thin
|
||||
glue — read `Logger.current`, copy-and-modify the logger, then bind it for the scope — so
|
||||
inlining them removes a cross-module call at each scope entry. The internal
|
||||
`withTaskLocalLogger` bridge over `TaskLocal.withValue` is `@usableFromInline` (not
|
||||
`@inlinable`), letting the inlinable bodies reach it without exposing the `@TaskLocal`
|
||||
storage. That storage, the bridge, and `Logger.current` all stay non-`@inlinable`, so the
|
||||
genuinely evolvable state — how the task-local is stored and how the unbound default is
|
||||
resolved — remains behind a resilient boundary and can change without breaking
|
||||
already-compiled clients. Only the small, settled control flow of the wrappers is committed
|
||||
to ABI.
|
||||
|
||||
**Source compatibility caveat.** The name `withLogger` is added at the top-level namespace.
|
||||
Codebases that previously defined their own free `withLogger` function may need to
|
||||
fully-qualify calls (`Logging.withLogger(...)`) or rename their own.
|
||||
|
||||
### Future directions
|
||||
|
||||
- **`Logger.withMetadata(merging:) -> Logger` and `Logger.withMetadata(replacing:) -> Logger`
|
||||
value-level instance methods.** Construct a derived `Logger` value (not a scope) with
|
||||
metadata layered onto or wholly replacing the receiver's metadata. The scope-level
|
||||
equivalents (`withLogger(mergingMetadata:)` and `withLogger(metadata:)`) ship in this
|
||||
proposal; the value-level forms are useful for per-statement metadata that should not
|
||||
propagate via the task-local — for example, a library that wants to stamp a key on its
|
||||
own log lines without pushing it onto `Logger.current` (avoiding leakage into downstream
|
||||
callees).
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Task-local metadata dictionary instead of task-local logger
|
||||
|
||||
Make only the metadata dictionary task-local, so ad-hoc `Logger(label:)` calls automatically
|
||||
merge it. Rejected because it changes default behavior for all existing logger creation
|
||||
(breaking semantic change) and overlaps with `swift-distributed-tracing`'s
|
||||
`ServiceContext`.
|
||||
|
||||
#### Static methods on `Logger` instead of free functions
|
||||
|
||||
`Logger.withCurrent(...)` instead of `withLogger(...)`. Rejected — inconsistent with
|
||||
`withSpan(...)` from `swift-distributed-tracing` and `withMetricsFactory(...)` from
|
||||
`swift-metrics`. Free functions follow the established ecosystem convention.
|
||||
|
||||
#### Use `ServiceContext` from swift-distributed-tracing instead of a new task-local
|
||||
|
||||
Store metadata in the existing `ServiceContext` — propagated by `swift-service-context`,
|
||||
the leaf package already designed as a shared propagation primitive — rather than
|
||||
introducing a second `@TaskLocal`. Rejected because the two propagation channels serve
|
||||
different use cases: `ServiceContext` carries *distributed* correlation (trace/span IDs,
|
||||
baggage) that flows across process boundaries, while `withLogger(mergingMetadata:)`
|
||||
accumulates *local* per-scope logger configuration (log level, handler, and application
|
||||
metadata like `request.id`) that is meaningful only within a single process. The
|
||||
task-local logger also carries more than metadata — it holds the `LogHandler`, log
|
||||
level, and label, none of which belong in a context intended for cross-process propagation.
|
||||
The existing `MetadataProvider` already bridges the two systems at log-emission time:
|
||||
handlers read trace/span IDs from `ServiceContext` without swift-log depending on it.
|
||||
|
||||
#### No closure parameter — require `Logger.current` inside the closure
|
||||
|
||||
`withLogger(logger) { ... }` without a parameter, reading `Logger.current` inside. Rejected
|
||||
because passing the logger avoids repeated task-local lookups, follows the `withSpan`
|
||||
convention, and makes it obvious at the call site which logger is in use.
|
||||
|
||||
#### Not propagating metadata across module boundaries by default
|
||||
|
||||
Expose a public `TaskLocal<Logger>` extension surface so that each module can declare
|
||||
its own scoped logger and stay structurally isolated from other modules — pushes on one
|
||||
module's task-local would be invisible to another's reads. Rejected for two reasons.
|
||||
|
||||
First, the public surface cost: `@TaskLocal`-declared task-locals require the `$logger`
|
||||
projection syntax for the scope methods (`MyApp.$logger.withMetadata(merging: …) { … }`),
|
||||
which is unfamiliar and easy to get wrong; alternatively, exposing `TaskLocal<Logger>`
|
||||
typed properties would leak a stdlib type into the swift-log surface that we'd rather
|
||||
keep internal. Hiding the task-local behind `Logger.current` and the `withLogger` free
|
||||
functions trades isolation for a cleaner API.
|
||||
|
||||
Second, the leak case is disciplinable. The only way library code propagates its own
|
||||
metadata downstream through `Logger.current` is by calling `withLogger(mergingMetadata:)`
|
||||
or `withLogger(metadata:)`. The documented contract is that those overloads are
|
||||
application-side APIs: libraries read `Logger.current` and use per-statement `metadata:`
|
||||
or a local copy for their own context; they do not push. Per-module isolation would make
|
||||
the leak impossible *by construction* even when discipline fails, but it would also
|
||||
fragment cross-cutting metadata propagation (`request.id` accumulated at the application
|
||||
layer would not appear on library log lines without an explicit bridge from one
|
||||
task-local to another) — which is the propagation we most want by default.
|
||||
|
||||
If structural isolation turns out to matter for specific use cases, the public
|
||||
`TaskLocal<Logger>` extension surface can be added as a non-breaking follow-up.
|
||||
|
||||
#### Use another third-party dependency management package
|
||||
|
||||
Swift packages ecosystem has packages for managing dependencies, one of those can
|
||||
be used to handle a task-local `Logger` instance. Rejected because if a library
|
||||
wants to benefit from a common logger without adding it to its API surface,
|
||||
it would have to depend on that extra package, effectively imposing that choice on
|
||||
the application. But the dependency mechanism is an application-level decision,
|
||||
an app may prefer a different approach, which leads to fragmentation or extra solutions
|
||||
to bridge them.
|
||||
|
||||
#### Let applications create their own task-local logger objects
|
||||
|
||||
Applications can declare their own task-local `Logger` instance and API explicitly,
|
||||
or via another dependency mechanism package. Rejected because it leaves library
|
||||
dependencies out of the picture and hurts discoverability and composability
|
||||
of the solution.
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
### Creating a metadata provider
|
||||
|
||||
- ``init(_:)-(()->Logger.Metadata)``
|
||||
- ``init(_:)``
|
||||
|
||||
### Invoking the provider
|
||||
|
||||
|
||||
@@ -9,3 +9,8 @@
|
||||
- ``array(_:)``
|
||||
- ``dictionary(_:)``
|
||||
|
||||
### Working with attributes
|
||||
|
||||
- ``attributed(_:attributes:)``
|
||||
- ``attributes``
|
||||
|
||||
@@ -10,6 +10,16 @@
|
||||
- ``init(label:factory:)-6iktu``
|
||||
- ``MetadataProvider``
|
||||
|
||||
### Task-local logger
|
||||
|
||||
- ``current``
|
||||
- ``withLogger(_:_:)-3dt06``
|
||||
- ``withLogger(_:_:)-70nli``
|
||||
- ``withLogger(mergingMetadata:_:)-2c7dy``
|
||||
- ``withLogger(mergingMetadata:_:)-3eduo``
|
||||
- ``withLogger(logLevel:handler:metadata:_:)-2pd9p``
|
||||
- ``withLogger(logLevel:handler:metadata:_:)-5nmw6``
|
||||
|
||||
### Sending trace log messages
|
||||
|
||||
- ``trace(_:metadata:file:function:line:)``
|
||||
|
||||
@@ -8,6 +8,8 @@
|
||||
- ``standardOutput(label:metadataProvider:)``
|
||||
- ``standardError(label:)``
|
||||
- ``standardError(label:metadataProvider:)``
|
||||
- ``init(label:stream:)``
|
||||
- ``init(label:stream:metadataProvider:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
|
||||
@@ -144,9 +144,23 @@ public struct MultiplexLogHandler: LogHandler {
|
||||
|
||||
/// Log a message using the log level and source that you provide.
|
||||
///
|
||||
/// Metadata from this handler's metadata provider overrides metadata from
|
||||
/// the underlying handlers and their providers. Explicit metadata in the
|
||||
/// log event takes precedence over this handler's provider.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - event: The log event containing the level, message, metadata, and source location.
|
||||
public func log(event: LogEvent) {
|
||||
var event = event
|
||||
if let provider = self._metadataProvider {
|
||||
var metadata = provider.get()
|
||||
if let explicit = event.metadata {
|
||||
metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
|
||||
}
|
||||
if !metadata.isEmpty {
|
||||
event.metadata = metadata
|
||||
}
|
||||
}
|
||||
for handler in self.handlers where handler.logLevel <= event.level {
|
||||
handler.log(event: event)
|
||||
}
|
||||
|
||||
@@ -38,8 +38,6 @@ import WASILibc
|
||||
/// 2. The handler's ``metadataProvider`` is invoked, overriding any existing keys.
|
||||
/// 3. The per-log-statement metadata is merged, overriding any previously set keys.
|
||||
public struct StreamLogHandler: LogHandler {
|
||||
internal typealias _SendableTextOutputStream = TextOutputStream & Sendable
|
||||
|
||||
/// Creates a stream log handler that directs its output to STDOUT.
|
||||
public static func standardOutput(label: String) -> StreamLogHandler {
|
||||
StreamLogHandler(
|
||||
@@ -68,7 +66,7 @@ public struct StreamLogHandler: LogHandler {
|
||||
StreamLogHandler(label: label, stream: StdioOutputStream.stderr, metadataProvider: metadataProvider)
|
||||
}
|
||||
|
||||
private let stream: any _SendableTextOutputStream
|
||||
private let stream: any TextOutputStream & Sendable
|
||||
private let label: String
|
||||
|
||||
/// Get the log level configured for this `Logger`.
|
||||
@@ -102,13 +100,24 @@ public struct StreamLogHandler: LogHandler {
|
||||
}
|
||||
}
|
||||
|
||||
// internal for testing only
|
||||
internal init(label: String, stream: any _SendableTextOutputStream) {
|
||||
/// Creates a ``StreamLogHandler`` that directs its output to the stream you provide,
|
||||
/// using the global metadata provider from ``LoggingSystem``.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - label: The label for this log handler.
|
||||
/// - stream: The stream to write log output to.
|
||||
public init(label: String, stream: any TextOutputStream & Sendable) {
|
||||
self.init(label: label, stream: stream, metadataProvider: LoggingSystem.metadataProvider)
|
||||
}
|
||||
|
||||
// internal for testing only
|
||||
internal init(label: String, stream: any _SendableTextOutputStream, metadataProvider: Logger.MetadataProvider?) {
|
||||
/// Creates a ``StreamLogHandler`` that directs its output to the stream you provide,
|
||||
/// using the metadata provider you provide.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - label: The label for this log handler.
|
||||
/// - stream: The stream to write log output to.
|
||||
/// - metadataProvider: The metadata provider to use, or `nil` for no provider.
|
||||
public init(label: String, stream: any TextOutputStream & Sendable, metadataProvider: Logger.MetadataProvider?) {
|
||||
self.label = label
|
||||
self.stream = stream
|
||||
self.metadataProvider = metadataProvider
|
||||
@@ -336,8 +345,13 @@ internal struct StdioOutputStream: TextOutputStream, @unchecked Sendable {
|
||||
)
|
||||
#elseif canImport(WASILibc)
|
||||
// no file locking on WASI
|
||||
#if compiler(>=6.5)
|
||||
let file = WASILibc.stderr
|
||||
#else
|
||||
let file = WASILibc.stderr!
|
||||
#endif
|
||||
return StdioOutputStream(
|
||||
file: WASILibc.stderr!,
|
||||
file: file,
|
||||
flushMode: .always,
|
||||
lock: nil,
|
||||
unlock: nil,
|
||||
@@ -408,8 +422,13 @@ internal struct StdioOutputStream: TextOutputStream, @unchecked Sendable {
|
||||
)
|
||||
#elseif canImport(WASILibc)
|
||||
// no file locking on WASI
|
||||
#if compiler(>=6.5)
|
||||
let file = WASILibc.stdout
|
||||
#else
|
||||
let file = WASILibc.stdout!
|
||||
#endif
|
||||
return StdioOutputStream(
|
||||
file: WASILibc.stdout!,
|
||||
file: file,
|
||||
flushMode: .always,
|
||||
lock: nil,
|
||||
unlock: nil,
|
||||
|
||||
+11
-11
@@ -61,7 +61,7 @@ package final class Lock {
|
||||
#elseif os(FreeBSD) || os(OpenBSD)
|
||||
fileprivate let mutex: UnsafeMutablePointer<pthread_mutex_t?> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
fileprivate let mutex: UnsafeMutablePointer<pthread_mutex_t> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#endif
|
||||
@@ -70,7 +70,7 @@ package final class Lock {
|
||||
package init() {
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
var attr = pthread_mutexattr_t(bitPattern: 0)
|
||||
#else
|
||||
@@ -100,7 +100,7 @@ package final class Lock {
|
||||
deinit {
|
||||
#if os(Windows)
|
||||
mutex.deallocate()
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_mutex_destroy(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
mutex.deallocate()
|
||||
@@ -114,7 +114,7 @@ package final class Lock {
|
||||
package func lock() {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_mutex_lock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
@@ -127,7 +127,7 @@ package final class Lock {
|
||||
package func unlock() {
|
||||
#if os(Windows)
|
||||
ReleaseSRWLockExclusive(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_mutex_unlock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
@@ -196,10 +196,10 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
#endif
|
||||
|
||||
/// Create a new lock.
|
||||
public init() {
|
||||
init() {
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.rwlock)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_init(self.rwlock, nil)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -208,7 +208,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
deinit {
|
||||
#if os(Windows)
|
||||
self.rwlock.deallocate()
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_destroy(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
self.rwlock.deallocate()
|
||||
@@ -223,7 +223,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockShared(self.rwlock)
|
||||
self.shared = true
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_rdlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -237,7 +237,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.rwlock)
|
||||
self.shared = false
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_wrlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -255,7 +255,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
} else {
|
||||
ReleaseSRWLockExclusive(self.rwlock)
|
||||
}
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_unlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
|
||||
@@ -280,6 +280,10 @@ extension LogHandler {
|
||||
}
|
||||
|
||||
/// A default implementation for the SwiftLog 1.0 log message handler.
|
||||
///
|
||||
/// Forwards to ``log(event:)`` directly. Forwarding to the source-carrying deprecated
|
||||
/// method closed a cycle with its own default, so a handler implementing only
|
||||
/// ``log(event:)`` overflowed the stack when called through this entry point.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logging.Logger.Level,
|
||||
@@ -290,13 +294,15 @@ extension LogHandler {
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: Logger.currentModule(filePath: file),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
event: LogEvent(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: Logger.currentModule(filePath: file),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -262,7 +262,9 @@ extension Logger.MetadataValue {
|
||||
///
|
||||
/// **Setting:** Replaces the value with `.stringConvertible(AttributedStringCarrier(...))`
|
||||
/// carrying the given attributes. For `.string` and `.stringConvertible` cases the string
|
||||
/// representation is preserved. For `.dictionary` and `.array` cases the setter is a no-op.
|
||||
/// representation is preserved. Setting attributes on a `.dictionary` or `.array` value is a
|
||||
/// programmer error: it triggers an assertion in debug builds and leaves the value unchanged in
|
||||
/// release builds. Set attributes on the leaf values instead.
|
||||
///
|
||||
/// Only handlers that inspect attributes pay the cost of the getter check.
|
||||
@inlinable
|
||||
|
||||
@@ -0,0 +1,325 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2026 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
// MARK: - withLogger() free functions for task-local logger
|
||||
|
||||
/// Runs `operation` with `logger` bound to the task-local context.
|
||||
///
|
||||
/// Code called within `operation` can read the logger via ``Logger/current`` without an
|
||||
/// explicit parameter. Binding a different logger with this overload **replaces** the
|
||||
/// current task-local logger; any metadata accumulated by an outer
|
||||
/// ``withLogger(mergingMetadata:_:)-2c7dy`` or
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)-2pd9p``
|
||||
/// scope is not carried over. Use the modifying overloads to layer or replace aspects
|
||||
/// of the current logger instead.
|
||||
///
|
||||
/// This overload is the application-bootstrap binding mechanism: pass a `Logger`
|
||||
/// constructed via ``Logger/init(label:)`` at your application entry point. Because
|
||||
/// ``Logger/init(label:)`` consults `LoggingSystem.factory`, the constructed `Logger`
|
||||
/// only carries a useful handler once ``LoggingSystem/bootstrap(_:)`` has been called.
|
||||
/// For mid-call-tree backend swaps that should work without bootstrap (tests, scoped
|
||||
/// routing), use ``withLogger(logLevel:handler:metadata:_:)-2pd9p``
|
||||
/// instead — it modifies
|
||||
/// the current logger's handler in place without constructing a new one.
|
||||
///
|
||||
/// ```swift
|
||||
/// let logger = Logger(label: "app")
|
||||
/// await withLogger(logger) { logger in
|
||||
/// logger.info("Application started")
|
||||
/// await handleRequests() // reads Logger.current
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The closure to run with `logger` bound. Receives `logger` as a
|
||||
/// parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result {
|
||||
do {
|
||||
return try Logger.withTaskLocalLogger(logger) {
|
||||
try operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with `logger` bound to the task-local context.
|
||||
///
|
||||
/// Code called within `operation` can read the logger via ``Logger/current`` without an
|
||||
/// explicit parameter. Binding a different logger with this overload **replaces** the
|
||||
/// current task-local logger; any metadata accumulated by an outer
|
||||
/// ``withLogger(mergingMetadata:_:)-3eduo`` or
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)-5nmw6``
|
||||
/// scope is not carried over. Use the modifying overloads to layer or replace aspects
|
||||
/// of the current logger instead.
|
||||
///
|
||||
/// This overload is the application-bootstrap binding mechanism: pass a `Logger`
|
||||
/// constructed via ``Logger/init(label:)`` at your application entry point. Because
|
||||
/// ``Logger/init(label:)`` consults `LoggingSystem.factory`, the constructed `Logger`
|
||||
/// only carries a useful handler once ``LoggingSystem/bootstrap(_:)`` has been called.
|
||||
/// For mid-call-tree backend swaps that should work without bootstrap (tests, scoped
|
||||
/// routing), use ``withLogger(logLevel:handler:metadata:_:)-5nmw6``
|
||||
/// instead — it modifies
|
||||
/// the current logger's handler in place without constructing a new one.
|
||||
///
|
||||
/// ```swift
|
||||
/// let logger = Logger(label: "app")
|
||||
/// await withLogger(logger) { logger in
|
||||
/// logger.info("Application started")
|
||||
/// await handleRequests() // reads Logger.current
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The async closure to run with `logger` bound. Receives `logger` as a
|
||||
/// parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result {
|
||||
do {
|
||||
return try await Logger.withTaskLocalLogger(logger) {
|
||||
try await operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` **layered on
|
||||
/// top of** the inherited base metadata. Keys present in `metadata` override existing
|
||||
/// keys with the same name. Other aspects (handler, log level, base metadata not in
|
||||
/// `metadata`) are preserved.
|
||||
///
|
||||
/// Use this overload at request boundaries and any point where context should
|
||||
/// accumulate. Nested ``withLogger(mergingMetadata:_:)-2c7dy`` scopes
|
||||
/// layer on top of each
|
||||
/// other.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
/// logger.info("Handling request")
|
||||
/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in
|
||||
/// logger.info("Authenticated") // sees both request.id and user.id
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
for (key, value) in metadata() {
|
||||
logger[metadataKey: key] = value
|
||||
}
|
||||
do {
|
||||
return try Logger.withTaskLocalLogger(logger) {
|
||||
try operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` **layered on
|
||||
/// top of** the inherited base metadata. Keys present in `metadata` override existing
|
||||
/// keys with the same name. Other aspects (handler, log level, base metadata not in
|
||||
/// `metadata`) are preserved.
|
||||
///
|
||||
/// Use this overload at request boundaries and any point where context should
|
||||
/// accumulate. Nested ``withLogger(mergingMetadata:_:)-3eduo`` scopes
|
||||
/// layer on top of each
|
||||
/// other.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
/// logger.info("Handling request")
|
||||
/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in
|
||||
/// logger.info("Authenticated") // sees both request.id and user.id
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The async closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
for (key, value) in metadata() {
|
||||
logger[metadataKey: key] = value
|
||||
}
|
||||
do {
|
||||
return try await Logger.withTaskLocalLogger(logger) {
|
||||
try await operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are **replaced** by
|
||||
/// the provided arguments. `nil` parameters leave the corresponding aspect unchanged.
|
||||
///
|
||||
/// Unlike ``withLogger(mergingMetadata:_:)-2c7dy``, which layers
|
||||
/// metadata on top of the
|
||||
/// inherited base, this overload **replaces** the base metadata when `metadata` is
|
||||
/// non-nil. Pass `metadata: [:]` to wipe the inherited metadata entirely for the scope.
|
||||
///
|
||||
/// With no arguments, this overload re-binds ``Logger/current`` unchanged — a convenient
|
||||
/// way to extract it into a local variable for repeated use inside the closure.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { _ in
|
||||
/// // Start a background job with metadata unrelated to the request that scheduled it.
|
||||
/// withLogger(metadata: ["job.id": "\(job.id)"]) { logger in
|
||||
/// logger.info("running") // metadata: job.id only — request.id wiped
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// When no `withLogger` scope has been set up, ``Logger/current`` (and therefore this
|
||||
/// function) returns the process-wide unbound default — a `Logger(label: "")` cached
|
||||
/// from the first time the task-local is touched. Bootstrap before reading
|
||||
/// ``Logger/current`` for predictable backend selection.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When `nil`,
|
||||
/// the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for the
|
||||
/// scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to start
|
||||
/// a scope from a known state. When `nil`, the inherited base metadata is preserved.
|
||||
/// - operation: The closure to run with the modified logger bound. Receives the
|
||||
/// modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
if let handler {
|
||||
logger.handler = handler
|
||||
}
|
||||
if let logLevel {
|
||||
logger.logLevel = logLevel
|
||||
}
|
||||
if let metadata = metadata() {
|
||||
logger.handler.metadata = metadata
|
||||
}
|
||||
do {
|
||||
return try Logger.withTaskLocalLogger(logger) {
|
||||
try operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are **replaced** by
|
||||
/// the provided arguments. `nil` parameters leave the corresponding aspect unchanged.
|
||||
///
|
||||
/// Unlike ``withLogger(mergingMetadata:_:)-3eduo``, which layers
|
||||
/// metadata on top of the
|
||||
/// inherited base, this overload **replaces** the base metadata when `metadata` is
|
||||
/// non-nil. Pass `metadata: [:]` to wipe the inherited metadata entirely for the scope.
|
||||
///
|
||||
/// With no arguments, this overload re-binds ``Logger/current`` unchanged — a convenient
|
||||
/// way to extract it into a local variable for repeated use inside the closure.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { _ in
|
||||
/// // Start a background job with metadata unrelated to the request that scheduled it.
|
||||
/// withLogger(metadata: ["job.id": "\(job.id)"]) { logger in
|
||||
/// logger.info("running") // metadata: job.id only — request.id wiped
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// When no `withLogger` scope has been set up, ``Logger/current`` (and therefore this
|
||||
/// function) returns the process-wide unbound default — a `Logger(label: "")` cached
|
||||
/// from the first time the task-local is touched. Bootstrap before reading
|
||||
/// ``Logger/current`` for predictable backend selection.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When `nil`,
|
||||
/// the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for the
|
||||
/// scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to start
|
||||
/// a scope from a known state. When `nil`, the inherited base metadata is preserved.
|
||||
/// - operation: The async closure to run with the modified logger bound. Receives the
|
||||
/// modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
if let handler {
|
||||
logger.handler = handler
|
||||
}
|
||||
if let logLevel {
|
||||
logger.logLevel = logLevel
|
||||
}
|
||||
if let metadata = metadata() {
|
||||
logger.handler.metadata = metadata
|
||||
}
|
||||
do {
|
||||
return try await Logger.withTaskLocalLogger(logger) {
|
||||
try await operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
@@ -34,7 +34,7 @@ public struct Logger {
|
||||
@usableFromInline
|
||||
var handler: any LogHandler
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(label: String, handler: any LogHandler) {
|
||||
self.label = label
|
||||
self.handler = handler
|
||||
@@ -57,15 +57,23 @@ public struct Logger {
|
||||
/// This computed property provides access to the `LogHandler`.
|
||||
@inlinable
|
||||
public var handler: any LogHandler {
|
||||
get {
|
||||
self._storage.handler
|
||||
_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.
|
||||
@@ -1414,14 +1422,29 @@ extension Logger.MetadataValue: CustomStringConvertible {
|
||||
/// A string representation of the metadata value.
|
||||
public var description: String {
|
||||
switch self {
|
||||
case .dictionary(let dict):
|
||||
return dict.mapValues { $0.description }.description
|
||||
case .array(let list):
|
||||
return list.map { $0.description }.description
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1454,6 +1477,71 @@ extension Logger.MetadataValue: ExpressibleByArrayLiteral {
|
||||
}
|
||||
}
|
||||
|
||||
// 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 {}
|
||||
|
||||
@@ -101,6 +101,12 @@ public enum LoggingSystem: Sendable {
|
||||
}
|
||||
}
|
||||
|
||||
/// `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
|
||||
@@ -151,7 +157,7 @@ public enum LoggingSystem: Sendable {
|
||||
/// and can only be updated once from the initial value given.
|
||||
private struct ReplaceOnceBox<BoxedType: Sendable> {
|
||||
private struct ReplaceOnce: Sendable {
|
||||
private var initialized = false
|
||||
private(set) var initialized = false
|
||||
private var _underlying: BoxedType
|
||||
private let violationErrorMessage: String
|
||||
|
||||
@@ -189,6 +195,10 @@ public enum LoggingSystem: Sendable {
|
||||
var underlying: BoxedType {
|
||||
self.storage.withReadLock { $0.underlying }
|
||||
}
|
||||
|
||||
var isInitialized: Bool {
|
||||
self.storage.withReadLock { $0.initialized }
|
||||
}
|
||||
}
|
||||
|
||||
private typealias FactoryBox = ReplaceOnceBox<
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2026 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct MultiplexProviderRegressionTests {
|
||||
@Test(arguments: [1, 2])
|
||||
func constructorProviderReachesEverySink(handlerCount: Int) {
|
||||
let sinks = (0..<handlerCount).map { _ in InMemoryLogHandler() }
|
||||
let handler = MultiplexLogHandler(sinks, metadataProvider: .init { ["trace-id": "123"] })
|
||||
let logger = Logger(label: "test", factory: { _ in handler })
|
||||
#expect(logger.metadataProvider?.get()["trace-id"] == "123")
|
||||
logger.info("hello")
|
||||
for sink in sinks {
|
||||
#expect(sink.entries.count == 1)
|
||||
#expect(sink.entries.first?.metadata["trace-id"] == "123")
|
||||
}
|
||||
}
|
||||
|
||||
@Test func constructorProviderLayersBetweenChildAndExplicitMetadata() {
|
||||
var sink = InMemoryLogHandler()
|
||||
sink.metadataProvider = .init { ["child": "kept", "shared": "child"] }
|
||||
let handler = MultiplexLogHandler(
|
||||
[sink],
|
||||
metadataProvider: .init {
|
||||
["outer": "kept", "shared": "outer"]
|
||||
}
|
||||
)
|
||||
let logger = Logger(label: "test", factory: { _ in handler })
|
||||
logger.info("provided")
|
||||
logger.info("explicit", metadata: ["shared": "explicit"])
|
||||
#expect(sink.entries.first?.metadata == ["child": "kept", "outer": "kept", "shared": "outer"])
|
||||
#expect(sink.entries.last?.metadata == ["child": "kept", "outer": "kept", "shared": "explicit"])
|
||||
}
|
||||
}
|
||||
@@ -66,6 +66,79 @@ struct CompatibilityTest {
|
||||
testLogging.history.assertExist(level: .error, message: "yes: error", source: "yes: error source")
|
||||
testLogging.history.assertExist(level: .critical, message: "yes: critical", source: "yes: critical source")
|
||||
}
|
||||
|
||||
/// A handler implementing only `log(event:)` must survive a caller on the SwiftLog 1.0
|
||||
/// entry point. Both deprecated defaults used to forward to each other.
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
@Test func swiftLog1CompatibilityMethodReachesAnEventOnlyHandler() {
|
||||
let handler = EventOnlyLogHandler()
|
||||
|
||||
handler.log(
|
||||
level: .warning,
|
||||
message: "compat",
|
||||
metadata: ["k": "v"],
|
||||
file: "/Sources/CompatModule/Caller.swift",
|
||||
function: #function,
|
||||
line: 42
|
||||
)
|
||||
|
||||
let events = handler.recorded
|
||||
#expect(events.count == 1)
|
||||
#expect(events.first?.level == .warning)
|
||||
#expect(events.first?.message == "compat")
|
||||
#expect(events.first?.metadata == ["k": "v"])
|
||||
#expect(events.first?.source == "CompatModule")
|
||||
#expect(events.first?.line == 42)
|
||||
}
|
||||
|
||||
/// The same entry point must still reach a handler implementing only the
|
||||
/// source-carrying deprecated method.
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
@Test func swiftLog1CompatibilityMethodReachesASourceOnlyHandler() {
|
||||
let testLogging = NewerButStillOldTestLogging()
|
||||
let handler = testLogging.make(label: "compat")
|
||||
|
||||
handler.log(
|
||||
level: .error,
|
||||
message: "compat",
|
||||
metadata: nil,
|
||||
file: "/Sources/CompatModule/Caller.swift",
|
||||
function: #function,
|
||||
line: 42
|
||||
)
|
||||
|
||||
testLogging.history.assertExist(level: .error, message: "compat", source: "CompatModule")
|
||||
}
|
||||
}
|
||||
|
||||
/// Implements `log(event:)` and nothing else.
|
||||
private struct EventOnlyLogHandler: LogHandler {
|
||||
private final class Store: @unchecked Sendable {
|
||||
private let lock = Lock()
|
||||
private var events: [LogEvent] = []
|
||||
func append(_ event: LogEvent) {
|
||||
self.lock.withLock { self.events.append(event) }
|
||||
}
|
||||
var all: [LogEvent] {
|
||||
self.lock.withLock { self.events }
|
||||
}
|
||||
}
|
||||
|
||||
private let store = Store()
|
||||
|
||||
var metadata: Logger.Metadata = [:]
|
||||
var logLevel: Logger.Level = .trace
|
||||
|
||||
subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[metadataKey] }
|
||||
set { self.metadata[metadataKey] = newValue }
|
||||
}
|
||||
|
||||
func log(event: LogEvent) {
|
||||
self.store.append(event)
|
||||
}
|
||||
|
||||
var recorded: [LogEvent] { self.store.all }
|
||||
}
|
||||
|
||||
private struct OldSchoolTestLogging {
|
||||
|
||||
@@ -12,6 +12,7 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Foundation
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
@@ -1143,6 +1143,23 @@ struct LoggingTest {
|
||||
#expect(.error == logger1.logLevel)
|
||||
#expect(.trace == logger2.logLevel)
|
||||
}
|
||||
|
||||
@Test func loggerMetadataWriteMutatesHandlerInPlace() {
|
||||
var logger1 = Logger(label: "foo", factory: { _ in CopyCountingLogHandler() })
|
||||
for i in 0..<10 {
|
||||
logger1[metadataKey: "key\(i)"] = "\(i)"
|
||||
}
|
||||
#expect(logger1.handlerCopies == 0)
|
||||
|
||||
// The first write to a copy copies the handler once, later writes reuse that copy.
|
||||
var logger2 = logger1
|
||||
for i in 0..<10 {
|
||||
logger2[metadataKey: "key\(i)"] = "changed"
|
||||
}
|
||||
#expect(logger2.handlerCopies == 1)
|
||||
#expect(logger1.handlerCopies == 0)
|
||||
#expect(logger1[metadataKey: "key0"] == "0")
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger {
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2026 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct MetadataValueTest {
|
||||
@Test
|
||||
func descriptionRendering() {
|
||||
#expect(Logger.MetadataValue.array([]).description == "[]")
|
||||
#expect(Logger.MetadataValue.array(["a", "b"]).description == ["a", "b"].description)
|
||||
|
||||
#expect(Logger.MetadataValue.dictionary([:]).description == "[:]")
|
||||
#expect(Logger.MetadataValue.dictionary(["k": "v"]).description == ["k": "v"].description)
|
||||
#expect(
|
||||
Logger.MetadataValue.dictionary(["outer": ["inner": "leaf"]]).description
|
||||
== "[\"outer\": [\"inner\": \"leaf\"]]"
|
||||
)
|
||||
}
|
||||
|
||||
@Test
|
||||
func equatableCompareson() {
|
||||
let lhs: Logger.MetadataValue = ["a": ["1", "2"]]
|
||||
let rhs: Logger.MetadataValue = ["a": ["1", "2"]]
|
||||
let different: Logger.MetadataValue = ["a": ["1", "3"]]
|
||||
|
||||
#expect(lhs == rhs)
|
||||
#expect(lhs != different)
|
||||
}
|
||||
|
||||
@Test
|
||||
func descriptionOfNestedArraysGrowsLinearlyNotExponentially() {
|
||||
var value: Logger.MetadataValue = .string("leaf")
|
||||
for _ in 0..<100 {
|
||||
value = .array([value])
|
||||
}
|
||||
// "leaf".debugDescription + each level adds a "[" and "]".
|
||||
#expect(value.description.count == 6 + 2 * 100)
|
||||
}
|
||||
|
||||
@Test
|
||||
func equatableComparesNestedArrays() {
|
||||
var lhs: Logger.MetadataValue = .string("leaf")
|
||||
var rhs: Logger.MetadataValue = .string("leaf")
|
||||
for _ in 0..<100 {
|
||||
lhs = .array([lhs])
|
||||
rhs = .array([rhs])
|
||||
}
|
||||
#expect(lhs == rhs)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,448 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2025 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
struct TaskLocalLoggerTest {
|
||||
// MARK: - Binding a logger
|
||||
|
||||
@Test func bindLogger() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { logger in
|
||||
logger.info("bound")
|
||||
}
|
||||
|
||||
logging.history.assertExist(level: .info, message: "bound")
|
||||
}
|
||||
|
||||
@Test func bindLoggerAsyncReturning() async {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
let result = await withLogger(logger) { logger -> Int in
|
||||
await Task.yield()
|
||||
logger.info("computing")
|
||||
return 42
|
||||
}
|
||||
|
||||
#expect(result == 42)
|
||||
logging.history.assertExist(level: .info, message: "computing")
|
||||
}
|
||||
|
||||
/// The bind overload replaces the task-local logger; accumulated metadata from an
|
||||
/// enclosing `withLogger(mergingMetadata:)` scope is intentionally not carried over.
|
||||
@Test func bindReplacesAccumulatedMetadata() {
|
||||
let logging1 = TestLogging()
|
||||
let logging2 = TestLogging()
|
||||
let root = Logger(label: "root", factory: { logging1.make(label: $0) })
|
||||
let other = Logger(label: "other", factory: { logging2.make(label: $0) })
|
||||
|
||||
withLogger(root) { _ in
|
||||
withLogger(mergingMetadata: ["request.id": "r1"]) { _ in
|
||||
withLogger(other) { inner in
|
||||
inner.info("no request.id")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let entry = logging2.history.entries.first { $0.message == "no request.id" }
|
||||
#expect(entry?.metadata?["request.id"] == nil)
|
||||
}
|
||||
|
||||
// MARK: - Modifying the current logger
|
||||
|
||||
@Test func mergeMetadata() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: ["key": "value"]) { logger in
|
||||
logger.info("merged")
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertExist(level: .info, message: "merged", metadata: ["key": "value"])
|
||||
}
|
||||
|
||||
@Test func mergeMetadataCopiesHandlerOnce() {
|
||||
let logger = Logger(label: "test", factory: { _ in CopyCountingLogHandler() })
|
||||
let metadata: Logger.Metadata = ["a": "1", "b": "2", "c": "3", "d": "4", "e": "5"]
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: metadata) { inner in
|
||||
#expect(inner.handler.metadata == metadata)
|
||||
#expect(inner.handlerCopies == 1)
|
||||
}
|
||||
#expect(Logger.current.handler.metadata.isEmpty)
|
||||
#expect(Logger.current.handlerCopies == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@Test func overrideLogLevel() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(logLevel: .warning) { logger in
|
||||
logger.debug("suppressed")
|
||||
logger.warning("emitted")
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertNotExist(level: .debug, message: "suppressed")
|
||||
logging.history.assertExist(level: .warning, message: "emitted")
|
||||
}
|
||||
|
||||
@Test func nestedMetadataAccumulates() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: ["level1": "first"]) { _ in
|
||||
withLogger(mergingMetadata: ["level2": "second"]) { logger in
|
||||
logger.info("inner")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "inner",
|
||||
metadata: ["level1": "first", "level2": "second"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func innerMetadataOverridesOuter() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: ["key": "outer"]) { _ in
|
||||
withLogger(mergingMetadata: ["key": "inner"]) { logger in
|
||||
logger.info("test")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertExist(level: .info, message: "test", metadata: ["key": "inner"])
|
||||
}
|
||||
|
||||
/// The modifying `withLogger(metadata:)` overload replaces the inherited metadata
|
||||
/// rather than layering — passing `[:]` wipes; passing a fresh dict starts the scope
|
||||
/// from a known state.
|
||||
@Test func metadataReplacesInherited() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: ["request.id": "r1", "user.id": "u1"]) { _ in
|
||||
withLogger(metadata: ["job.id": "j1"]) { scoped in
|
||||
scoped.info("background")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let entry = logging.history.entries.first { $0.message == "background" }
|
||||
#expect(entry?.metadata?["job.id"] == "j1")
|
||||
#expect(entry?.metadata?["request.id"] == nil)
|
||||
#expect(entry?.metadata?["user.id"] == nil)
|
||||
}
|
||||
|
||||
@Test func metadataEmptyDictWipesInherited() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: ["request.id": "r1"]) { _ in
|
||||
withLogger(metadata: [:]) { scoped in
|
||||
scoped.info("wiped")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let entry = logging.history.entries.first { $0.message == "wiped" }
|
||||
#expect(entry?.metadata?.isEmpty ?? true)
|
||||
}
|
||||
|
||||
/// `withLogger(handler:)` routes logs to a different handler for the scope — the
|
||||
/// canonical use is swapping in an in-memory handler to capture logs for assertions
|
||||
/// in a test.
|
||||
@Test func handlerSwapsForScope() {
|
||||
let outer = TestLogging()
|
||||
let inner = TestLogging()
|
||||
let appLogger = Logger(label: "app", factory: { outer.make(label: $0) })
|
||||
|
||||
withLogger(appLogger) { _ in
|
||||
for _ in outer.history.entries {} // touch outer so we can see the drift
|
||||
withLogger(handler: inner.make(label: "captured"), metadata: ["case": "test"]) { scoped in
|
||||
scoped.info("emitted under inner handler")
|
||||
}
|
||||
appLogger.info("back under outer")
|
||||
}
|
||||
|
||||
inner.history.assertExist(
|
||||
level: .info,
|
||||
message: "emitted under inner handler",
|
||||
metadata: ["case": "test"]
|
||||
)
|
||||
inner.history.assertNotExist(level: .info, message: "back under outer")
|
||||
outer.history.assertExist(level: .info, message: "back under outer")
|
||||
outer.history.assertNotExist(level: .info, message: "emitted under inner handler")
|
||||
}
|
||||
|
||||
@Test(arguments: [Logger.Level.debug, .warning])
|
||||
func handlerSwapRespectsExplicitLogLevel(level: Logger.Level) {
|
||||
let outer = TestLogging()
|
||||
let inner = TestLogging()
|
||||
var appLogger = Logger(label: "app", factory: { outer.make(label: $0) })
|
||||
appLogger.logLevel = .critical
|
||||
var replacement = inner.make(label: "captured")
|
||||
replacement.logLevel = .info
|
||||
let suppressedLevel: Logger.Level = level == .debug ? .trace : .info
|
||||
|
||||
withLogger(appLogger) { _ in
|
||||
withLogger(logLevel: level, handler: replacement) { scoped in
|
||||
#expect(scoped.logLevel == level)
|
||||
#expect(Logger.current.logLevel == level)
|
||||
scoped.log(level: level, "emitted")
|
||||
Logger.current.log(level: suppressedLevel, "suppressed")
|
||||
}
|
||||
#expect(Logger.current.logLevel == .critical)
|
||||
}
|
||||
|
||||
#expect(replacement.logLevel == .info)
|
||||
inner.history.assertExist(level: level, message: "emitted")
|
||||
inner.history.assertNotExist(level: suppressedLevel, message: "suppressed")
|
||||
outer.history.assertNotExist(level: level, message: "emitted")
|
||||
}
|
||||
|
||||
@Test(arguments: [Logger.Level.debug, .warning])
|
||||
func asyncHandlerSwapRespectsExplicitLogLevel(level: Logger.Level) async {
|
||||
let outer = TestLogging()
|
||||
let inner = TestLogging()
|
||||
var appLogger = Logger(label: "app", factory: { outer.make(label: $0) })
|
||||
appLogger.logLevel = .critical
|
||||
var replacement = inner.make(label: "captured")
|
||||
replacement.logLevel = .info
|
||||
let suppressedLevel: Logger.Level = level == .debug ? .trace : .info
|
||||
|
||||
await withLogger(appLogger) { _ in
|
||||
await withLogger(logLevel: level, handler: replacement) { scoped in
|
||||
await Task.yield()
|
||||
#expect(scoped.logLevel == level)
|
||||
#expect(Logger.current.logLevel == level)
|
||||
scoped.log(level: level, "emitted")
|
||||
Logger.current.log(level: suppressedLevel, "suppressed")
|
||||
}
|
||||
#expect(Logger.current.logLevel == .critical)
|
||||
}
|
||||
|
||||
#expect(replacement.logLevel == .info)
|
||||
inner.history.assertExist(level: level, message: "emitted")
|
||||
inner.history.assertNotExist(level: suppressedLevel, message: "suppressed")
|
||||
outer.history.assertNotExist(level: level, message: "emitted")
|
||||
}
|
||||
|
||||
@Test func siblingScopesAreIsolated() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: ["a": "1"]) { logger in
|
||||
logger.info("first")
|
||||
}
|
||||
withLogger(mergingMetadata: ["b": "2"]) { logger in
|
||||
logger.info("second")
|
||||
}
|
||||
}
|
||||
|
||||
let second = logging.history.entries.first { $0.message == "second" }
|
||||
#expect(second?.metadata?["a"] == nil)
|
||||
#expect(second?.metadata?["b"] == "2")
|
||||
}
|
||||
|
||||
// MARK: - Async propagation and task isolation
|
||||
|
||||
@Test func contextPreservedAcrossAwait() async throws {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
await withLogger(logger) { _ in
|
||||
await withLogger(mergingMetadata: ["request": "123"]) { logger in
|
||||
logger.info("before await")
|
||||
await Task.yield()
|
||||
logger.info("after await")
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertExist(level: .info, message: "before await", metadata: ["request": "123"])
|
||||
logging.history.assertExist(level: .info, message: "after await", metadata: ["request": "123"])
|
||||
}
|
||||
|
||||
@Test func childTaskInheritsContextDetachedDoesNot() async {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
await withLogger(logger) { _ in
|
||||
await withLogger(mergingMetadata: ["parent": "value"]) { _ in
|
||||
await Task {
|
||||
Logger.current.info("child")
|
||||
}.value
|
||||
await Task.detached {
|
||||
Logger.current.info("detached")
|
||||
}.value
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertExist(level: .info, message: "child", metadata: ["parent": "value"])
|
||||
// Detached task starts without a task-local logger and falls back to a freshly
|
||||
// constructed `Logger(label: "")`, which doesn't reach our per-test TestLogging.
|
||||
logging.history.assertNotExist(level: .info, message: "detached")
|
||||
}
|
||||
|
||||
@Test func concurrentTasksHaveIndependentContext() async {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
await withLogger(logger) { _ in
|
||||
await withLogger(mergingMetadata: ["context": "parent"]) { _ in
|
||||
await withTaskGroup(of: Void.self) { group in
|
||||
group.addTask {
|
||||
withLogger(mergingMetadata: ["task": "1"]) { logger in
|
||||
logger.info("task 1")
|
||||
}
|
||||
}
|
||||
group.addTask {
|
||||
withLogger(mergingMetadata: ["task": "2"]) { logger in
|
||||
logger.info("task 2")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "task 1",
|
||||
metadata: ["task": "1", "context": "parent"]
|
||||
)
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "task 2",
|
||||
metadata: ["task": "2", "context": "parent"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func asyncLetInheritsContext() async {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
func observedScope() async -> String? {
|
||||
Logger.current.handler.metadata["scope"]?.description
|
||||
}
|
||||
|
||||
await withLogger(logger) { _ in
|
||||
await withLogger(mergingMetadata: ["scope": "parent"]) { _ in
|
||||
async let inherited = observedScope()
|
||||
let observed = await inherited
|
||||
#expect(observed == "parent")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Error propagation
|
||||
|
||||
@Test func bindPropagatesThrow() {
|
||||
struct TestError: Error {}
|
||||
#expect(throws: TestError.self) {
|
||||
try withLogger(Logger(label: "t")) { _ in
|
||||
throw TestError()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@Test func modifyAsyncPropagatesThrow() async {
|
||||
struct TestError: Error {}
|
||||
#expect(throws: TestError.self) {
|
||||
try withLogger(mergingMetadata: ["k": "v"]) { _ in
|
||||
throw TestError()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Fallback behavior
|
||||
|
||||
@Test func fallbackUsesEmptyLabel() {
|
||||
// Without an active `withLogger` scope, `Logger.current` returns the process-wide
|
||||
// unbound default — a `Logger(label: "")` cached from the first time the
|
||||
// task-local is touched. The empty label is the diagnostic signal that no
|
||||
// `withLogger` scope was set up before the read.
|
||||
withLogger(mergingMetadata: ["key": "value"]) { logger in
|
||||
#expect(logger.label == "")
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Real-world patterns
|
||||
|
||||
@Test func libraryReadsCurrentWithoutLoggerParameter() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
struct DatabaseClient {
|
||||
func query(_ sql: String) {
|
||||
Logger.current.debug("query", metadata: ["sql": "\(sql)"])
|
||||
}
|
||||
}
|
||||
|
||||
withLogger(logger) { _ in
|
||||
withLogger(mergingMetadata: ["request.id": "123"]) { _ in
|
||||
DatabaseClient().query("SELECT 1")
|
||||
}
|
||||
}
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .debug,
|
||||
message: "query",
|
||||
metadata: ["request.id": "123", "sql": "SELECT 1"]
|
||||
)
|
||||
}
|
||||
|
||||
// MARK: - Stress
|
||||
|
||||
@Test func deeplyNestedScopes() {
|
||||
let logging = TestLogging()
|
||||
let logger = Logger(label: "test", factory: { logging.make(label: $0) })
|
||||
|
||||
func nest(depth: Int) {
|
||||
if depth == 0 {
|
||||
Logger.current.info("bottom")
|
||||
return
|
||||
}
|
||||
withLogger(mergingMetadata: ["d-\(depth)": "\(depth)"]) { _ in
|
||||
nest(depth: depth - 1)
|
||||
}
|
||||
}
|
||||
|
||||
withLogger(logger) { _ in
|
||||
nest(depth: 20)
|
||||
}
|
||||
|
||||
let entry = logging.history.entries.first { $0.message == "bottom" }
|
||||
#expect(entry?.metadata?.count == 20)
|
||||
}
|
||||
}
|
||||
@@ -485,9 +485,64 @@ internal struct TestLibrary: Sendable {
|
||||
}
|
||||
}
|
||||
|
||||
/// A log handler that keeps its metadata in a copy-on-write box and counts how often the box was copied.
|
||||
internal struct CopyCountingLogHandler: LogHandler {
|
||||
final class Box {
|
||||
var metadata: Logger.Metadata = [:]
|
||||
var copies = 0
|
||||
}
|
||||
|
||||
private var box = Box()
|
||||
|
||||
var logLevel: Logger.Level = .info
|
||||
|
||||
var copies: Int {
|
||||
self.box.copies
|
||||
}
|
||||
|
||||
var metadata: Logger.Metadata {
|
||||
get {
|
||||
self.box.metadata
|
||||
}
|
||||
set {
|
||||
self.makeUnique()
|
||||
self.box.metadata = newValue
|
||||
}
|
||||
}
|
||||
|
||||
subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self.box.metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
self.makeUnique()
|
||||
self.box.metadata[metadataKey] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
func log(event: LogEvent) {}
|
||||
|
||||
private mutating func makeUnique() {
|
||||
if !isKnownUniquelyReferenced(&self.box) {
|
||||
let copy = Box()
|
||||
copy.metadata = self.box.metadata
|
||||
copy.copies = self.box.copies + 1
|
||||
self.box = copy
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger {
|
||||
/// How often the `CopyCountingLogHandler` of this logger copied its box.
|
||||
var handlerCopies: Int? {
|
||||
(self.handler as? CopyCountingLogHandler)?.copies
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Sendable
|
||||
|
||||
extension TestLogHandler: @unchecked Sendable {}
|
||||
extension CopyCountingLogHandler.Box: @unchecked Sendable {}
|
||||
extension Recorder: @unchecked Sendable {}
|
||||
extension Config: @unchecked Sendable {}
|
||||
extension MDC: @unchecked Sendable {}
|
||||
@@ -0,0 +1,22 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 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
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
set(SwiftLog_EXPORTS_FILE ${CMAKE_CURRENT_BINARY_DIR}/SwiftLogExports.cmake)
|
||||
|
||||
configure_file(SwiftLogConfig.cmake.in
|
||||
${CMAKE_CURRENT_BINARY_DIR}/SwiftLogConfig.cmake)
|
||||
|
||||
get_property(SwiftLog_EXPORTS GLOBAL PROPERTY SwiftLog_EXPORTS)
|
||||
export(TARGETS ${SwiftLog_EXPORTS}
|
||||
FILE ${SwiftLog_EXPORTS_FILE})
|
||||
@@ -0,0 +1,17 @@
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) 2018-2026 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
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
if(NOT TARGET Logging)
|
||||
include(@SwiftLog_EXPORTS_FILE@)
|
||||
endif()
|
||||
@@ -0,0 +1,80 @@
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) 2018-2026 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
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
# Returns the os name in a variable
|
||||
#
|
||||
# Usage:
|
||||
# get_swift_host_os(result_var_name)
|
||||
#
|
||||
#
|
||||
# Sets ${result_var_name} with the converted OS name derived from
|
||||
# CMAKE_SYSTEM_NAME.
|
||||
function(get_swift_host_os result_var_name)
|
||||
if(CMAKE_SYSTEM_NAME STREQUAL Darwin)
|
||||
set(${result_var_name} macosx PARENT_SCOPE)
|
||||
else()
|
||||
string(TOLOWER ${CMAKE_SYSTEM_NAME} cmake_system_name_lc)
|
||||
set(${result_var_name} ${cmake_system_name_lc} PARENT_SCOPE)
|
||||
endif()
|
||||
endfunction()
|
||||
|
||||
if(NOT Swift_MODULE_TRIPLE)
|
||||
# Attempt to get the module triple from the Swift compiler.
|
||||
set(module_triple_command "${CMAKE_Swift_COMPILER}" -print-target-info)
|
||||
if(CMAKE_Swift_COMPILER_TARGET)
|
||||
list(APPEND module_triple_command -target ${CMAKE_Swift_COMPILER_TARGET})
|
||||
endif()
|
||||
execute_process(COMMAND ${module_triple_command}
|
||||
OUTPUT_VARIABLE target_info_json)
|
||||
string(JSON module_triple GET "${target_info_json}" "target" "moduleTriple")
|
||||
|
||||
# Exit now if we failed to infer the triple.
|
||||
if(NOT module_triple)
|
||||
message(FATAL_ERROR
|
||||
"Failed to get module triple from Swift compiler. "
|
||||
"Compiler output: ${target_info_json}")
|
||||
endif()
|
||||
|
||||
# Cache the module triple for future use.
|
||||
set(Swift_MODULE_TRIPLE "${module_triple}" CACHE STRING "swift module triple used for installed swiftmodule and swiftinterface files")
|
||||
mark_as_advanced(Swift_MODULE_TRIPLE)
|
||||
endif()
|
||||
|
||||
function(_install_target module)
|
||||
get_swift_host_os(swift_os)
|
||||
get_target_property(type ${module} TYPE)
|
||||
|
||||
if(type STREQUAL STATIC_LIBRARY)
|
||||
set(swift swift_static)
|
||||
else()
|
||||
set(swift swift)
|
||||
endif()
|
||||
|
||||
install(TARGETS ${module})
|
||||
if(type STREQUAL EXECUTABLE)
|
||||
return()
|
||||
endif()
|
||||
|
||||
get_target_property(module_name ${module} Swift_MODULE_NAME)
|
||||
if(NOT module_name)
|
||||
set(module_name ${module})
|
||||
endif()
|
||||
|
||||
install(FILES $<TARGET_PROPERTY:${module},Swift_MODULE_DIRECTORY>/${module_name}.swiftdoc
|
||||
DESTINATION ${CMAKE_INSTALL_LIBDIR}/${swift}/${swift_os}/${module_name}.swiftmodule
|
||||
RENAME ${Swift_MODULE_TRIPLE}.swiftdoc)
|
||||
install(FILES $<TARGET_PROPERTY:${module},Swift_MODULE_DIRECTORY>/${module_name}.swiftmodule
|
||||
DESTINATION ${CMAKE_INSTALL_LIBDIR}/${swift}/${swift_os}/${module_name}.swiftmodule
|
||||
RENAME ${Swift_MODULE_TRIPLE}.swiftmodule)
|
||||
endfunction()
|
||||
Reference in new issue
Block a user