mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
92448c359f | ||
|
|
2aed77ae5e | ||
|
|
7dc6101ae4 | ||
|
|
a012e0ad8a | ||
|
|
1069d31898 | ||
|
|
3061a62b6d | ||
|
|
184c73762f | ||
|
|
eca81998f5 | ||
|
|
ac3646e5e0 | ||
|
|
5c348a629c | ||
|
|
deae26e91a | ||
|
|
1fe83fbfe9 | ||
|
|
41592e45e1 | ||
|
|
83b6d96b19 | ||
|
|
25598b609a | ||
|
|
8ba97a9cf5 | ||
|
|
5073617dac | ||
|
|
6f3fbace66 | ||
|
|
41f6c72707 | ||
|
|
bffceaf778 | ||
|
|
6558438e46 | ||
|
|
7c04f86fba | ||
|
|
8c0f217f01 | ||
|
|
f4f84c9f26 | ||
|
|
1f38a59922 | ||
|
|
39e14910f6 | ||
|
|
63ee499927 | ||
|
|
c9ceb519e7 | ||
|
|
154acdf7d4 | ||
|
|
b93451412b | ||
|
|
c5f42781c4 | ||
|
|
4f1022c5cd | ||
|
|
f22537f94d | ||
|
|
185a56a488 | ||
|
|
bbd81b6725 | ||
|
|
8fb4e7147d | ||
|
|
d5dbc04d53 | ||
|
|
47ef0ec6a4 | ||
|
|
7d6d55f9ed | ||
|
|
8f634e4e68 | ||
|
|
2778fd4e5a | ||
|
|
0d9c9ae808 | ||
|
|
a92ccc626c | ||
|
|
7ee16e4656 | ||
|
|
1ccd2c5a27 | ||
|
|
477fab4170 | ||
|
|
bc386b95f2 | ||
|
|
6856e42a3f | ||
|
|
cdaa5ac879 | ||
|
|
b1fa4ef41f | ||
|
|
63eaca6f4d | ||
|
|
f3a82f1119 | ||
|
|
6b380c9f4b | ||
|
|
ca538143e2 | ||
|
|
3612813963 | ||
|
|
95a70b954c | ||
|
|
dea0abb603 | ||
|
|
4121d24dbd | ||
|
|
a90a3d1c37 | ||
|
|
2a4139ef2a | ||
|
|
bd44c73045 | ||
|
|
45b82c6e24 | ||
|
|
1be2c17b80 | ||
|
|
21d132f1ca |
No files matched your search
@@ -0,0 +1,8 @@
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "daily"
|
||||
labels:
|
||||
- "semver/none"
|
||||
@@ -0,0 +1,12 @@
|
||||
name: Auto Release
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: read
|
||||
|
||||
jobs:
|
||||
auto-release:
|
||||
uses: apple/swift-temporal-sdk/.github/workflows/auto-release.yml@main
|
||||
@@ -1,5 +1,8 @@
|
||||
name: Main
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
@@ -11,27 +14,35 @@ jobs:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
linux_5_9_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_5_10_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_1_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_0_enabled: true
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
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_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"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
macos_swift_6_3_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
static-sdk:
|
||||
name: Static SDK
|
||||
static-linux:
|
||||
name: Static Linux Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
|
||||
|
||||
@@ -40,4 +51,31 @@ jobs:
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
runner_pool: nightly
|
||||
build_scheme: swift-log
|
||||
build_scheme: swift-log-Package
|
||||
debug_output_enabled: true
|
||||
macos_xcode_test_enabled: false
|
||||
ios_xcode_test_enabled: false
|
||||
watchos_xcode_test_enabled: false
|
||||
tvos_xcode_test_enabled: false
|
||||
visionos_xcode_test_enabled: false
|
||||
|
||||
wasm:
|
||||
name: Wasm Swift SDK
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
with:
|
||||
nightly_next_enabled: false
|
||||
|
||||
android:
|
||||
name: Android Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/android_swift_sdk.yml@main
|
||||
|
||||
release-builds:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
@@ -1,5 +1,8 @@
|
||||
name: PR
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, reopened, synchronize]
|
||||
@@ -7,7 +10,7 @@ on:
|
||||
jobs:
|
||||
soundness:
|
||||
name: Soundness
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.11
|
||||
with:
|
||||
license_header_check_project_name: "Swift Logging API"
|
||||
|
||||
@@ -15,27 +18,36 @@ jobs:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
linux_5_9_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_5_10_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_1_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_0_enabled: true
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
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_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"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
macos_runner_pool: general
|
||||
macos_swift_6_3_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
static-sdk:
|
||||
name: Static SDK
|
||||
static-linux:
|
||||
name: Static Linux Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
|
||||
|
||||
@@ -44,4 +56,26 @@ jobs:
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
runner_pool: general
|
||||
build_scheme: swift-log
|
||||
build_scheme: swift-log-Package
|
||||
swift_test_enabled: true
|
||||
|
||||
android:
|
||||
name: Android Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/android_swift_sdk.yml@main
|
||||
|
||||
release-builds:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
|
||||
wasm:
|
||||
name: Wasm Swift SDK
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
with:
|
||||
nightly_next_enabled: false
|
||||
@@ -1,5 +1,8 @@
|
||||
name: PR label
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [labeled, unlabeled, opened, reopened, synchronize]
|
||||
@@ -11,7 +14,7 @@ jobs:
|
||||
timeout-minutes: 1
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Check for Semantic Version label
|
||||
|
||||
+2
-2
@@ -5,7 +5,6 @@
|
||||
.gitattributes
|
||||
.git-blame-ignore-revs
|
||||
.mailfilter
|
||||
.mailmap
|
||||
.spi.yml
|
||||
.swift-format
|
||||
.editorconfig
|
||||
@@ -19,6 +18,8 @@ Package.swift
|
||||
**/Package.swift
|
||||
Package@-*.swift
|
||||
**/Package@-*.swift
|
||||
Package@swift-*.swift
|
||||
**/Package@swift-*.swift
|
||||
Package.resolved
|
||||
**/Package.resolved
|
||||
Makefile
|
||||
@@ -32,7 +33,6 @@ Makefile
|
||||
Dockerfile
|
||||
**/Dockerfile
|
||||
Snippets/*
|
||||
dev/git.commit.template
|
||||
dev/update-benchmark-thresholds
|
||||
*.crt
|
||||
**/*.crt
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
Tomer Doron <tomer@apple.com> <tomer.doron@gmail.com>
|
||||
Tomer Doron <tomer@apple.com> tomer doron <tomer@apple.com>
|
||||
Tomer Doron <tomer@apple.com> tomer doron <tomerd@apple.com>
|
||||
Johannes Weiss <johannesweiss@apple.com> <johannes@jweiss.io>
|
||||
Max Moiseev <moiseev@apple.com> <moiseev@users.noreply.github.com>
|
||||
Konrad `ktoso` Malawski <ktoso@apple.com> <konrad.malawski@project13.pl>
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
@@ -0,0 +1,35 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Benchmark
|
||||
import BenchmarksFactory
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public let benchmarks: @Sendable () -> Void = {
|
||||
makeBenchmark(loggerLevel: .critical, logLevel: .critical) { logger in
|
||||
logger.critical("hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .critical, logLevel: .critical, "_generic") { logger in
|
||||
logger.log(level: .critical, "hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .critical, logLevel: .critical, "_metadata_set") { logger in
|
||||
var logger = logger
|
||||
logger[metadataKey: "user-id"] = "42"
|
||||
}
|
||||
makeBenchmark(loggerLevel: .critical, logLevel: .critical, "_logLevel_set") { logger in
|
||||
var logger = logger
|
||||
logger.logLevel = .info
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
// swift-tools-version: 6.2
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "MaxLogLevelNone",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
products: [
|
||||
.executable(name: "MaxLogLevelNone", targets: ["MaxLogLevelNone"])
|
||||
],
|
||||
dependencies: [
|
||||
// swift-log
|
||||
.package(
|
||||
path: "../../",
|
||||
traits: ["MaxLogLevelNone"]
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "MaxLogLevelNone",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/MaxLogLevelNoneBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 970,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 970,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5851,
|
||||
"objectAllocCount" : 2
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 7055,
|
||||
"objectAllocCount" : 3
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Benchmark
|
||||
import BenchmarksFactory
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public let benchmarks: @Sendable () -> Void = {
|
||||
makeBenchmark(loggerLevel: .notice, logLevel: .notice) { logger in
|
||||
logger.notice("hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .notice, logLevel: .notice, "_generic") { logger in
|
||||
logger.log(level: .notice, "hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .warning, logLevel: .warning) { logger in
|
||||
logger.warning("hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .warning, logLevel: .warning, "_generic") { logger in
|
||||
logger.log(level: .warning, "hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .notice, logLevel: .notice, "_attributed_generic") { logger in
|
||||
logger.log(
|
||||
level: .notice,
|
||||
"hello, benchmarking world",
|
||||
metadata: [
|
||||
"public-key": "\("public-value", sensitivity: .public)",
|
||||
"private-key": "\("private-value", sensitivity: .sensitive)",
|
||||
]
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
// swift-tools-version: 6.2
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "MaxLogLevelWarning",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
products: [
|
||||
.executable(name: "MaxLogLevelWarning", targets: ["MaxLogLevelWarning"])
|
||||
],
|
||||
dependencies: [
|
||||
// swift-log
|
||||
.package(
|
||||
path: "../../",
|
||||
traits: ["MaxLogLevelWarning"]
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "MaxLogLevelWarning",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/MaxLogLevelWarningBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 662,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 662,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 658,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1892,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1892,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
@@ -0,0 +1,63 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Benchmark
|
||||
import BenchmarksFactory
|
||||
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")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_1_attribute") { logger in
|
||||
logger.log(
|
||||
level: .error,
|
||||
"hello, benchmarking world",
|
||||
metadata: [
|
||||
"public-key": "\("public-value", sensitivity: .public)"
|
||||
]
|
||||
)
|
||||
}
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_1_attribute") { logger in
|
||||
logger.log(
|
||||
level: .debug,
|
||||
"hello, benchmarking world",
|
||||
metadata: [
|
||||
"public-key": "\("public-value", sensitivity: .public)"
|
||||
]
|
||||
)
|
||||
}
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_2_attributes") { logger in
|
||||
logger.log(
|
||||
level: .error,
|
||||
"hello, benchmarking world",
|
||||
metadata: [
|
||||
"public-key": "\("public-value", attributes: [BenchmarkSensitivity.public, BenchmarkColor.red])"
|
||||
]
|
||||
)
|
||||
}
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_2_attributes") { logger in
|
||||
logger.log(
|
||||
level: .debug,
|
||||
"hello, benchmarking world",
|
||||
metadata: [
|
||||
"public-key": "\("public-value", attributes: [BenchmarkSensitivity.public, BenchmarkColor.red])"
|
||||
]
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
// swift-tools-version:6.2
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "NoTraits",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
products: [
|
||||
.executable(name: "NoTraits", targets: ["NoTraits"])
|
||||
],
|
||||
dependencies: [
|
||||
// swift-log
|
||||
.package(
|
||||
path: "../../"
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "NoTraits",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/NoTraitsBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 985,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 985,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 970,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5855,
|
||||
"objectAllocCount" : 2
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 7075,
|
||||
"objectAllocCount" : 3
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1890,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
// swift-tools-version:6.2
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "BenchmarksFactory",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
products: [
|
||||
.library(name: "BenchmarksFactory", targets: ["BenchmarksFactory"])
|
||||
],
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(path: "../"), // swift-log
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "BenchmarksFactory",
|
||||
dependencies: [
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
@@ -0,0 +1,55 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Benchmark
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public func makeBenchmark(
|
||||
loggerLevel: Logger.Level,
|
||||
logLevel: Logger.Level,
|
||||
_ suffix: String = "",
|
||||
_ body: @escaping (Logger) -> Void
|
||||
) {
|
||||
let iterations = 1_000_000
|
||||
let metrics: [BenchmarkMetric] = [.instructions, .objectAllocCount]
|
||||
|
||||
var logger = Logger(label: "BenchmarkRunner_\(loggerLevel)_\(logLevel)")
|
||||
|
||||
// Use a NoOpLogHandler to avoid polluting the logs
|
||||
logger.handler = NoOpLogHandler(label: "NoOpLogHandler")
|
||||
logger.logLevel = loggerLevel
|
||||
|
||||
Benchmark(
|
||||
"\(logLevel)_log_with_\(loggerLevel)_log_level\(suffix)",
|
||||
configuration: .init(
|
||||
metrics: metrics,
|
||||
maxIterations: iterations,
|
||||
thresholds: [
|
||||
.instructions: BenchmarkThresholds(
|
||||
relative: [
|
||||
.p90: 10.0 // we only record p90
|
||||
]
|
||||
),
|
||||
.objectAllocCount: BenchmarkThresholds(
|
||||
absolute: [
|
||||
.p90: 0 // we only record p90
|
||||
]
|
||||
),
|
||||
]
|
||||
)
|
||||
) { _ in
|
||||
body(logger)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,132 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Logging
|
||||
|
||||
// MARK: - Benchmark attributes
|
||||
|
||||
public enum BenchmarkSensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
|
||||
case sensitive = 1
|
||||
case `public` = 2
|
||||
}
|
||||
|
||||
extension Logger.MetadataValue.StringInterpolation {
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
|
||||
_ value: T,
|
||||
sensitivity: BenchmarkSensitivity
|
||||
) {
|
||||
self.appendInterpolation(value, attributes: { $0[BenchmarkSensitivity.self] = sensitivity })
|
||||
}
|
||||
}
|
||||
|
||||
public enum BenchmarkColor: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
|
||||
case red = 1
|
||||
case blue = 2
|
||||
}
|
||||
|
||||
extension Logger.MetadataValue.StringInterpolation {
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
|
||||
_ value: T,
|
||||
color: BenchmarkColor
|
||||
) {
|
||||
self.appendInterpolation(value, attributes: { $0[BenchmarkColor.self] = color })
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - NoOpLogHandler
|
||||
|
||||
struct NoOpLogHandler: LogHandler {
|
||||
let label: String
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
init(label: String, metadataProvider: Logger.MetadataProvider?) {
|
||||
self.label = label
|
||||
self.metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
init(label: String) {
|
||||
self.label = label
|
||||
self.metadataProvider = LoggingSystem.metadataProvider
|
||||
}
|
||||
|
||||
func log(
|
||||
event: LogEvent
|
||||
) {
|
||||
// Access metadata attributes
|
||||
if let metadata = event.metadata {
|
||||
for (_, value) in metadata {
|
||||
let _ = value.attributes
|
||||
}
|
||||
}
|
||||
|
||||
// Do nothing
|
||||
}
|
||||
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata explicitMetadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
// Access metadata attributes
|
||||
if let metadata = explicitMetadata {
|
||||
for (_, value) in metadata {
|
||||
let _ = value.attributes
|
||||
}
|
||||
}
|
||||
|
||||
// Do nothing
|
||||
}
|
||||
|
||||
private var _logLevel: Logger.Level?
|
||||
var logLevel: Logger.Level {
|
||||
get {
|
||||
self._logLevel ?? .debug
|
||||
}
|
||||
set {
|
||||
self._logLevel = newValue
|
||||
}
|
||||
}
|
||||
|
||||
private var _metadataSet = false
|
||||
private var _metadata = Logger.Metadata() {
|
||||
didSet {
|
||||
self._metadataSet = true
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logger.Metadata {
|
||||
get {
|
||||
self._metadata
|
||||
}
|
||||
set {
|
||||
self._metadata = newValue
|
||||
}
|
||||
}
|
||||
|
||||
// TODO: would be nice to delegate to local copy of logger but StdoutLogger is a reference type. why?
|
||||
subscript(metadataKey metadataKey: Logger.Metadata.Key) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self._metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
self._metadata[metadataKey] = newValue
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,3 +0,0 @@
|
||||
# Code of Conduct
|
||||
|
||||
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
|
||||
+58
-39
@@ -45,52 +45,71 @@ Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 20
|
||||
My system has IPv6 disabled.
|
||||
```
|
||||
|
||||
## Writing a Patch
|
||||
## Make sure Tests work on Linux
|
||||
|
||||
A good SwiftLog patch is:
|
||||
SwiftLog uses Swift Testing to run tests on all supported platforms.
|
||||
|
||||
1. Concise, and contains as few changes as needed to achieve the end result.
|
||||
2. Tested, ensuring that any tests provided failed before the patch and pass after it.
|
||||
3. Documented, adding API documentation as needed to cover new functions and properties.
|
||||
4. Accompanied by a great commit message, using our commit message template.
|
||||
## Run CI checks locally
|
||||
|
||||
### Commit Message Template
|
||||
You can run the Github Actions workflows locally using
|
||||
[act](https://github.com/nektos/act). To run all the jobs that run on a pull
|
||||
request, use the following command:
|
||||
|
||||
We require that your commit messages match our template. The easiest way to do that is to get git to help you by explicitly using the template. To do that, `cd` to the root of our repository and run:
|
||||
|
||||
git config commit.template dev/git.commit.template
|
||||
|
||||
### Make sure Tests work on Linux
|
||||
|
||||
SwiftLog uses XCTest to run tests on both macOS and Linux. While the macOS version of XCTest is able to use the Objective-C runtime to discover tests at execution time, the Linux version is not.
|
||||
For this reason, whenever you add new tests **you have to run a script** that generates the hooks needed to run those tests on Linux, or our CI will complain that the tests are not all present on Linux. To do this, merely execute `ruby ./scripts/generate_linux_tests.rb` at the root of the package and check the changes it made.
|
||||
|
||||
### Run `./scripts/soundness.sh`
|
||||
|
||||
The scripts directory contains a [soundness.sh script](https://github.com/apple/swift-log/blob/main/scripts/soundness.sh)
|
||||
that enforces additional checks, like license headers and formatting style.
|
||||
|
||||
Please make sure to `./scripts/soundness.sh` before pushing a change upstream, otherwise it is likely the PR validation will fail
|
||||
on minor changes such as a missing `self.` or similar formatting issues.
|
||||
|
||||
> The script also executes the above mentioned `generate_linux_tests.rb`.
|
||||
|
||||
For frequent contributors, we recommend adding the script as a [git pre-push hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), which you can do via executing the following command in the project root directory:
|
||||
|
||||
```bash
|
||||
cat << EOF > .git/hooks/pre-push
|
||||
#!/bin/bash
|
||||
|
||||
if [[ -f "scripts/soundness.sh" ]]; then
|
||||
scripts/soundness.sh
|
||||
fi
|
||||
EOF
|
||||
```
|
||||
% act pull_request
|
||||
```
|
||||
|
||||
Which makes the script execute, and only allow the `git push` to complete if the check has passed.
|
||||
To run just a single job, use `workflow_call -j <job>`, and specify the inputs
|
||||
the job expects. For example, to run just shellcheck:
|
||||
|
||||
```
|
||||
% act workflow_call -j soundness --input shell_check_enabled=true
|
||||
```
|
||||
|
||||
To bind-mount the working directory to the container, rather than a copy, use
|
||||
`--bind`. For example, to run just the formatting, and have the results
|
||||
reflected in your working directory:
|
||||
|
||||
```
|
||||
% act --bind workflow_call -j soundness --input format_check_enabled=true
|
||||
```
|
||||
|
||||
If you'd like `act` to always run with certain flags, these can be be placed in
|
||||
an `.actrc` file either in the current working directory or your home
|
||||
directory, for example:
|
||||
|
||||
```
|
||||
--container-architecture=linux/amd64
|
||||
--remote-name upstream
|
||||
--action-offline-mode
|
||||
```
|
||||
|
||||
## 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`.
|
||||
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).
|
||||
|
||||
In the case of formatting issues, you can then `git add` the formatting changes, and attempt the push again.
|
||||
|
||||
## How to contribute your work
|
||||
|
||||
Please open a pull request at https://github.com/apple/swift-log. Make sure the CI passes, and then wait for code review.
|
||||
For non-trivial changes that affect the public API, it is good practice to have a discussion phase before writing code. Please follow the [proposal process](Sources/Logging/Docs.docc/Proposals/Proposals.md) to gather feedback and align on the approach with other contributors.
|
||||
|
||||
1. Prepare your change, keeping in mind that a good patch is:
|
||||
- Concise, and contains as few changes as needed to achieve the end result.
|
||||
- Tested, ensuring that any tests provided failed before the patch and pass after it.
|
||||
- Documented, adding API documentation as needed to cover new functions and properties.
|
||||
- Accompanied by a great commit message.
|
||||
2. Open a pull request at https://github.com/apple/swift-log and wait for code review by the maintainers.
|
||||
|
||||
|
||||
## Automated release process
|
||||
|
||||
This repository uses automated releases based on semantic versioning labels. See the [Auto Release Workflow documentation](https://github.com/apple/swift-temporal-sdk/blob/main/.github/workflows/README.md) for details.
|
||||
@@ -1,27 +0,0 @@
|
||||
For the purpose of tracking copyright, this is the list of individuals and
|
||||
organizations who have contributed source code to the Swift Logging API.
|
||||
|
||||
For employees of an organization/company where the copyright of work done
|
||||
by employees of that company is held by the company itself, only the company
|
||||
needs to be listed here.
|
||||
|
||||
## COPYRIGHT HOLDERS
|
||||
|
||||
- Apple Inc. (all contributors with '@apple.com')
|
||||
|
||||
### Contributors
|
||||
|
||||
- David Hart <david@hartbit.com>
|
||||
- Iain Smith <iainsmith@users.noreply.github.com>
|
||||
- Ian Partridge <i.partridge@uk.ibm.com>
|
||||
- Johannes Weiss <johannesweiss@apple.com>
|
||||
- Kevin Sweeney <kevin.t.sweeney@gmail.com>
|
||||
- Konrad `ktoso` Malawski <ktoso@apple.com>
|
||||
- Max Moiseev <moiseev@apple.com>
|
||||
- Tanner <me@tanner.xyz>
|
||||
- Thomas Krajacic <tkrajacic@users.noreply.github.com>
|
||||
- Tomer Doron <tomer@apple.com>
|
||||
|
||||
**Updating this list**
|
||||
|
||||
Please do not edit this file manually. It is generated using `./scripts/generate_contributors_list.sh`. If a name is misspelled or appearing multiple times: add an entry in `./.mailmap`
|
||||
@@ -26,15 +26,6 @@ components that this product depends on.
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
This product contains a derivation of the Tony Stone's 'process_test_files.rb'.
|
||||
|
||||
* LICENSE (Apache License 2.0):
|
||||
* https://www.apache.org/licenses/LICENSE-2.0
|
||||
* HOMEPAGE:
|
||||
* https://codegists.com/snippet/ruby/generate_xctest_linux_runnerrb_tonystone_ruby
|
||||
|
||||
---
|
||||
|
||||
This product contains a derivation of the lock implementation and various
|
||||
scripts from SwiftNIO.
|
||||
|
||||
|
||||
+50
-33
@@ -1,55 +1,72 @@
|
||||
// swift-tools-version:5.9
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
// swift-tools-version:6.2
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-log",
|
||||
products: [
|
||||
.library(name: "Logging", targets: ["Logging"])
|
||||
.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 {
|
||||
for target in package.targets
|
||||
where [.executable, .test, .regular].contains(
|
||||
target.type
|
||||
) {
|
||||
var settings = target.swiftSettings ?? []
|
||||
settings.append(.enableExperimentalFeature("StrictConcurrency=complete"))
|
||||
|
||||
// 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"))
|
||||
|
||||
// https://docs.swift.org/compiler/documentation/diagnostics/nonisolated-nonsending-by-default/
|
||||
settings.append(.enableUpcomingFeature("NonisolatedNonsendingByDefault"))
|
||||
|
||||
// Ensure all public types are explicitly annotated as Sendable or not Sendable.
|
||||
settings.append(.unsafeFlags(["-Xfrontend", "-require-explicit-sendable"]))
|
||||
|
||||
target.swiftSettings = settings
|
||||
}
|
||||
|
||||
// --- STANDARD CROSS-REPO SETTINGS DO NOT EDIT --- //
|
||||
for target in package.targets {
|
||||
switch target.type {
|
||||
case .regular, .test, .executable:
|
||||
var settings = target.swiftSettings ?? []
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
|
||||
settings.append(.enableUpcomingFeature("MemberImportVisibility"))
|
||||
target.swiftSettings = settings
|
||||
case .macro, .plugin, .system, .binary:
|
||||
() // not applicable
|
||||
@unknown default:
|
||||
() // we don't know what to do here, do nothing
|
||||
}
|
||||
}
|
||||
// --- END: STANDARD CROSS-REPO SETTINGS DO NOT EDIT --- //
|
||||
@@ -0,0 +1,66 @@
|
||||
// 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
|
||||
}
|
||||
@@ -1,5 +1,10 @@
|
||||
# SwiftLog
|
||||
|
||||
[](https://swiftpackageindex.com/apple/swift-log/documentation)
|
||||
[](https://github.com/apple/swift-log/releases)
|
||||
[](https://swiftpackageindex.com/apple/swift-log)
|
||||
[](https://swiftpackageindex.com/apple/swift-log)
|
||||
|
||||
This repository contains a logging API implementation for Swift.
|
||||
SwiftLog provides a unified, performant, and ergonomic logging API that can be
|
||||
adopted by libraries and applications across the Swift ecosystem.
|
||||
@@ -7,7 +12,7 @@ adopted by libraries and applications across the Swift ecosystem.
|
||||
- 📚 **Documentation** and **tutorials** are available on the [Swift Package Index](https://swiftpackageindex.com/apple/swift-log)
|
||||
- 🚀 **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- 🪪 **License** is Apache 2.0, repeated in [LICENSE.txt](LICENSE.txt)
|
||||
- 🔒 **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md)
|
||||
- 🔒 **Security** issues should be reported via the process in [Security](https://github.com/apple/swift-log?tab=security-ov-file)
|
||||
- 🔀 **Available Logging Backends**: SwiftLog is an API package - you'll want to
|
||||
choose from the many
|
||||
[community-maintained logging backends](#available-log-handler-backends) for production use
|
||||
|
||||
-43
@@ -1,43 +0,0 @@
|
||||
# Security
|
||||
|
||||
This document specifies the security process for the SwiftLog project.
|
||||
|
||||
## Disclosures
|
||||
|
||||
### Private Disclosure Process
|
||||
|
||||
The SwiftLog maintainers ask that known and suspected vulnerabilities be
|
||||
privately and responsibly disclosed by emailing
|
||||
[sswg-security-reports@forums.swift.org](mailto:sswg-security-reports@forums.swift.org)
|
||||
with the all the required detail.
|
||||
**Do not file a public issue.**
|
||||
|
||||
#### When to report a vulnerability
|
||||
|
||||
* You think you have discovered a potential security vulnerability in SwiftLog.
|
||||
* You are unsure how a vulnerability affects SwiftLog.
|
||||
|
||||
#### What happens next?
|
||||
|
||||
* A member of the team will acknowledge receipt of the report within 3
|
||||
working days (United States). This may include a request for additional
|
||||
information about reproducing the vulnerability.
|
||||
* We will privately inform the Swift Server Work Group ([SSWG][sswg]) of the
|
||||
vulnerability within 10 days of the report as per their [security
|
||||
guidelines][sswg-security].
|
||||
* Once we have identified a fix we may ask you to validate it. We aim to do this
|
||||
within 30 days. In some cases this may not be possible, for example when the
|
||||
vulnerability exists at the protocol level and the industry must coordinate on
|
||||
the disclosure process.
|
||||
* If a CVE number is required, one will be requested from [MITRE][mitre]
|
||||
providing you with full credit for the discovery.
|
||||
* We will decide on a planned release date and let you know when it is.
|
||||
* Prior to release, we will inform major dependents that a security-related
|
||||
patch is impending.
|
||||
* Once the fix has been released we will publish a security advisory on GitHub
|
||||
and in the Server → Security Updates category on the [Swift forums][swift-forums-sec].
|
||||
|
||||
[sswg]: https://github.com/swift-server/sswg
|
||||
[sswg-security]: https://www.swift.org/sswg/security/
|
||||
[swift-forums-sec]: https://forums.swift.org/c/server/security-updates/
|
||||
[mitre]: https://cveform.mitre.org/
|
||||
@@ -0,0 +1,8 @@
|
||||
// Import the logging API
|
||||
import Logging
|
||||
|
||||
// Create a logger with a label
|
||||
let logger = Logger(label: "MyLogger")
|
||||
|
||||
// Use it to log messages
|
||||
logger.info("Hello World!")
|
||||
@@ -0,0 +1,194 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2022 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
public import Logging
|
||||
|
||||
/// A custom log handler which just collects logs into memory.
|
||||
/// You can then retrieve an array of those log entries.
|
||||
/// Example use cases include testing and buffering.
|
||||
///
|
||||
/// # Usage
|
||||
/// ```swift
|
||||
/// let logHandler = InMemoryLogHandler()
|
||||
/// let logger = Logger(
|
||||
/// label: "MyApp",
|
||||
/// factory: { _ in
|
||||
/// logHandler
|
||||
/// }
|
||||
/// )
|
||||
/// // Use logger to emit some logs
|
||||
/// someFunction(logger: logger)
|
||||
///
|
||||
/// // Retrieve what was logged
|
||||
/// let logEntries = logger.entries
|
||||
/// ```
|
||||
///
|
||||
public struct InMemoryLogHandler: LogHandler {
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
public var logLevel: Logger.Level = .info
|
||||
private let logStore: LogStore
|
||||
|
||||
/// A struct representing a log entry.
|
||||
public struct Entry: Sendable, Equatable {
|
||||
/// The level we logged at.
|
||||
public var level: Logger.Level
|
||||
/// The message which was logged.
|
||||
public var message: Logger.Message
|
||||
/// The error which was logged.
|
||||
public var error: (any Error)?
|
||||
/// The metadata which was logged.
|
||||
public var metadata: Logger.Metadata
|
||||
|
||||
public init(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata) {
|
||||
self.level = level
|
||||
self.message = message
|
||||
self.metadata = metadata
|
||||
}
|
||||
|
||||
public init(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata
|
||||
) {
|
||||
self.level = level
|
||||
self.message = message
|
||||
self.error = error
|
||||
self.metadata = metadata
|
||||
}
|
||||
|
||||
public static func == (lhs: Entry, rhs: Entry) -> Bool {
|
||||
lhs.level == rhs.level
|
||||
&& lhs.message == rhs.message
|
||||
&& lhs.metadata == rhs.metadata
|
||||
&& errorsEqual(lhs.error, rhs.error)
|
||||
}
|
||||
|
||||
private static func errorsEqual(_ lhs: (any Error)?, _ rhs: (any Error)?) -> Bool {
|
||||
switch (lhs, rhs) {
|
||||
case (nil, nil):
|
||||
return true
|
||||
case let (l?, r?):
|
||||
return "\(l)" == "\(r)" && String(reflecting: type(of: l)) == String(reflecting: type(of: r))
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private final class LogStore: @unchecked Sendable {
|
||||
private var _entries: [Entry] = []
|
||||
private let lock = Lock()
|
||||
|
||||
fileprivate func append(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata
|
||||
) {
|
||||
self.lock.withLockVoid {
|
||||
self._entries.append(
|
||||
Entry(
|
||||
level: level,
|
||||
message: message,
|
||||
error: error,
|
||||
metadata: metadata
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
fileprivate func clear() {
|
||||
self.lock.withLockVoid {
|
||||
_entries.removeAll()
|
||||
}
|
||||
}
|
||||
|
||||
var entries: [Entry] {
|
||||
self.lock.withLock { self._entries }
|
||||
}
|
||||
}
|
||||
|
||||
private init(logStore: LogStore) {
|
||||
self.logStore = logStore
|
||||
}
|
||||
|
||||
/// Create a new ``InMemoryLogHandler``.
|
||||
public init() {
|
||||
self.init(logStore: .init())
|
||||
}
|
||||
|
||||
public func log(event: LogEvent) {
|
||||
var merged = self.metadata
|
||||
|
||||
if let provider = self.metadataProvider {
|
||||
let provided = provider.get()
|
||||
merged.merge(provided, uniquingKeysWith: { _, rhs in rhs })
|
||||
}
|
||||
|
||||
if let eventMetadata = event.metadata {
|
||||
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
|
||||
}
|
||||
|
||||
self.logStore.append(
|
||||
level: event.level,
|
||||
message: event.message,
|
||||
error: event.error,
|
||||
metadata: merged
|
||||
)
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
event: LogEvent(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self.metadata[key]
|
||||
}
|
||||
set {
|
||||
self.metadata[key] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
/// All logs that have been collected.
|
||||
public var entries: [Entry] {
|
||||
self.logStore.entries
|
||||
}
|
||||
|
||||
/// Clear all entries.
|
||||
public func clear() {
|
||||
self.logStore.clear()
|
||||
}
|
||||
}
|
||||
@@ -1,7 +1,6 @@
|
||||
# 001: Choosing log levels
|
||||
|
||||
Best practice for selecting appropriate log levels in applications and
|
||||
libraries.
|
||||
Select appropriate log levels in applications and libraries.
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -10,7 +9,7 @@ creating well-behaved libraries that don't overwhelm logging systems or misuse
|
||||
severity levels. This practice provides clear guidance on when to use each
|
||||
level.
|
||||
|
||||
### Motivation
|
||||
### Motivation
|
||||
|
||||
Libraries must be well-behaved across various use cases and cannot assume
|
||||
specific logging backend configurations. Using inappropriate log levels can
|
||||
@@ -39,29 +38,30 @@ its logging environment.
|
||||
|
||||
#### For libraries
|
||||
|
||||
Libraries should use **info level or lower** (info, debug, trace). Each level
|
||||
serves different purposes:
|
||||
Libraries should use **info level or less severe** (info, debug, trace).
|
||||
|
||||
Libraries **should not** log information on **warning or more severe levels**,
|
||||
unless it is a one-time (for example during startup) warning, that cannot lead
|
||||
to overwhelming log outputs.
|
||||
|
||||
##### Trace Level
|
||||
- **Usage**: Log everything needed to diagnose hard-to-reproduce bugs
|
||||
- **Performance**: May impact performance; assume it won't be used in production
|
||||
- **Content**: Internal state, detailed operation flows, diagnostic information
|
||||
Each level serves different purposes:
|
||||
|
||||
##### Debug Level
|
||||
- **Usage**: May be enabled in some production deployments
|
||||
- **Performance**: Should not significantly undermine production performance
|
||||
- **Content**: High-level operation overview, connection events, major decisions
|
||||
##### Trace Level
|
||||
- **Usage**: Log everything needed to diagnose hard-to-reproduce bugs.
|
||||
- **Performance**: May impact performance; assume it won't be used in production.
|
||||
- **Content**: Internal state, detailed operation flows, diagnostic information.
|
||||
|
||||
##### Debug Level
|
||||
- **Usage**: May be enabled in some production deployments.
|
||||
- **Performance**: Should not significantly undermine production performance.
|
||||
- **Content**: High-level operation overview, connection events, major decisions.
|
||||
|
||||
##### Info Level
|
||||
- **Usage**: Reserved for things that went wrong but can't be communicated
|
||||
through other means like throwing from a method
|
||||
through other means, like throwing from a method.
|
||||
- **Examples**: Connection retry attempts, fallback mechanisms, recoverable
|
||||
failures
|
||||
- **Guideline**: Use sparingly - not for normal successful operations
|
||||
failures.
|
||||
- **Guideline**: Use sparingly - Don't use for normal successful operations.
|
||||
|
||||
#### For applications
|
||||
|
||||
@@ -128,11 +128,11 @@ logger.info("Request failed")
|
||||
```swift
|
||||
// ❌ Bad: Normal operations at info level flood production logs
|
||||
logger.info("HTTP request received")
|
||||
logger.info("Database query executed")
|
||||
logger.info("Database query executed")
|
||||
logger.info("Response sent")
|
||||
|
||||
// ✅ Good: Use appropriate levels instead
|
||||
logger.debug("Processing request", metadata: ["path": "\(path)"])
|
||||
logger.trace("Query", , metadata: ["path": "\(query)"])
|
||||
logger.trace("Query", metadata: ["sql": "\(query)"])
|
||||
logger.debug("Request completed", metadata: ["status": "\(status)"])
|
||||
```
|
||||
@@ -0,0 +1,96 @@
|
||||
# 002: Structured logging
|
||||
|
||||
Use metadata to create machine-readable, searchable log entries.
|
||||
|
||||
## Overview
|
||||
|
||||
Structured logging uses metadata to separate human-readable messages from
|
||||
machine-readable data. This practice makes logs easier to search, filter, and
|
||||
analyze programmatically while maintaining readability.
|
||||
|
||||
### Motivation
|
||||
|
||||
Traditional string-based logging embeds all information in the message text,
|
||||
making it more difficult for automated tools to parse and extract.
|
||||
Structured logging separates these concerns; messages provide human readable
|
||||
context while metadata provides structured data for tooling.
|
||||
|
||||
### Example
|
||||
|
||||
#### Recommended: Structured logging
|
||||
|
||||
```swift
|
||||
// ✅ Structured - message provides context, metadata provides data
|
||||
logger.info(
|
||||
"Accepted connection",
|
||||
metadata: [
|
||||
"connection.id": "\(id)",
|
||||
"connection.peer": "\(peer)",
|
||||
"connections.total": "\(count)"
|
||||
]
|
||||
)
|
||||
|
||||
logger.error(
|
||||
"Database query failed",
|
||||
metadata: [
|
||||
"query.retries": "\(retries)",
|
||||
"query.error": "\(error)",
|
||||
"query.duration": "\(duration)"
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Advanced: Nested metadata for complex data
|
||||
|
||||
```swift
|
||||
// ✅ Complex structured data
|
||||
logger.trace(
|
||||
"HTTP request started",
|
||||
metadata: [
|
||||
"request.id": "\(requestId)",
|
||||
"request.method": "GET",
|
||||
"request.path": "/api/users",
|
||||
"request.headers": [
|
||||
"user-agent": "\(userAgent)"
|
||||
],
|
||||
"client.ip": "\(clientIP)",
|
||||
"client.country": "\(country)"
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
#### Avoid: Unstructured logging
|
||||
|
||||
```swift
|
||||
// ❌ Not structured - hard to parse programmatically
|
||||
logger.info("Accepted connection \(id) from \(peer), total: \(count)")
|
||||
logger.error("Database query failed after \(retries) retries: \(error)")
|
||||
```
|
||||
|
||||
### Metadata key conventions
|
||||
|
||||
Use hierarchical dot-notation for related fields:
|
||||
|
||||
```swift
|
||||
// ✅ Good: Hierarchical keys
|
||||
logger.debug(
|
||||
"Database operation completed",
|
||||
metadata: [
|
||||
"db.operation": "SELECT",
|
||||
"db.table": "users",
|
||||
"db.duration": "\(duration)",
|
||||
"db.rows": "\(rowCount)"
|
||||
]
|
||||
)
|
||||
|
||||
// ✅ Good: Consistent prefixing
|
||||
logger.info(
|
||||
"HTTP response",
|
||||
metadata: [
|
||||
"http.method": "POST",
|
||||
"http.status": "201",
|
||||
"http.path": "/api/users",
|
||||
"http.duration": "\(duration)"
|
||||
]
|
||||
)
|
||||
```
|
||||
@@ -0,0 +1,100 @@
|
||||
# 003: Accepting loggers in libraries
|
||||
|
||||
Accept loggers through method parameters to ensure proper metadata propagation.
|
||||
|
||||
## 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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Example
|
||||
|
||||
#### Recommended: Accept logger through method parameters
|
||||
|
||||
```swift
|
||||
// ✅ Good: Pass the logger through method parameters.
|
||||
struct RequestProcessor {
|
||||
func processRequest(_ request: HTTPRequest, logger: Logger) async throws -> HTTPResponse {
|
||||
// Add structured metadata that every log statement should contain.
|
||||
var logger = logger
|
||||
logger[metadataKey: "request.method"] = "\(request.method)"
|
||||
logger[metadataKey: "request.path"] = "\(request.path)"
|
||||
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
|
||||
|
||||
```swift
|
||||
// ✅ 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")
|
||||
// Execute some more long running work
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 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.
|
||||
|
||||
```swift
|
||||
// ❌ Bad: Library creates its own logger
|
||||
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
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,84 @@
|
||||
# Disable log levels during compilation
|
||||
|
||||
SwiftLog provides compile-time traits to eliminate less severe log levels from
|
||||
your binary reducing the runtime overhead.
|
||||
|
||||
## Overview
|
||||
|
||||
### Motivation
|
||||
|
||||
When deploying applications to production, you often know in advance which log
|
||||
levels will never be needed. For example, a production service might only need
|
||||
warning and above, while trace and debug levels are only useful during
|
||||
development. By using traits, you can completely remove these unnecessary log
|
||||
levels at compile time, achieving zero runtime overhead.
|
||||
|
||||
### Available traits
|
||||
|
||||
SwiftLog defines seven maximum log level traits, ordered from most permissive
|
||||
to most restrictive:
|
||||
|
||||
- `MaxLogLevelDebug`: Debug and above available (compiles out trace)
|
||||
- `MaxLogLevelInfo`: Info and above available (compiles out trace, debug)
|
||||
- `MaxLogLevelNotice`: Notice and above available (compiles out trace, debug,
|
||||
info)
|
||||
- `MaxLogLevelWarning`: Warning and above available (compiles out trace, debug,
|
||||
info, notice)
|
||||
- `MaxLogLevelError`: Error and above available (compiles out trace, debug,
|
||||
info, notice, warning)
|
||||
- `MaxLogLevelCritical`: Only critical available (compiles out all except
|
||||
critical)
|
||||
- `MaxLogLevelNone`: All logging compiled out (no log levels available)
|
||||
|
||||
By default (when no traits are specified), all log levels are available.
|
||||
|
||||
When you specify a maximum log level trait, all less severe levels are
|
||||
completely removed from your binary at compile time. This applies to both
|
||||
level-specific methods (e.g., `logger.debug()`) and calls to the generic
|
||||
`logger.log(level:)` method. Traits are additive. If multiple max level traits
|
||||
are specified, the most restrictive one takes effect.
|
||||
|
||||
> Note: Traits should only be set by the applications and not libraries as
|
||||
> any traits defined in a transitive dependency will affect the whole resolution tree.
|
||||
|
||||
### Example
|
||||
|
||||
To enable a trait, specify it when declaring your package dependency:
|
||||
|
||||
```swift
|
||||
// In your Package.swift:
|
||||
dependencies: [
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["MaxLogLevelWarning"]
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
With `MaxLogLevelWarning` enabled, all trace, debug, info, and notice log
|
||||
statements are compiled out:
|
||||
|
||||
```swift
|
||||
// These become no-ops (compiled out completely):
|
||||
logger.trace("This will not be in the binary")
|
||||
logger.debug("This will not be in the binary")
|
||||
logger.info("This will not be in the binary")
|
||||
logger.notice("This will not be in the binary")
|
||||
logger.log(level: .debug, "This will not log anything")
|
||||
|
||||
// These work normally:
|
||||
logger.warning("This still works")
|
||||
logger.error("This still works")
|
||||
logger.critical("This still works")
|
||||
logger.log(level: .error, "This still works")
|
||||
```
|
||||
|
||||
When `MaxLogLevelNone` is enabled no log statement can ever fire, so
|
||||
mutations that only configure the underlying ``LogHandler`` for future log
|
||||
statements are also compiled out. Specifically, the body of the
|
||||
``Logger/subscript(metadataKey:)`` setter and the body of the
|
||||
``Logger/logLevel`` setter become empty, so calls like
|
||||
`logger[metadataKey: "user-id"] = "\(id)"` and `logger.logLevel = .info`
|
||||
do not reach the handler. Reads continue to work and return whatever the
|
||||
handler reports.
|
||||
@@ -1,11 +1,10 @@
|
||||
# Implementing a log handler
|
||||
|
||||
Create a custom logging backend that provides logging services for your apps
|
||||
and libraries.
|
||||
Create a custom logging backend that provides logging services for your apps and libraries.
|
||||
|
||||
## Overview
|
||||
|
||||
To become a compatible logging backend that any `SwiftLog` consumer can use,
|
||||
To become a compatible logging backend that any SwiftLog consumer can use,
|
||||
you need to fulfill a few requirements, primarily conforming to the
|
||||
``LogHandler`` protocol.
|
||||
|
||||
@@ -24,11 +23,11 @@ func logHandlerValueSemantics() {
|
||||
var logger1 = Logger(label: "first logger")
|
||||
logger1.logLevel = .debug
|
||||
logger1[metadataKey: "only-on"] = "first"
|
||||
|
||||
|
||||
var logger2 = logger1
|
||||
logger2.logLevel = .error // Must not affect logger1
|
||||
logger2[metadataKey: "only-on"] = "second" // Must not affect logger1
|
||||
|
||||
|
||||
// These expectations must pass
|
||||
#expect(logger1.logLevel == .debug)
|
||||
#expect(logger2.logLevel == .error)
|
||||
@@ -52,37 +51,29 @@ public struct PrintLogHandler: LogHandler {
|
||||
private let label: String
|
||||
public var logLevel: Logger.Level = .info
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
|
||||
|
||||
public init(label: String) {
|
||||
self.label = label
|
||||
}
|
||||
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
|
||||
public func log(event: LogEvent) {
|
||||
let timestamp = ISO8601DateFormatter().string(from: Date())
|
||||
let levelString = level.rawValue.uppercased()
|
||||
|
||||
let levelString = event.level.rawValue.uppercased()
|
||||
|
||||
// Merge handler metadata with message metadata
|
||||
let combinedMetadata = Self.prepareMetadata(
|
||||
base: self.metadata
|
||||
explicit: metadata
|
||||
base: self.metadata,
|
||||
explicit: event.metadata
|
||||
)
|
||||
|
||||
|
||||
// Format metadata
|
||||
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
|
||||
|
||||
|
||||
// Create log line and print to console
|
||||
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
|
||||
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(event.message)"
|
||||
print(logLine)
|
||||
}
|
||||
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
return self.metadata[key]
|
||||
@@ -129,41 +120,30 @@ public struct PrintLogHandler: LogHandler {
|
||||
public var logLevel: Logger.Level = .info
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
|
||||
public init(label: String) {
|
||||
self.label = label
|
||||
}
|
||||
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
|
||||
public func log(event: LogEvent) {
|
||||
let timestamp = ISO8601DateFormatter().string(from: Date())
|
||||
let levelString = level.rawValue.uppercased()
|
||||
|
||||
// Get provider metadata
|
||||
let providerMetadata = metadataProvider?.get() ?? [:]
|
||||
let levelString = event.level.rawValue.uppercased()
|
||||
|
||||
// Merge handler metadata with message metadata
|
||||
let combinedMetadata = Self.prepareMetadata(
|
||||
base: self.metadata,
|
||||
provider: self.metadataProvider,
|
||||
explicit: metadata
|
||||
explicit: event.metadata
|
||||
)
|
||||
|
||||
|
||||
// Format metadata
|
||||
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
|
||||
|
||||
|
||||
// Create log line and print to console
|
||||
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
|
||||
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(event.message)"
|
||||
print(logLine)
|
||||
}
|
||||
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
return self.metadata[key]
|
||||
@@ -200,6 +180,49 @@ public struct PrintLogHandler: LogHandler {
|
||||
}
|
||||
```
|
||||
|
||||
#### Reading metadata attributes in LogHandlers
|
||||
|
||||
Metadata values can carry attributes alongside their string representation. Attributes are embedded inside
|
||||
`MetadataValue` via the `.stringConvertible` case and are accessible through the `value.attributes` property. This
|
||||
enables features like sensitivity annotations without any changes to your handler's protocol conformance.
|
||||
|
||||
To read attributes in your log handler:
|
||||
|
||||
```swift
|
||||
public func log(event: LogEvent) {
|
||||
// Merge handler metadata, provider metadata, and event metadata as usual
|
||||
var merged = self.metadata
|
||||
|
||||
if let provider = self.metadataProvider {
|
||||
merged.merge(provider.get(), uniquingKeysWith: { _, rhs in rhs })
|
||||
}
|
||||
|
||||
if let eventMetadata = event.metadata {
|
||||
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
|
||||
}
|
||||
|
||||
// Read attributes from individual values:
|
||||
for (key, value) in merged {
|
||||
let attributes = value.attributes // Empty if the value carries no attributes
|
||||
|
||||
// Process based on your handler's needs
|
||||
// For example, check for a custom attribute:
|
||||
// if attributes[MyAttribute.self] == .flagged { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key considerations:**
|
||||
|
||||
- **Opt-in inspection**: Attributes are invisible unless you call `value.attributes`. Handlers that do not care about
|
||||
attributes work without any changes.
|
||||
|
||||
- **No new protocol requirements**: Reading attributes does not require implementing any new `LogHandler` properties
|
||||
or subscripts. The `metadata` property and `metadataKey` subscript work exactly as before.
|
||||
|
||||
- **Attributes flow through metadata**: Attributed values flow naturally through metadata merging, `MetadataProvider`,
|
||||
and `MultiplexLogHandler` — no special handling needed.
|
||||
|
||||
### Performance considerations
|
||||
|
||||
1. **Avoid blocking**: Don't block the calling thread for I/O operations.
|
||||
|
||||
@@ -39,3 +39,5 @@ practice includes:
|
||||
## Topics
|
||||
|
||||
- <doc:001-ChoosingLogLevels>
|
||||
- <doc:002-StructuredLogging>
|
||||
- <doc:003-AcceptingLoggers>
|
||||
@@ -0,0 +1,38 @@
|
||||
# Proposals
|
||||
|
||||
Collaborate on API changes to SwiftLog by writing a proposal.
|
||||
|
||||
## Overview
|
||||
|
||||
For non-trivial changes that affect the public API, the SwiftLog project adopts a lightweight version of the [Swift Evolution](https://github.com/apple/swift-evolution/blob/main/process.md) process.
|
||||
|
||||
Writing a proposal first helps discuss multiple possible solutions early, apply useful feedback from other contributors, and avoid reimplementing the same feature multiple times.
|
||||
|
||||
While it's encouraged to get feedback by opening a pull request with a proposal early in the process, it's also important to consider the complexity of the implementation when evaluating different solutions. For example, this might mean including a link to a branch containing a prototype implementation of the feature in the pull request description.
|
||||
|
||||
> Note: The goal of this process is to help solicit feedback from the whole community around the project, and we will continue to refine the proposal process itself. Use your best judgement, and don't hesitate to propose changes to the proposal structure itself!
|
||||
|
||||
### Steps
|
||||
|
||||
1. Make sure there's a GitHub issue for the feature or change you would like to propose.
|
||||
2. Duplicate the `SLG-NNNN.md` document and replace `NNNN` with the next available proposal number.
|
||||
3. Link the GitHub issue from your proposal, and fill in the proposal.
|
||||
4. Open a pull request with your proposal and solicit feedback from other contributors.
|
||||
5. Once a maintainer confirms that the proposal is ready for review, the state is updated accordingly. The review period is 7 days, and ends when one of the maintainers marks the proposal as Ready for Implementation, or Deferred.
|
||||
6. Before the pull request is merged, there should be an implementation ready, either in the same pull request, or a separate one, linked from the proposal.
|
||||
7. The proposal is considered Approved once the implementation, proposal PRs have been merged, and, if originally disabled by a feature flag, feature flag enabled unconditionally.
|
||||
|
||||
If you have any questions, ask in an issue on GitHub.
|
||||
|
||||
### Possible review states
|
||||
|
||||
- Awaiting Review
|
||||
- In Review
|
||||
- Ready for Implementation
|
||||
- In Preview
|
||||
- Approved
|
||||
- Deferred
|
||||
|
||||
## Topics
|
||||
|
||||
- <doc:SLG-NNNN>
|
||||
+5
-5
@@ -1,11 +1,11 @@
|
||||
# Metadata Providers
|
||||
|
||||
Authors: [Moritz Lang](https://github.com/slashmo), [Konrad 'ktoso' Malawski](https://github.com/ktoso)
|
||||
|
||||
## Introduction
|
||||
# SLG-0001: Metadata Providers
|
||||
|
||||
While global metadata attributes may be manually set on a `LogHandler` level, there's currently no way of reliably providing contextual, automatically propagated, metadata when logging with swift-log.
|
||||
|
||||
## Authors
|
||||
|
||||
[Moritz Lang](https://github.com/slashmo), [Konrad 'ktoso' Malawski](https://github.com/ktoso)
|
||||
|
||||
## Motivation
|
||||
|
||||
To benefit from tools such as [Distributed Tracing](https://github.com/apple/swift-distributed-tracing) it is necessary for libraries to make use of the trace information.
|
||||
@@ -0,0 +1,173 @@
|
||||
# SLG-0002: Compile-time log level elimination using traits
|
||||
|
||||
Enable compile-time elimination of log levels to achieve zero runtime overhead for logs that will never be needed in production.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0002
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#378](https://github.com/apple/swift-log/issues/378)
|
||||
- Implementation:
|
||||
- [apple/swift-log#389](https://github.com/apple/swift-log/pull/389)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
Add Swift package traits to allow applications to compile out less severe log levels, completely eliminating their runtime overhead from the final binary.
|
||||
|
||||
### Motivation
|
||||
|
||||
In production deployments, applications often know in advance which log levels will never be needed. For example, a production service typically only needs warning and above, while trace and debug levels are exclusively useful during development. Currently, even with the log level set to `.warning` at runtime, the code for trace and debug statements still exists in the binary and incurs overhead.
|
||||
|
||||
For performance-critical applications or resource-constrained environments, this overhead is unacceptable. Applications need a way to completely remove unnecessary log levels at compile time, achieving zero runtime cost.
|
||||
|
||||
Before this proposal, the only workarounds were:
|
||||
- Manually wrapping log statements in `#if DEBUG` checks (error-prone and verbose)
|
||||
- Accepting the runtime overhead (unacceptable for many use cases)
|
||||
|
||||
### Proposed solution
|
||||
|
||||
This proposal introduces seven package traits that correspond to maximum log level thresholds. Applications specify a trait when declaring their dependency on SwiftLog, and all less severe log levels are completely compiled out.
|
||||
|
||||
In your `Package.swift`:
|
||||
|
||||
```swift
|
||||
dependencies: [
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["MaxLogLevelWarning"]
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
With `MaxLogLevelWarning` enabled:
|
||||
|
||||
```swift
|
||||
// These become no-ops (compiled out completely):
|
||||
logger.trace("This will not be in the binary")
|
||||
logger.debug("This will not be in the binary")
|
||||
logger.info("This will not be in the binary")
|
||||
logger.notice("This will not be in the binary")
|
||||
logger.log(level: .debug, "This will not log anything")
|
||||
|
||||
// These work normally:
|
||||
logger.warning("This still works")
|
||||
logger.error("This still works")
|
||||
logger.critical("This still works")
|
||||
logger.log(level: .error, "This still works")
|
||||
```
|
||||
|
||||
### Detailed design
|
||||
|
||||
The seven available traits, ordered from most permissive to most restrictive, are:
|
||||
|
||||
```swift
|
||||
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)"),
|
||||
|
||||
.default(enabledTraits: []),
|
||||
]
|
||||
```
|
||||
|
||||
By default (when no traits are specified), all log levels remain available.
|
||||
|
||||
Traits are additive: if multiple max level traits are specified in the dependency graph, the most restrictive one takes effect. This ensures that if any dependency requests stricter elimination, the entire build respects it.
|
||||
|
||||
> Important: Traits should only be set by applications, not libraries, as any trait defined in a transitive dependency will affect the entire dependency resolution tree.
|
||||
|
||||
For the generic `log(level:)` method, the implementation switches behavior based on whether any trait is enabled:
|
||||
|
||||
```swift
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
) {
|
||||
#if MaxLogLevelDebug || MaxLogLevelInfo || MaxLogLevelNotice || MaxLogLevelWarning || MaxLogLevelError || MaxLogLevelCritical || MaxLogLevelNone
|
||||
// When traits are enabled, dispatch to level-specific methods
|
||||
// to leverage their compile-time elimination
|
||||
switch level {
|
||||
case .trace:
|
||||
self.trace(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
|
||||
case .debug:
|
||||
self.debug(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
|
||||
// ... (all levels)
|
||||
}
|
||||
#else
|
||||
// When no traits are enabled, avoid the switch overhead
|
||||
self._log(
|
||||
level: level,
|
||||
message(),
|
||||
metadata: metadata(),
|
||||
source: source(),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
#endif
|
||||
}
|
||||
```
|
||||
|
||||
This approach adds a minimal switch statement overhead when traits are enabled, but allows the level-specific methods' compile-time elimination to work even when called through `log(level:)`. When no traits are enabled, the original zero-overhead path is preserved. Level-specific methods has no additional overhead.
|
||||
|
||||
### API stability
|
||||
|
||||
**For existing `Logger` users:**
|
||||
- When no traits are enabled (the default), behavior is identical to before
|
||||
- Users can opt in to traits at the application level without modifying any source code
|
||||
|
||||
**For existing `LogHandler` implementations:**
|
||||
- No changes are required to any `LogHandler` implementation
|
||||
|
||||
### Future directions
|
||||
|
||||
No future directions identified.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Per-log-level traits
|
||||
|
||||
An alternative approach would be to define one trait per log level that could be individually disabled:
|
||||
|
||||
```swift
|
||||
traits: [
|
||||
.trait(name: "DisableTraceLogs"),
|
||||
.trait(name: "DisableDebugLogs"),
|
||||
.trait(name: "DisableInfoLogs"),
|
||||
.trait(name: "DisableNoticeLogs"),
|
||||
.trait(name: "DisableWarningLogs"),
|
||||
.trait(name: "DisableErrorLogs"),
|
||||
.trait(name: "DisableCriticalLogs"),
|
||||
]
|
||||
```
|
||||
|
||||
Users would specify multiple traits to eliminate multiple levels:
|
||||
|
||||
```swift
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["DisableTraceLogs", "DisableDebugLogs", "DisableInfoLogs", "DisableNoticeLogs"]
|
||||
)
|
||||
```
|
||||
|
||||
This approach was rejected in favor of a `MaxLogLevel` semantics to make it less verbose to use the functionality and to be aligned with the similar functionality in logging packages in other languages users might already be familiar with.
|
||||
@@ -0,0 +1,416 @@
|
||||
# SLG-0003: Support for Attaching Errors to Log Entries
|
||||
|
||||
Add standardized way of attaching data from `Error` instances to log entries.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0003
|
||||
- Author(s): [Samuel Murray](https://github.com/samuelmurray)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#291](https://github.com/apple/swift-log/issues/291)
|
||||
- Implementation:
|
||||
- [apple/swift-log#425](https://github.com/apple/swift-log/pull/425)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
- [First attempt at solution](https://github.com/apple/swift-log/pull/384)
|
||||
|
||||
### Introduction
|
||||
|
||||
Add new methods on `Logger` that accept an `Error` instance, which is passed as-is to the underlying `LogHandler`. To ensure backwards compatibility and a smooth adoption, a default implementation where the error is serialized into `MetadataValue`s is provided.
|
||||
|
||||
### Motivation
|
||||
|
||||
SwiftLog advocates for the use of _structured logging_, which in its implementation is achieved by using the `metadata` attribute in the log methods. This is important since it allows for automated tools to parse the logs and extract metadata values for filtering and/or visualization. When logging in a catch-block, it often makes sense to attach some information from the thrown `Error` in the log post, so as to capture the root cause.
|
||||
|
||||
```swift
|
||||
do {
|
||||
try someThrowingFunc()
|
||||
} catch {
|
||||
logger.warning("Something went wrong") // Want to somehow attach information about the error
|
||||
}
|
||||
```
|
||||
|
||||
Currently, there is no standardized way of doing this. The simplest way to do it would be to simply attach the stringified error to the message.
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong: \(error)")
|
||||
```
|
||||
|
||||
This of course is not _structured_, so a better way would be:
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong", metadata: ["error": "\(error)"])
|
||||
```
|
||||
|
||||
However, since there is no clear preference for what metadata key to use, it is likely that different code bases use variations of the above. This makes it hard for automated tools to extract error information, since there is no single key to look for.
|
||||
|
||||
Additionally, there is more information that we could extract from the error, such as the type name.
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong", metadata: ["error.message": "\(error)", "error.type": "\(String(reflecting: type(of: error)))"])
|
||||
```
|
||||
|
||||
The above is a reasonable way to log a generic error, but it is unlikely that everyone will use the same metadata keys. It is also quite a lot of code, for something that feels like it should be easy to do - i.e. attach an error to a log.
|
||||
|
||||
Finally, even if you log errors in a consistent way in your code, you do not control logs generated in other modules/packages that you use. In practice, this makes it so that different parts of your application could log error information under different keys, which, again, makes it harder for tooling.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
The solution we propose is to add convenience methods in `Logger` that allows the caller to do the following:
|
||||
|
||||
```swift
|
||||
do {
|
||||
try someThrowingFunc()
|
||||
} catch {
|
||||
logger.warning("Something went wrong", error: error)
|
||||
}
|
||||
```
|
||||
|
||||
The error would get passed as-is to the underlying `LogHandler`, which is free to serialize it in an appropriate way. We propose that such convenience methods are added for all log methods (even if it arguably makes less sense for e.g. `trace` and `debug` than `warning`).
|
||||
|
||||
There are two clear gains from this:
|
||||
|
||||
* It is obvious for the caller _how_ to attach an `Error` to a log (and the caller code also looks cleaner).
|
||||
* `LogHandler`s are free to serialize the `Error` in an way appropriate to that handler.
|
||||
|
||||
A `LogHandler` instance can access the `Error` using a new protocol method. A typical `LogHandler` implementation could be to extract the string representation and type name, and serialize it as metadata.
|
||||
|
||||
```swift
|
||||
struct ErrorLogHandler: LogHandler {
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
var metadata = metadata ?? [:]
|
||||
if let error {
|
||||
metadata.merge([
|
||||
"error.message": "\(error)",
|
||||
"error.type": "\(String(reflecting: type(of: error)))",
|
||||
]) { $1 }
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
As we extend the API of both `Logger` and `LogHandler`, we need to ensure compatibility with existing solutions on both sides. Specifically, users should be able to use the new `Logger` methods with existing `LogHandler`s, and get a reasonable serialization of the error. Otherwise, early adopters would have to manually serialize it _in addition to_ passing it using the new argument, until all `LogHandler`s have been updated. To achieve this, we add a default implementation on the `LogHandler` method, that serializes the `Error` as metadata, similar to the example above.
|
||||
|
||||
### Detailed design
|
||||
|
||||
The proposed solution is to add a new overload for each log method (`trace`, ..., `critical`) that accepts an `Error` as its second argument, as well as a new overload for `Logger.log`, that accepts an `Error` as its third argument.
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
/// Log a message at the 'trace' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/trace`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func trace(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'debug' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/debug`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func debug(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'info' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/info`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func info(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'notice' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/notice`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func notice(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'warning' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/warning`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func warning(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'error' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/error`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func error(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'critical' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/critical`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func critical(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message using the log level and source that you provide.
|
||||
///
|
||||
/// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library
|
||||
/// logs the message, otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - level: The severity level of the `message`.
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
A new method is also added to `LogHandler`, which receives the `Error` passed to `Logger`.
|
||||
|
||||
```swift
|
||||
protocol LogHandler {
|
||||
/// The library calls this method when a log handler must emit a log message.
|
||||
///
|
||||
/// There is no need for the `LogHandler` to check if the `level` is above or
|
||||
/// below the configured `logLevel` as `Logger` already performed this check and
|
||||
/// determined that a message should be logged.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - error: The `Error` associated to this log message.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
A default implementation is included via an extension method, that calls the existing `log` function. This is to ensure backwards compatibility, and is similar to how `source` was added. The default implementation will serialize the `Error`, extracting its string representation and fully qualified type name, and add those to the metadata under the keys `"error.message"` and `"error.type"` respectively.
|
||||
|
||||
A draft implementation can be found in [apple/swift-log#425](https://github.com/apple/swift-log/pull/425).
|
||||
|
||||
We choose the keys `"error.message"` and `"error.type"` since they correspond to what [ECS](https://www.elastic.co/docs/reference/ecs/ecs-error) and [OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/#error-type) use. However, we propose that the metadata keys used should **not** be considered stable or part of the `swift-log` API. Instead, if a `LogHandler` wants to use separate keys, it should implement the new protocol method, rather than re-map the metadata keys.
|
||||
|
||||
### API stability
|
||||
|
||||
The proposed additions are fully backwards compatible, meaning that all existing code will continue to function as is. Additionally, a user of `Logger` can start using the new convenience methods, without any modifications of the `LogHandler`, thanks to the default implementation and since a `LogHandler` is already expected to handle `Metadata`.
|
||||
|
||||
However, when using the default implementation, a potential metadata collision exists when an `Error` is passed via the new methods while the same keys (`"error.message"`, `"error.type"`) are present in metadata:
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong", error: error, metadata: ["error.message": "some other info"])
|
||||
```
|
||||
|
||||
We recommend that the `error` parameter takes precedence in such cases, with conflicting metadata values discarded. This aligns with the principle that explicit `error:` parameters represent primary data, while the same keys in metadata are likely incidental. In practice, we don't expect callers to deliberately pass conflicting error information.
|
||||
|
||||
Conversely, a `LogHandler` can implement the new protocol method, and still function with existing users of `Logger` - the `error` parameter will then always be `nil`.
|
||||
|
||||
### Future directions
|
||||
|
||||
#### recordError
|
||||
|
||||
If `swift-log` develops better support for scoped loggers, it might be possible to add a `recordError` method on `Logger`, that would attach the `Error` to all logs in that scope.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Standardized Error metadata via Logger convenience
|
||||
|
||||
The first proposed solution was to treat the new `Logger` methods as "convenience methods", that simply serialized the `Error` as metadata and did not pass the raw `Error` to `LogHandler`. The end result was similar to the currently proposed default implementation in `LogHandler`. In this solution, the metadata keys (`"error.message"` and `"error.type"`) were considered stable and part of the API, since that allowed for `LogHandler` implementations to re-map the keys (e.g. to `"err.*"`).
|
||||
|
||||
Ultimately, this was declined in favor of the current proposal. While the metadata based solution was simple, it lacked the flexibility that passing the raw `Error` allows for.
|
||||
|
||||
#### recordError convenience method
|
||||
|
||||
In the first iteration, we considered adding a new convenience method `recordError` on `Logger`, that would take an `Error`, serialize it, and add to the metadata on the `Logger`. This would primarily have been useful for when a `Logger` instance were passed down a call hierarchy and the `Error` metadata were relevant further down. However, it doesn't work well with the current proposal, since the serialization happens at a later stage.
|
||||
|
||||
#### Using .stringConvertible to pass Error to LogHandler
|
||||
|
||||
An alternative way to let the `LogHandler` get access to the raw `Error` would be to use the existing `.stringConvertible` enum case of `MetadataValue`. By putting the `Error` under a well-known metadata key (such as `"error"`), a `LogHandler` could get access to it, without any changes to the `LogHandler` protocol. However, this would only work for `Error`s that conform to `CustomStringConvertible`.
|
||||
|
||||
#### some Error vs any Error
|
||||
|
||||
The error argument in `Logger` was considered to be `some Error` rather than `any Error`. Ultimately, `any Error` was preferred. This is because in most typical use cases (e.g. general catch blocks), the error is an existential, so by using `some Error` we would get a slight performance penalty.
|
||||
@@ -0,0 +1,512 @@
|
||||
# SLG-0004: Metadata value attributes
|
||||
|
||||
Add an extensible per-value attribute mechanism for metadata.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0004
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Ready for Implementation**
|
||||
- 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)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
- [First iteration of the proposal](https://forums.swift.org/t/proposal-slg-0004-metadata-values-privacy-attribute/85249)
|
||||
|
||||
### Introduction
|
||||
|
||||
Introduce an extensible mechanism for attaching per-value attributes to metadata. The core `Logging` module provides
|
||||
the protocol and storage. Attribute packages define concrete attributes using the
|
||||
`Logger.MetadataValueAttributes.Attribute` protocol.
|
||||
|
||||
### Motivation
|
||||
|
||||
Metadata values in `swift-log` are opaque strings by the time the `LogHandler` receives them. The call site often
|
||||
knows things about a value that the handler cannot infer — for example, whether the value should be redacted in
|
||||
different environments.
|
||||
|
||||
Today, there is no way to express this. A single log statement can contain values that need different treatment, and
|
||||
log levels cannot help because they are per-statement, not per-value:
|
||||
|
||||
```swift
|
||||
logger.info("Login", metadata: [
|
||||
"action": "\(action)", // safe to log
|
||||
"user_email": "\(email)", // should be redacted in production, but nothing tells the handler
|
||||
])
|
||||
```
|
||||
|
||||
The workaround is handler-side key-based rules (`redact: ["email", "card-*", ...]`), but this is fragile:
|
||||
|
||||
- Rules break when libraries rename keys.
|
||||
- Rules require coordination across all dependencies.
|
||||
- The rule mapping is invisible at the call site.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Attributes are embedded directly in `MetadataValue` via the existing `.stringConvertible` case. A custom
|
||||
`MetadataValue.StringInterpolation` type produces attributed values when any interpolation segment specifies
|
||||
attributes. Libraries define attribute types conforming to `Logger.MetadataValueAttributes.Attribute` and provide
|
||||
ergonomic string interpolation overloads. Handlers read the attributes via `value.attributes` and act on them:
|
||||
|
||||
```swift
|
||||
import Logging
|
||||
|
||||
public enum Sensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
|
||||
case sensitive = 1
|
||||
case `public` = 2
|
||||
}
|
||||
|
||||
extension Logger.MetadataValue.StringInterpolation {
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
|
||||
_ value: T, sensitivity: Sensitivity
|
||||
) {
|
||||
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
|
||||
}
|
||||
}
|
||||
|
||||
logger.info("Request", metadata: [
|
||||
"method": "\(req.method)",
|
||||
"user_id": "\(req.userId, sensitivity: .sensitive)",
|
||||
])
|
||||
```
|
||||
|
||||
Handlers that support specific attributes read them from `value.attributes` and act accordingly. Handlers that do not
|
||||
understand attributes see plain `MetadataValue` instances — attributes are invisible unless explicitly inspected. The
|
||||
existing `metadata:` parameter is the only parameter needed; no new log method overloads are added.
|
||||
|
||||
Attributed values can also be created programmatically with the `.attributed` factory, which behaves like an additional
|
||||
enum case without breaking existing exhaustive switches:
|
||||
|
||||
```swift
|
||||
let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
|
||||
```
|
||||
|
||||
Intermediate handlers can read **and modify** attributes as metadata flows through a handler chain. The `attributes`
|
||||
property supports both getting and setting, enabling composable pipelines where each handler in the chain can enrich,
|
||||
transform, or strip attributes before forwarding:
|
||||
|
||||
```swift
|
||||
// An enriching handler that tags all metadata with a processing timestamp attribute
|
||||
func log(event: LogEvent) {
|
||||
var mutatedEvent = event
|
||||
if var eventMetadata = event.metadata {
|
||||
for (key, _) in eventMetadata {
|
||||
var attrs = eventMetadata[key]!.attributes
|
||||
attrs[ProcessingStage.self] = .enriched
|
||||
eventMetadata[key]?.attributes = attrs
|
||||
}
|
||||
mutatedEvent.metadata = eventMetadata
|
||||
}
|
||||
self.inner.log(event: mutatedEvent)
|
||||
}
|
||||
```
|
||||
|
||||
Attributes are **classifications, not enforcement**. An attribute does not guarantee any particular handler behavior —
|
||||
the handler may not support it. Applications needing guaranteed behavior must enforce it at a different abstraction.
|
||||
|
||||
The attribute mechanism is extensible: packages define their own attribute types using
|
||||
`Logger.MetadataValueAttributes.Attribute`. A
|
||||
chained `LogHandler` can read the attributes it cares about, act on them, and forward the rest to the next handler in
|
||||
the chain — enabling composable handler pipelines (e.g., redaction handler -> metrics-extraction handler -> output
|
||||
handler). Common attributes should be defined in separate packages so that the core `Logging` module remains free of
|
||||
domain-specific attributes while providing shared vocabulary across libraries. To improve discoverability, `swift-log`
|
||||
can reference attribute packages that are common across the whole ecosystem.
|
||||
|
||||
### Detailed design
|
||||
|
||||
#### `Attribute` protocol
|
||||
|
||||
```swift
|
||||
extension Logger.MetadataValueAttributes {
|
||||
/// A protocol for defining custom metadata attributes.
|
||||
///
|
||||
/// Conform to this protocol to define a custom attribute that can be stored in
|
||||
/// ``MetadataValueAttributes``. Each conforming type acts as both the key (identified
|
||||
/// by its metatype) and the value.
|
||||
///
|
||||
/// This protocol is designed for **small, fixed-vocabulary attributes**.
|
||||
/// Each attribute value is stored as an `Int64` raw value, so attributes occupy minimal
|
||||
/// space (one inline slot without heap allocation for the common single-attribute case).
|
||||
///
|
||||
/// ## Examples
|
||||
///
|
||||
/// ```swift
|
||||
/// public enum Priority: Int64, Sendable, Logger.MetadataValueAttributes.Attribute {
|
||||
/// case low = 1
|
||||
/// case high = 2
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// ```swift
|
||||
/// public struct Priority: Sendable, Hashable, Logger.MetadataValueAttributes.Attribute {
|
||||
/// public let rawValue: Int64
|
||||
/// public init(rawValue: Int64) {
|
||||
/// self.rawValue = rawValue
|
||||
/// }
|
||||
/// public static let low = Priority(rawValue: 1)
|
||||
/// public static let high = Priority(rawValue: 2)
|
||||
/// }
|
||||
/// ```
|
||||
public protocol Attribute: Sendable,
|
||||
RawRepresentable where RawValue == Int64 {}
|
||||
}
|
||||
```
|
||||
|
||||
Each conforming type serves as both the key and the value for an attribute. The metatype (`Key.Type`) identifies
|
||||
the attribute at runtime — no coordination between packages is needed.
|
||||
|
||||
#### `MetadataValueAttributes`
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
/// Attributes that can be associated with metadata values.
|
||||
public struct MetadataValueAttributes: Sendable, Equatable, ExpressibleByArrayLiteral {
|
||||
/// Nested ``Attribute`` protocol (see above).
|
||||
public protocol Attribute: Sendable, RawRepresentable where RawValue == Int64 {}
|
||||
|
||||
/// Create empty metadata value attributes.
|
||||
public init()
|
||||
|
||||
/// Create metadata value attributes from an array literal of attribute values.
|
||||
///
|
||||
/// ```swift
|
||||
/// let attrs: MetadataValueAttributes = [Sensitivity.sensitive, ValueType.int64]
|
||||
/// ```
|
||||
public init(arrayLiteral elements: any Attribute...)
|
||||
|
||||
/// Get or set a custom attribute by its type.
|
||||
///
|
||||
/// - Parameter attribute: The metatype of the attribute to access.
|
||||
/// - Returns: The attribute value, or `nil` if not set.
|
||||
public subscript<Attr: Attribute>(attribute: Attr.Type) -> Attr? { get set }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The common case (0–1 attributes) avoids heap allocation. `Equatable` compares entries as an unordered set (O(n²),
|
||||
n typically 0–2).
|
||||
|
||||
#### `MetadataValue.attributes` computed property
|
||||
|
||||
```swift
|
||||
extension Logger.MetadataValue {
|
||||
/// The attributes associated with this metadata value, if any.
|
||||
///
|
||||
/// **Getting:** When the value is a ``stringConvertible(_:)`` wrapping an attributed carrier,
|
||||
/// returns that carrier's attributes. For all other cases returns empty attributes.
|
||||
///
|
||||
/// **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.
|
||||
public var attributes: Logger.MetadataValueAttributes { get set }
|
||||
}
|
||||
```
|
||||
|
||||
This is the handler-side read/write API. Internally, the `Logging` module stores attributes in an internal
|
||||
`AttributedStringCarrier` class wrapped by `.stringConvertible`. The getter check is a concrete type comparison — no
|
||||
protocol conformance lookup. Users attach attributes via string interpolation and read them via this property. The
|
||||
setter allows handlers to modify or add attributes as they process metadata values through the handler chain.
|
||||
|
||||
#### `MetadataValue.attributed` factory method
|
||||
|
||||
```swift
|
||||
extension Logger.MetadataValue {
|
||||
/// Creates an attributed metadata value from a string-convertible value and attributes.
|
||||
public static func attributed(
|
||||
_ value: some CustomStringConvertible & Sendable,
|
||||
attributes: Logger.MetadataValueAttributes
|
||||
) -> Self
|
||||
}
|
||||
```
|
||||
|
||||
This convenience factory behaves like an additional enum case, producing a
|
||||
`.stringConvertible(AttributedStringCarrier(...))` value without requiring string interpolation:
|
||||
|
||||
```swift
|
||||
let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
|
||||
```
|
||||
|
||||
#### String interpolation
|
||||
|
||||
`MetadataValue` replaces its empty `ExpressibleByStringInterpolation` conformance with a custom `StringInterpolation`
|
||||
type. When no attributes are specified, the result is `.string(...)` — identical to the previous behavior. When any
|
||||
interpolation segment specifies attributes, the result is `.stringConvertible(...)` wrapping the internal carrier:
|
||||
```swift
|
||||
extension Logger.MetadataValue: ExpressibleByStringInterpolation {
|
||||
/// Custom string interpolation that optionally captures metadata attributes.
|
||||
///
|
||||
/// When no attributes are specified, produces `.string(...)` — identical to the
|
||||
/// default `DefaultStringInterpolation` behavior. When any interpolation segment
|
||||
/// specifies attributes (via the `attributes:` parameter), the result is
|
||||
/// `.stringConvertible(AttributedStringCarrier(...))` carrying both the string
|
||||
/// and the accumulated attributes.
|
||||
///
|
||||
/// Attribute packages (like `LoggingAttributes`) can add overloads with
|
||||
/// domain-specific parameters (e.g. `sensitivity:`) that call through to
|
||||
/// `appendInterpolation(_:attributes:)`.
|
||||
public struct StringInterpolation: StringInterpolationProtocol, Sendable {
|
||||
public init(literalCapacity: Int, interpolationCount: Int)
|
||||
public mutating func appendLiteral(_ literal: String)
|
||||
|
||||
/// Interpolation with a custom attributes closure.
|
||||
///
|
||||
/// When called, the result will be `.stringConvertible(AttributedStringCarrier(...))`
|
||||
/// instead of `.string(...)`.
|
||||
///
|
||||
/// ```swift
|
||||
/// "\(userId, attributes: { $0[MyAttribute.self] = .flagged })"
|
||||
/// ```
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T,
|
||||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||||
) where T: CustomStringConvertible & Sendable
|
||||
|
||||
/// Plain interpolation without attributes.
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T
|
||||
) where T: CustomStringConvertible & Sendable
|
||||
|
||||
/// Fallback interpolation for types that are not `CustomStringConvertible`.
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T
|
||||
) where T: Sendable
|
||||
|
||||
/// Unconstrained fallback for non-`Sendable` types.
|
||||
///
|
||||
/// The value is immediately converted to `String` via `String(describing:)` and never
|
||||
/// stored, so no `Sendable` safety issue arises. This overload exists so that interpolating
|
||||
/// a non-`Sendable` type into a `MetadataValue` continues to compile, matching the behavior
|
||||
/// of `DefaultStringInterpolation`.
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T
|
||||
)
|
||||
}
|
||||
|
||||
/// Creates a metadata value from string interpolation.
|
||||
///
|
||||
/// If any interpolation segment specified attributes, the result is
|
||||
/// `.stringConvertible(AttributedStringCarrier(...))`. Otherwise, `.string(...)`.
|
||||
public init(stringInterpolation: StringInterpolation)
|
||||
}
|
||||
```
|
||||
|
||||
Attribute packages add ergonomic overloads that wrap the closure-based method — for example:
|
||||
|
||||
```swift
|
||||
extension Logger.MetadataValue.StringInterpolation {
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
|
||||
_ value: T, sensitivity: Sensitivity
|
||||
) {
|
||||
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This enables the clean call-site syntax: `"\(userId, sensitivity: .sensitive)"`.
|
||||
|
||||
When a single `MetadataValue` contains multiple interpolated segments with different attributes, the merging behavior
|
||||
is defined by each attribute's `appendInterpolation` implementation.
|
||||
|
||||
#### No changes to `Logger`, `LogHandler`, `LogEvent`, or `MetadataProvider`
|
||||
|
||||
Unlike earlier iterations of this proposal, the piggyback approach requires **no new API** on `Logger`, `LogHandler`,
|
||||
`LogEvent`, or `MetadataProvider`:
|
||||
|
||||
- **`Logger`**: No new `attributedMetadata:` log method overloads. Attributes flow through the existing `metadata:`
|
||||
parameter.
|
||||
- **`LogHandler`**: No new protocol requirements. No `attributedMetadata` property, no `attributedMetadataKey`
|
||||
subscript. Existing handlers work unchanged.
|
||||
- **`LogEvent`**: No dual storage. `metadata` remains a simple `Logger.Metadata?` stored property. Values inside the
|
||||
dictionary may carry attributes, but `LogEvent` is unaware of this.
|
||||
- **`MetadataProvider`**: No `.attributed()` factory or `getAttributedMetadata()` method. Providers return
|
||||
`Logger.Metadata` where values may carry attributes via string interpolation.
|
||||
|
||||
### API stability
|
||||
|
||||
- **Existing `Logger` users.** No changes to existing API. The same `metadata:` parameter carries attributed values.
|
||||
- **Existing `LogHandler` implementations.** No protocol changes. Handlers that only call `.description` on metadata
|
||||
values see the string as before — attributes are invisible. Handlers that want to inspect attributes read
|
||||
`value.attributes`.
|
||||
|
||||
### Future directions
|
||||
|
||||
- **Attribute-aware equality.** The current `MetadataValue` equality for `.stringConvertible` values compares only
|
||||
`.description`, ignoring attributes. Two values with the same text but different attributes compare as equal. A
|
||||
future proposal could refine equality to include attributes when both sides carry them, but this
|
||||
requires careful consideration of backward compatibility since existing code may rely on description-only equality.
|
||||
- **Metadata values sensitivity attribute.** A separate ecosystem package could add the sensitivity attribute,
|
||||
allowing compatible `LogHandler` to redact values in certain situations.
|
||||
- **Typed metadata values.** A separate ecosystem package could add typed variants to `MetadataValue` (`.int64`,
|
||||
`.double`, `.bool`), reducing the need for attributes that compensate for stringly-typed metadata.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Wrapper type with parallel API ("attributed metadata value" approach)
|
||||
|
||||
Introduce an `AttributedMetadataValue` struct wrapping `MetadataValue` + `MetadataValueAttributes`, a separate
|
||||
`AttributedMetadata` typealias, new `attributedMetadata:` overloads on all Logger methods, dual storage in
|
||||
`LogEvent`, and new `LogHandler` protocol requirements. This was the design in the first iteration of this proposal.
|
||||
|
||||
It provides strong type separation but creates a parallel API surface: 7 new convenience methods, new protocol
|
||||
requirements with default implementations, dual `MetadataStorage` enum in `LogEvent`, and `mapValues` bridging
|
||||
between plain and attributed representations. The piggyback approach achieves the same functionality by embedding
|
||||
attributes inside `MetadataValue` via the existing `.stringConvertible` case, avoiding the parallel universe
|
||||
entirely.
|
||||
|
||||
#### Sidecar dictionary on `LogEvent`
|
||||
|
||||
Store attributes in a separate `[String: MetadataValueAttributes]` dictionary on `LogEvent`, keyed by the same
|
||||
metadata keys. This keeps `MetadataValue` unchanged but introduces sync issues — attributes can drift out of sync
|
||||
with metadata keys when handlers merge or transform metadata. The piggyback approach avoids this by co-locating
|
||||
attributes with the value they describe.
|
||||
|
||||
#### New enum case on `MetadataValue`
|
||||
|
||||
Add a dedicated `.attributed(String, MetadataValueAttributes)` case to the `MetadataValue` enum. This would make
|
||||
attributes statically visible in the type — no runtime downcast needed, and `switch` statements would handle
|
||||
attributed values explicitly. However, `MetadataValue` is a public enum that is exhaustively matched by every
|
||||
`LogHandler` in the ecosystem. Adding a case is source-breaking: every existing handler's `switch` over
|
||||
`MetadataValue` would fail to compile until updated. The piggyback approach avoids this by reusing the existing
|
||||
`.stringConvertible` case, which handlers already handle.
|
||||
|
||||
#### Concrete stored property instead of extensible mechanism
|
||||
|
||||
Add concrete stored properties (e.g., `var sensitivity: Sensitivity?`) on `MetadataValueAttributes`. Simpler, but
|
||||
closed — chained handlers cannot define their own attributes. The extensible mechanism keeps the core `Logging` module
|
||||
free of domain-specific attributes.
|
||||
|
||||
#### Bitmask storage
|
||||
|
||||
Pack attribute values into an inline `UInt64` using declared bit offsets. O(1) access, but requires authors to
|
||||
coordinate bit layout and risks collisions between independent packages.
|
||||
|
||||
#### Pure dynamic array storage
|
||||
|
||||
Use a dynamic array for all attributes with no inline slot. Simpler, but requires heap allocation even for the first
|
||||
attribute.
|
||||
|
||||
#### No per-value attributes
|
||||
|
||||
Rely on handler-side configuration (key-name-based rules). Simpler, but fragile — rules break when keys are renamed,
|
||||
require coordination across all dependencies, and are invisible at the call site.
|
||||
|
||||
### Example attributes
|
||||
|
||||
The following examples illustrate how ecosystem packages could define attributes using the
|
||||
`Logger.MetadataValueAttributes.Attribute` protocol. These are not part of this proposal.
|
||||
|
||||
#### Sensitivity
|
||||
|
||||
A sensitivity attribute for marking metadata values that contain private or personally identifiable information:
|
||||
|
||||
```swift
|
||||
public enum Sensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
|
||||
case sensitive = 1
|
||||
case `public` = 2
|
||||
}
|
||||
|
||||
extension Logger.MetadataValue.StringInterpolation {
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
|
||||
_ value: T, sensitivity: Sensitivity
|
||||
) {
|
||||
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
|
||||
}
|
||||
}
|
||||
|
||||
logger.info("Request", metadata: [
|
||||
"method": "\(req.method)",
|
||||
"user_id": "\(req.userId, sensitivity: .sensitive)",
|
||||
])
|
||||
```
|
||||
|
||||
A handler reads the attribute:
|
||||
|
||||
```swift
|
||||
for (key, value) in mergedMetadata {
|
||||
if value.attributes[Sensitivity.self] == .sensitive {
|
||||
// redact this value
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Value type hint
|
||||
|
||||
A type hint for structured logging backends that benefit from native types:
|
||||
|
||||
```swift
|
||||
public enum ValueType: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
|
||||
case string = 1
|
||||
case int64 = 2
|
||||
case double = 3
|
||||
case bool = 4
|
||||
}
|
||||
|
||||
extension Logger.MetadataValue.StringInterpolation {
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
|
||||
_ value: T, valueType: ValueType
|
||||
) {
|
||||
self.appendInterpolation(value, attributes: { $0[ValueType.self] = valueType })
|
||||
}
|
||||
}
|
||||
|
||||
logger.info("Metrics", metadata: [
|
||||
"latency_ms": "\(latency, valueType: .double)",
|
||||
"retry_count": "\(retries, valueType: .int64)",
|
||||
])
|
||||
```
|
||||
|
||||
#### Metric extraction
|
||||
|
||||
A metric attribute for a chained `LogHandler` that dual-writes to swift-metrics:
|
||||
|
||||
```swift
|
||||
public enum MetricKind: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
|
||||
case counter = 1
|
||||
case gauge = 2
|
||||
case histogram = 3
|
||||
}
|
||||
|
||||
extension Logger.MetadataValue.StringInterpolation {
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
|
||||
_ value: T, metricKind: MetricKind
|
||||
) {
|
||||
self.appendInterpolation(value, attributes: { $0[MetricKind.self] = metricKind })
|
||||
}
|
||||
}
|
||||
|
||||
logger.info("Request completed", metadata: [
|
||||
"duration_ms": "\(duration, metricKind: .histogram)",
|
||||
"error_count": "\(errors, metricKind: .counter)",
|
||||
])
|
||||
```
|
||||
|
||||
#### Attribute-enriching intermediate handler
|
||||
|
||||
An intermediate `LogHandler` that reads and modifies attributes before forwarding to the next handler in the chain.
|
||||
This pattern enables composable pipelines — for example, a handler that adds a default sensitivity to all metadata
|
||||
values that do not already carry one:
|
||||
|
||||
```swift
|
||||
struct DefaultSensitivityHandler: LogHandler {
|
||||
private var inner: any LogHandler
|
||||
|
||||
// ... logLevel, metadata, metadataProvider forwarded to inner ...
|
||||
|
||||
func log(event: LogEvent) {
|
||||
var mutatedEvent = event
|
||||
if var eventMetadata = event.metadata {
|
||||
for (key, _) in eventMetadata {
|
||||
if eventMetadata[key]?.attributes[Sensitivity.self] == nil {
|
||||
eventMetadata[key]?.attributes = [Sensitivity.sensitive]
|
||||
}
|
||||
}
|
||||
mutatedEvent.metadata = eventMetadata
|
||||
}
|
||||
self.inner.log(event: mutatedEvent)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With this handler in the chain, any metadata value without an explicit sensitivity annotation is treated as sensitive
|
||||
by default — a "deny by default" policy that individual call sites can override with `.public`.
|
||||
@@ -0,0 +1,180 @@
|
||||
# SLG-0005: `LogEvent`-based `LogHandler` API
|
||||
|
||||
Replace the flat-parameter `log(level:message:metadata:source:file:function:line:)` method on `LogHandler` with
|
||||
`log(event: LogEvent)`, enabling forward-compatible evolution of the `LogHandler` interface without breaking existing
|
||||
handler implementations.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0005
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#421](https://github.com/apple/swift-log/issues/421)
|
||||
- Implementation:
|
||||
- [apple/swift-log#423](https://github.com/apple/swift-log/pull/423)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
- [SLG-0003: Standardized Error Metadata via Logger Convenience](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/SLG-0003.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
Introduce `LogEvent` that bundles all log-statement data, and replace the flat-parameter
|
||||
`log(level:message:metadata:source:file:function:line:)` method on `LogHandler` with `log(event: LogEvent)`.
|
||||
|
||||
### Motivation
|
||||
|
||||
The `LogHandler` protocol currently requires implementing a single method with seven parameters:
|
||||
|
||||
```swift
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
```
|
||||
|
||||
Every time a new piece of data needs to be forwarded from a log call site to the handler — an error, or a richer metadata type — the only options are:
|
||||
|
||||
- **Add a new parameter to the existing method.** This is a source-breaking change: every existing `LogHandler`
|
||||
implementation across the entire Swift ecosystem must be updated simultaneously.
|
||||
- **Add a new `Logger` overload.** This requires 2 parallel APIs to coexist until the old one can be safely deprecated.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Introduce `LogEvent`, a `struct` that carries all the data associated with a single log statement. `LogEvent` is
|
||||
a handler-side type: it is constructed by `Logger._log` and passed to `LogHandler`. The public `Logger` call-site
|
||||
API — `logger.info(...)`, `logger.log(level:...)` and so on — is unchanged.
|
||||
|
||||
The `LogHandler` protocol gains a new required method `log(event: LogEvent)`, while the old flat-parameter method
|
||||
is deprecated.
|
||||
|
||||
For existing handlers, a default implementation of `log(event:)` forwards to the old method, so no code changes
|
||||
are required to keep existing implementations working. Handlers that want to take advantage of new fields added to
|
||||
`LogEvent` in future proposals implement `log(event:)`.
|
||||
|
||||
### Detailed design
|
||||
|
||||
#### New `LogEvent` type
|
||||
|
||||
A new top-level `struct` in the `Logging` module:
|
||||
|
||||
```swift
|
||||
public struct LogEvent: Sendable {
|
||||
public var level: Logger.Level
|
||||
public var message: Logger.Message
|
||||
private var _metadata: Logger.Metadata?
|
||||
public var metadata: Logger.Metadata? {
|
||||
get { self._metadata }
|
||||
set { self._metadata = newValue }
|
||||
}
|
||||
public var source: String
|
||||
public var file: String
|
||||
public var function: String
|
||||
public var line: UInt
|
||||
|
||||
public init(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Updated `LogHandler` protocol
|
||||
|
||||
```swift
|
||||
public protocol LogHandler: _SwiftLogSendableLogHandler {
|
||||
|
||||
/// The library calls this method when a log handler must emit a log message.
|
||||
///
|
||||
/// There is no need for the `LogHandler` to check if the level is above or below the configured `logLevel`
|
||||
/// as `Logger` already performed this check and determined that a message should be logged.
|
||||
///
|
||||
/// - Parameter event: The log event containing the level, message, metadata, and source location.
|
||||
func log(event: LogEvent)
|
||||
|
||||
/// Please do _not_ implement this method when you create a `LogHandler` implementation.
|
||||
/// Implement ``log(event:)`` instead.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Default implementation
|
||||
|
||||
The default for `log(event:)` forwards all event fields to the old flat-parameter method,
|
||||
preserving the behavior of existing handlers with no source changes required.
|
||||
|
||||
The default implementation is marked as deprecated to encourage handler authors to migrate to `log(event:)`.
|
||||
Handlers that still rely on the forwarding bridge will see a deprecation warning at compile time, signaling that
|
||||
they should adopt the new method directly.
|
||||
|
||||
```swift
|
||||
extension LogHandler {
|
||||
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
|
||||
public func log(event: LogEvent) {
|
||||
self.log(
|
||||
level: event.level,
|
||||
message: event.message,
|
||||
metadata: event.metadata,
|
||||
source: event.source,
|
||||
file: event.file,
|
||||
function: event.function,
|
||||
line: event.line
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### API stability
|
||||
|
||||
**For existing `Logger` users:** No changes. All existing call sites continue to compile and behave identically.
|
||||
|
||||
**For existing `LogHandler` implementations:** Implementations of
|
||||
`log(level:message:metadata:source:file:function:line:)` continue to work without any source changes. The
|
||||
default implementation of `log(event:)` forwards to the old method.
|
||||
|
||||
### Future directions
|
||||
|
||||
Future proposals can add new fields to `LogEvent` with sensible defaults — a richer metadata
|
||||
type, or an attached `Error` (as a follow-up for [SLG-0003 proposal](https://forums.swift.org/t/proposal-slg-0003-standardized-error-metadata-via-logger-convenience/84518/39)) —
|
||||
without touching the `LogHandler` protocol and without requiring any changes to
|
||||
existing handler implementations. This is the primary motivation for this proposal.
|
||||
|
||||
The [SLG-0004 proposal](https://github.com/apple/swift-log/pull/416) introduces an `AttributedMetadata` type that wraps
|
||||
`Logger.Metadata` with additional context. Adding it to `LogEvent` as a new optional field would be
|
||||
source-compatible, and the existing `metadata` field could become a computed property that projects from
|
||||
`attributedMetadata` when present, keeping old handlers fully functional without modification.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Adding parameters with default values to the existing method
|
||||
|
||||
Adding new parameters with default values avoids introducing a new method, but still constitutes a
|
||||
source-breaking change: every existing `LogHandler` implementation that implements the method explicitly
|
||||
must add the new parameter. The whole point of this proposal is to avoid that pattern indefinitely.
|
||||
@@ -0,0 +1,49 @@
|
||||
# SLG-NNNN: Feature name
|
||||
|
||||
Feature abstract – a one sentence summary.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-NNNN
|
||||
- Author(s): [Author 1](https://github.com/swiftdev), [Author 2](https://github.com/swiftdev)
|
||||
- Status: **Awaiting Review**
|
||||
- Issue: [apple/swift-log#1](https://github.com/apple/swift-log/issues/1)
|
||||
- Implementation:
|
||||
- [apple/swift-log#1](https://github.com/apple/swift-log/pull/1)
|
||||
- Feature flag: `proposalNNNN`
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
A short, one-sentence overview of the feature or change.
|
||||
|
||||
### Motivation
|
||||
|
||||
Describe the problems that this proposal aims to address, and what workarounds adopters have to employ currently, if any.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds.
|
||||
|
||||
This section should focus on what will change for the _adopters_ of SwiftLog.
|
||||
|
||||
### Detailed design
|
||||
|
||||
Describe the implementation of the feature, a link to a prototype implementation is encouraged here.
|
||||
|
||||
This section should focus on what will change for the _contributors_ to SwiftLog.
|
||||
|
||||
### API stability
|
||||
|
||||
Discuss the API implications, making sure to considering all of:
|
||||
- existing ``Logger`` users,
|
||||
- existing ``LogHandler`` implementations.
|
||||
|
||||
### Future directions
|
||||
|
||||
Discuss any potential future improvements to the feature.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
Discuss the alternative solutions considered, even during the review process itself.
|
||||
@@ -0,0 +1,19 @@
|
||||
# ``Logging/LogEvent``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a log event
|
||||
|
||||
- ``init(level:message:metadata:source:file:function:line:)``
|
||||
- ``init(level:message:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Inspecting a log event
|
||||
|
||||
- ``level``
|
||||
- ``message``
|
||||
- ``error``
|
||||
- ``metadata``
|
||||
- ``source``
|
||||
- ``file``
|
||||
- ``function``
|
||||
- ``line``
|
||||
@@ -0,0 +1,22 @@
|
||||
# ``Logging/LogHandler``
|
||||
|
||||
## Topics
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)-7x67``
|
||||
- ``log(event:)-17f2r``
|
||||
- ``log(level:message:metadata:source:file:function:line:)-8kgt7``
|
||||
- ``log(level:message:metadata:source:file:function:line:)-69pez``
|
||||
- ``log(level:message:metadata:file:function:line:)-89rya``
|
||||
- ``log(level:message:metadata:file:function:line:)-1xdau``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,13 @@
|
||||
# ``Logging/Logger/Level``
|
||||
|
||||
## Topics
|
||||
|
||||
### Log Levels
|
||||
|
||||
- ``trace``
|
||||
- ``debug``
|
||||
- ``info``
|
||||
- ``notice``
|
||||
- ``warning``
|
||||
- ``error``
|
||||
- ``critical``
|
||||
@@ -0,0 +1,12 @@
|
||||
# ``Logging/Logger/Message``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a log message
|
||||
|
||||
- ``init(stringLiteral:)``
|
||||
|
||||
### Inspecting a log message
|
||||
|
||||
- ``description``
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# ``Logging/Logger/MetadataProvider``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a metadata provider
|
||||
|
||||
- ``init(_:)-(()->Logger.Metadata)``
|
||||
|
||||
### Invoking the provider
|
||||
|
||||
- ``get()``
|
||||
|
||||
### Merging metadata
|
||||
|
||||
- ``multiplex(_:)``
|
||||
@@ -0,0 +1,11 @@
|
||||
# ``Logging/Logger/MetadataValue``
|
||||
|
||||
## Topics
|
||||
|
||||
### Types of metadata values
|
||||
|
||||
- ``string(_:)``
|
||||
- ``stringConvertible(_:)``
|
||||
- ``array(_:)``
|
||||
- ``dictionary(_:)``
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# ``Logging/Logger``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating Loggers
|
||||
|
||||
- ``init(label:)``
|
||||
- ``init(label:metadataProvider:)``
|
||||
- ``init(label:factory:)-9uiy2``
|
||||
- ``init(label:factory:)-6iktu``
|
||||
- ``MetadataProvider``
|
||||
|
||||
### Sending trace log messages
|
||||
|
||||
- ``trace(_:metadata:file:function:line:)``
|
||||
- ``trace(_:metadata:source:file:function:line:)``
|
||||
- ``trace(_:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending debug log messages
|
||||
|
||||
- ``debug(_:metadata:file:function:line:)``
|
||||
- ``debug(_:metadata:source:file:function:line:)``
|
||||
- ``debug(_:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending info log messages
|
||||
|
||||
- ``info(_:metadata:file:function:line:)``
|
||||
- ``info(_:metadata:source:file:function:line:)``
|
||||
- ``info(_:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending notice log messages
|
||||
|
||||
- ``notice(_:metadata:file:function:line:)``
|
||||
- ``notice(_:metadata:source:file:function:line:)``
|
||||
- ``notice(_:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending warning log messages
|
||||
|
||||
- ``warning(_:metadata:file:function:line:)``
|
||||
- ``warning(_:metadata:source:file:function:line:)``
|
||||
- ``warning(_:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending error log messages
|
||||
|
||||
- ``error(_:metadata:file:function:line:)``
|
||||
- ``error(_:metadata:source:file:function:line:)``
|
||||
- ``error(_:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending critical log messages
|
||||
|
||||
- ``critical(_:metadata:file:function:line:)``
|
||||
- ``critical(_:metadata:source:file:function:line:)``
|
||||
- ``critical(_:error:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending general log messages
|
||||
|
||||
- ``log(level:_:metadata:file:function:line:)``
|
||||
- ``log(level:_:metadata:source:file:function:line:)``
|
||||
- ``log(level:_:error:metadata:source:file:function:line:)``
|
||||
- ``Level``
|
||||
- ``Message``
|
||||
- ``Metadata``
|
||||
|
||||
### Adjusting logger metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
- ``MetadataValue``
|
||||
|
||||
### Metadata attribute types
|
||||
|
||||
- ``MetadataValueAttributes``
|
||||
|
||||
### Inspecting a logger
|
||||
|
||||
- ``label``
|
||||
- ``logLevel``
|
||||
- ``handler``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,13 @@
|
||||
# ``Logging/LoggingSystem``
|
||||
|
||||
## Topics
|
||||
|
||||
### Initializing the logging system
|
||||
|
||||
- ``bootstrap(_:)``
|
||||
- ``bootstrap(_:metadataProvider:)``
|
||||
|
||||
### Inspecting the logging system
|
||||
|
||||
- ``metadataProvider``
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# ``Logging/MultiplexLogHandler``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a multiplex log handler
|
||||
|
||||
- ``init(_:)``
|
||||
- ``init(_:metadataProvider:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)``
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,25 @@
|
||||
# ``Logging/StreamLogHandler``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a stream log handler
|
||||
|
||||
- ``standardOutput(label:)``
|
||||
- ``standardOutput(label:metadataProvider:)``
|
||||
- ``standardError(label:)``
|
||||
- ``standardError(label:metadataProvider:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)``
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,26 @@
|
||||
# ``Logging/SwiftLogNoOpLogHandler``
|
||||
|
||||
A log handler that silently discards all log messages.
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a Swift Log no-op log handler
|
||||
|
||||
- ``init()``
|
||||
- ``init(_:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)``
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
- ``log(level:message:metadata:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,86 @@
|
||||
# Understanding Loggers and Log Handlers
|
||||
|
||||
Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages.
|
||||
|
||||
## Overview
|
||||
|
||||
Create or retrieve a logger to get an instance for logging messages.
|
||||
Log messages have a level that you use to indicate the message's importance.
|
||||
|
||||
SwiftLog defines seven log levels, represented by ``Logger/Level``, ordered from least to
|
||||
most severe:
|
||||
|
||||
- ``Logger/Level/trace``
|
||||
- ``Logger/Level/debug``
|
||||
- ``Logger/Level/info``
|
||||
- ``Logger/Level/notice``
|
||||
- ``Logger/Level/warning``
|
||||
- ``Logger/Level/error``
|
||||
- ``Logger/Level/critical``
|
||||
|
||||
Once a message is sent to a logger, a log handler processes it.
|
||||
The app using the logger configures the handler, usually for the environment in which that app runs, processing messages appropriate to that environment.
|
||||
If the app doesn't provide its own log handler, SwiftLog defaults to using a ``StreamLogHandler`` that outputs log messages to `STDOUT`.
|
||||
|
||||
### Loggers
|
||||
|
||||
Loggers are used to emit log messages at different severity levels:
|
||||
|
||||
```swift
|
||||
// Informational message
|
||||
logger.info("Processing request")
|
||||
|
||||
// Something went wrong
|
||||
logger.error("Houston, we have a problem")
|
||||
```
|
||||
|
||||
``Logger`` is a value type with value semantics, meaning that when you modify a
|
||||
logger's configuration (like its log level or metadata), it only affects that
|
||||
specific logger instance:
|
||||
|
||||
```swift
|
||||
let baseLogger = Logger(label: "MyApp")
|
||||
|
||||
// Create a new logger with different configuration.
|
||||
var requestLogger = baseLogger
|
||||
requestLogger.logLevel = .debug
|
||||
requestLogger[metadataKey: "request-id"] = "\(UUID())"
|
||||
|
||||
// baseLogger is unchanged. It still has default log level and no metadata
|
||||
// requestLogger has debug level and request-id metadata.
|
||||
```
|
||||
|
||||
This value type behavior makes loggers safe to pass between functions and modify
|
||||
without unexpected side effects.
|
||||
|
||||
### Log Levels
|
||||
|
||||
Log levels can be changed per logger without affecting others:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "MyLogger")
|
||||
logger.logLevel = .debug
|
||||
```
|
||||
|
||||
For guidance on what level to use for a message, see <doc:001-ChoosingLogLevels>.
|
||||
|
||||
### Logging Metadata
|
||||
|
||||
Metadata provides contextual information crucial for debugging:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "com.example.server")
|
||||
logger[metadataKey: "request.id"] = "\(UUID())"
|
||||
logger.info("Processing request")
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request
|
||||
```
|
||||
|
||||
### Source vs Label
|
||||
|
||||
A ``Logger`` has an immutable `label` that identifies its creator, while each log
|
||||
message carries a `source` parameter that identifies where the message originated.
|
||||
Use `source` for filtering messages from specific subsystems.
|
||||
@@ -17,10 +17,10 @@ This separation allows libraries to adopt the API while applications choose any
|
||||
compatible logging backend implementation without requiring changes from
|
||||
libraries.
|
||||
|
||||
## Getting Started
|
||||
### Getting Started
|
||||
|
||||
Use this If you are writing a cross-platform application (for example, Linux and
|
||||
macOS) or library, target this logging API.
|
||||
Use this package if you're writing a cross-platform application (for example, Linux and
|
||||
macOS) or library, and want to target this logging API.
|
||||
|
||||
### Adding the Dependency
|
||||
|
||||
@@ -56,7 +56,7 @@ logger.info("Hello World!")
|
||||
|
||||
This outputs:
|
||||
```
|
||||
2019-03-13T15:46:38+0000 info: Hello World!
|
||||
2025-10-24T17:26:47-0700 info MyLogger: [your_app] Hello World!
|
||||
```
|
||||
|
||||
### Default Behavior
|
||||
@@ -72,89 +72,19 @@ LoggingSystem.bootstrap(StreamLogHandler.standardError)
|
||||
implement the ``LogHandler`` protocol directly or use a community-maintained
|
||||
backend.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Loggers
|
||||
|
||||
Loggers are used to emit log messages at different severity levels:
|
||||
|
||||
```swift
|
||||
// Informational message
|
||||
logger.info("Processing request")
|
||||
|
||||
// Something went wrong
|
||||
logger.error("Houston, we have a problem")
|
||||
```
|
||||
|
||||
``Logger`` is a value type with value semantics, meaning that when you modify a
|
||||
logger's configuration (like its log level or metadata), it only affects that
|
||||
specific logger instance:
|
||||
|
||||
```swift
|
||||
let baseLogger = Logger(label: "MyApp")
|
||||
|
||||
// Create a new logger with different configuration.
|
||||
var requestLogger = baseLogger
|
||||
requestLogger.logLevel = .debug
|
||||
requestLogger[metadataKey: "request-id"] = "\(UUID())"
|
||||
|
||||
// baseLogger is unchanged. It still has default log level and no metadata
|
||||
// requestLogger has debug level and request-id metadata.
|
||||
```
|
||||
|
||||
This value type behavior makes loggers safe to pass between functions and modify
|
||||
without unexpected side effects.
|
||||
|
||||
### Log Levels
|
||||
|
||||
SwiftLog supports seven log levels (from least to most severe):
|
||||
- ``Logger/Level/trace``
|
||||
- ``Logger/Level/debug``
|
||||
- ``Logger/Level/info``
|
||||
- ``Logger/Level/notice``
|
||||
- ``Logger/Level/warning``
|
||||
- ``Logger/Level/error``
|
||||
- ``Logger/Level/critical``
|
||||
|
||||
Log levels can be changed per logger without affecting others:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "MyLogger")
|
||||
logger.logLevel = .debug
|
||||
```
|
||||
|
||||
### Logging Metadata
|
||||
|
||||
Metadata provides contextual information crucial for debugging:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "com.example.server")
|
||||
logger[metadataKey: "request-uuid"] = "\(UUID())"
|
||||
logger.info("Processing request")
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request
|
||||
```
|
||||
|
||||
### Source vs Label
|
||||
|
||||
A ``Logger`` has an immutable `label` identifying its creator, while each log
|
||||
message carries a `source` parameter identifying where the message originated.
|
||||
Use `source` for filtering messages from specific subsystems.
|
||||
|
||||
|
||||
## Topics
|
||||
|
||||
### Logging API
|
||||
|
||||
- <doc:UnderstandingLoggers>
|
||||
- ``Logger``
|
||||
- ``LoggingSystem``
|
||||
|
||||
### Log Handlers
|
||||
|
||||
- ``LogHandler``
|
||||
- ``LogEvent``
|
||||
- ``MultiplexLogHandler``
|
||||
- ``StreamLogHandler``
|
||||
- ``SwiftLogNoOpLogHandler``
|
||||
@@ -162,5 +92,9 @@ Use `source` for filtering messages from specific subsystems.
|
||||
### Best Practices
|
||||
|
||||
- <doc:LoggingBestPractices>
|
||||
- <doc:001-ChoosingLogLevels>
|
||||
- <doc:ImplementingALogHandler>
|
||||
- <doc:DisableLogLevelsDuringCompilation>
|
||||
|
||||
### Contributing
|
||||
|
||||
- <doc:Proposals>
|
||||
@@ -0,0 +1,227 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A pseudo log handler that sends messages to multiple other log handlers.
|
||||
///
|
||||
/// ### Effective Logger.Level
|
||||
///
|
||||
/// When first initialized, the multiplex log handlers' log level is automatically set to the minimum of all the
|
||||
/// provided log handlers.
|
||||
/// This ensures that each of the handlers are able to log at their appropriate level
|
||||
/// any log events they might be interested in.
|
||||
///
|
||||
/// Example:
|
||||
/// If log handler `A` is logging at `.debug` level, and log handler `B` is logging at `.info` level, the log level of the constructed
|
||||
/// `MultiplexLogHandler([A, B])` is set to `.debug`. This means that this handler will operate on debug messages,
|
||||
/// while only logged by the underlying `A` log handler (since `B`'s log level is `.info`
|
||||
/// and thus it would not actually log that log message).
|
||||
///
|
||||
/// If the log level is _set_ on a `Logger` backed by an `MultiplexLogHandler` the log level applies to *all*
|
||||
/// underlying log handlers, allowing a logger to still select at what level it wants to log regardless of if the underlying
|
||||
/// handler is a multiplex or a normal one. If for some reason one might want to not allow changing a log level of a specific
|
||||
/// handler passed into the multiplex log handler, this is possible by wrapping it in a handler which ignores any log level changes.
|
||||
///
|
||||
/// ### Effective Logger.Metadata
|
||||
///
|
||||
/// Since a `MultiplexLogHandler` is a combination of multiple log handlers, the handling of metadata can be non-obvious.
|
||||
/// For example, the underlying log handlers may have metadata of their own set before they are used to initialize the multiplex log handler.
|
||||
///
|
||||
/// The multiplex log handler acts purely as proxy and does not make any changes to underlying handler metadata other than
|
||||
/// proxying writes that users made on a `Logger` instance backed by this handler.
|
||||
///
|
||||
/// Setting metadata is always proxied through to _all_ underlying handlers, meaning that if a modification like
|
||||
/// `logger[metadataKey: "x"] = "y"` is made, all the underlying log handlers used to create the multiplex handler
|
||||
/// observe this change.
|
||||
///
|
||||
/// Reading metadata from the multiplex log handler MAY need to pick one of conflicting values if the underlying log handlers
|
||||
/// were previously initiated with metadata before passing them into the multiplex handler. The multiplex handler uses
|
||||
/// the order in which the handlers were passed in during its initialization as a priority indicator - the first handler's
|
||||
/// values are more important than the next handlers values, etc.
|
||||
///
|
||||
/// Example:
|
||||
/// If the multiplex log handler was initiated with two handlers like this: `MultiplexLogHandler([handler1, handler2])`.
|
||||
/// The handlers each have some already set metadata: `handler1` has metadata values for keys `one` and `all`, and `handler2`
|
||||
/// has values for keys `two` and `all`.
|
||||
///
|
||||
/// A query through the multiplex log handler the key `one` naturally returns `handler1`'s value, and a query for `two`
|
||||
/// naturally returns `handler2`'s value.
|
||||
/// Querying for the key `all` will return `handler1`'s value, as that handler has a high priority,
|
||||
/// as indicated by its earlier position in the initialization, than the second handler.
|
||||
/// The same rule applies when querying for the `metadata` property of the multiplex log handler; it constructs `Metadata` uniquing values.
|
||||
public struct MultiplexLogHandler: LogHandler {
|
||||
private var handlers: [any LogHandler]
|
||||
private var effectiveLogLevel: Logger.Level
|
||||
/// This metadata provider runs after all metadata providers of the multiplexed handlers.
|
||||
private var _metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
/// Create a multiplex log handler.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - handlers: An array of `LogHandler`s, each of which will receive the log messages sent to this `Logger`.
|
||||
/// The array must not be empty.
|
||||
public init(_ handlers: [any LogHandler]) {
|
||||
assert(!handlers.isEmpty, "MultiplexLogHandler.handlers MUST NOT be empty")
|
||||
self.handlers = handlers
|
||||
self.effectiveLogLevel = handlers.map { $0.logLevel }.min() ?? .trace
|
||||
}
|
||||
|
||||
/// Create a multiplex log handler with the metadata provider you provide.
|
||||
/// - Parameters:
|
||||
/// - handlers: An array of `LogHandler`s, each of which will receive every log message sent to this `Logger`.
|
||||
/// The array must not be empty.
|
||||
/// - metadataProvider: The metadata provider that adds metadata to log messages for this handler.
|
||||
public init(_ handlers: [any LogHandler], metadataProvider: Logger.MetadataProvider?) {
|
||||
assert(!handlers.isEmpty, "MultiplexLogHandler.handlers MUST NOT be empty")
|
||||
self.handlers = handlers
|
||||
self.effectiveLogLevel = handlers.map { $0.logLevel }.min() ?? .trace
|
||||
self._metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
/// Get or set the log level configured for this `Logger`.
|
||||
///
|
||||
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
|
||||
/// > It is acceptable for logging backends to have some form of global log level override
|
||||
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
|
||||
/// > certain cases have no effect.
|
||||
public var logLevel: Logger.Level {
|
||||
get {
|
||||
self.effectiveLogLevel
|
||||
}
|
||||
set {
|
||||
self.mutatingForEachHandler { $0.logLevel = newValue }
|
||||
self.effectiveLogLevel = newValue
|
||||
}
|
||||
}
|
||||
|
||||
/// The metadata provider.
|
||||
public var metadataProvider: Logger.MetadataProvider? {
|
||||
get {
|
||||
if self.handlers.count == 1 {
|
||||
if let innerHandler = self.handlers.first?.metadataProvider {
|
||||
if let multiplexHandlerProvider = self._metadataProvider {
|
||||
return .multiplex([innerHandler, multiplexHandlerProvider])
|
||||
} else {
|
||||
return innerHandler
|
||||
}
|
||||
} else if let multiplexHandlerProvider = self._metadataProvider {
|
||||
return multiplexHandlerProvider
|
||||
} else {
|
||||
return nil
|
||||
}
|
||||
} else {
|
||||
var providers: [Logger.MetadataProvider] = []
|
||||
let additionalMetadataProviderCount = (self._metadataProvider != nil ? 1 : 0)
|
||||
providers.reserveCapacity(self.handlers.count + additionalMetadataProviderCount)
|
||||
for handler in self.handlers {
|
||||
if let provider = handler.metadataProvider {
|
||||
providers.append(provider)
|
||||
}
|
||||
}
|
||||
if let multiplexHandlerProvider = self._metadataProvider {
|
||||
providers.append(multiplexHandlerProvider)
|
||||
}
|
||||
guard !providers.isEmpty else {
|
||||
return nil
|
||||
}
|
||||
return .multiplex(providers)
|
||||
}
|
||||
}
|
||||
set {
|
||||
self.mutatingForEachHandler { $0.metadataProvider = newValue }
|
||||
}
|
||||
}
|
||||
|
||||
/// Log a message using the log level and source that you provide.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - event: The log event containing the level, message, metadata, and source location.
|
||||
public func log(event: LogEvent) {
|
||||
for handler in self.handlers where handler.logLevel <= event.level {
|
||||
handler.log(event: event)
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
event: LogEvent(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
/// Get or set the entire metadata storage as a dictionary.
|
||||
public var metadata: Logger.Metadata {
|
||||
get {
|
||||
var effective: Logger.Metadata = [:]
|
||||
// as a rough estimate we assume that the underlying handlers have a similar metadata count,
|
||||
// and we use the first one's current count to estimate how big of a dictionary we need to allocate:
|
||||
|
||||
// !-safe, we always have at least one handler
|
||||
effective.reserveCapacity(self.handlers.first!.metadata.count)
|
||||
|
||||
for handler in self.handlers {
|
||||
effective.merge(handler.metadata, uniquingKeysWith: { _, handlerMetadata in handlerMetadata })
|
||||
if let provider = handler.metadataProvider {
|
||||
effective.merge(provider.get(), uniquingKeysWith: { _, provided in provided })
|
||||
}
|
||||
}
|
||||
if let provider = self._metadataProvider {
|
||||
effective.merge(provider.get(), uniquingKeysWith: { _, provided in provided })
|
||||
}
|
||||
|
||||
return effective
|
||||
}
|
||||
set {
|
||||
self.mutatingForEachHandler { $0.metadata = newValue }
|
||||
}
|
||||
}
|
||||
|
||||
/// Add, change, or remove a logging metadata item.
|
||||
///
|
||||
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
|
||||
public subscript(metadataKey metadataKey: Logger.Metadata.Key) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
for handler in self.handlers {
|
||||
if let value = handler[metadataKey: metadataKey] {
|
||||
return value
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
set {
|
||||
self.mutatingForEachHandler { $0[metadataKey: metadataKey] = newValue }
|
||||
}
|
||||
}
|
||||
|
||||
private mutating func mutatingForEachHandler(_ mutator: (inout any LogHandler) -> Void) {
|
||||
for index in self.handlers.indices {
|
||||
mutator(&self.handlers[index])
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,429 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif os(Windows)
|
||||
import CRT
|
||||
#elseif canImport(Glibc)
|
||||
@preconcurrency import Glibc
|
||||
#elseif canImport(Android)
|
||||
@preconcurrency import Android
|
||||
#elseif canImport(Musl)
|
||||
import Musl
|
||||
#elseif canImport(WASILibc)
|
||||
import WASILibc
|
||||
#else
|
||||
#error("Unsupported runtime")
|
||||
#endif
|
||||
|
||||
/// Stream log handler presents log messages to STDERR or STDOUT.
|
||||
///
|
||||
/// This is a simple implementation of `LogHandler` that directs
|
||||
/// `Logger` output to either `stderr` or `stdout` via the factory methods.
|
||||
///
|
||||
/// Metadata is merged in the following order:
|
||||
/// 1. Metadata set on the log handler itself is used as the base metadata.
|
||||
/// 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(
|
||||
label: label,
|
||||
stream: StdioOutputStream.stdout,
|
||||
metadataProvider: LoggingSystem.metadataProvider
|
||||
)
|
||||
}
|
||||
|
||||
/// Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide.
|
||||
public static func standardOutput(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler {
|
||||
StreamLogHandler(label: label, stream: StdioOutputStream.stdout, metadataProvider: metadataProvider)
|
||||
}
|
||||
|
||||
/// Creates a stream log handler that directs its output to STDERR.
|
||||
public static func standardError(label: String) -> StreamLogHandler {
|
||||
StreamLogHandler(
|
||||
label: label,
|
||||
stream: StdioOutputStream.stderr,
|
||||
metadataProvider: LoggingSystem.metadataProvider
|
||||
)
|
||||
}
|
||||
|
||||
/// Creates a stream log handler that directs its output to STDERR using the metadata provider you provide.
|
||||
public static func standardError(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler {
|
||||
StreamLogHandler(label: label, stream: StdioOutputStream.stderr, metadataProvider: metadataProvider)
|
||||
}
|
||||
|
||||
private let stream: any _SendableTextOutputStream
|
||||
private let label: String
|
||||
|
||||
/// Get the log level configured for this `Logger`.
|
||||
///
|
||||
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
|
||||
/// > It is acceptable for logging backends to have some form of global log level override
|
||||
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
|
||||
/// > certain cases have no effect.
|
||||
public var logLevel: Logger.Level = .info
|
||||
|
||||
/// The metadata provider.
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
private var prettyMetadata: String?
|
||||
/// Get or set the entire metadata storage as a dictionary.
|
||||
public var metadata = Logger.Metadata() {
|
||||
didSet {
|
||||
self.prettyMetadata = self.prettify(self.metadata)
|
||||
}
|
||||
}
|
||||
|
||||
/// Add, change, or remove a logging metadata item.
|
||||
///
|
||||
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
|
||||
public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self.metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
self.metadata[metadataKey] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
// internal for testing only
|
||||
internal init(label: String, stream: any _SendableTextOutputStream) {
|
||||
self.init(label: label, stream: stream, metadataProvider: LoggingSystem.metadataProvider)
|
||||
}
|
||||
|
||||
// internal for testing only
|
||||
internal init(label: String, stream: any _SendableTextOutputStream, metadataProvider: Logger.MetadataProvider?) {
|
||||
self.label = label
|
||||
self.stream = stream
|
||||
self.metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
/// Log a message using the log level and source that you provide.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - event: The log event containing the level, message, metadata, and source location.
|
||||
public func log(event: LogEvent) {
|
||||
let effectiveMetadata = StreamLogHandler.prepareMetadata(
|
||||
base: self.metadata,
|
||||
provider: self.metadataProvider,
|
||||
explicit: event.metadata,
|
||||
error: event.error,
|
||||
)
|
||||
|
||||
let prettyMetadata: String?
|
||||
if let effectiveMetadata = effectiveMetadata {
|
||||
prettyMetadata = self.prettify(effectiveMetadata)
|
||||
} else {
|
||||
prettyMetadata = self.prettyMetadata
|
||||
}
|
||||
|
||||
var stream = self.stream
|
||||
stream.write(
|
||||
"\(self.timestamp()) \(event.level)\(self.label.isEmpty ? "" : " ")\(self.label):\(prettyMetadata.map { " \($0)" } ?? "") [\(event.source)] \(event.message)\n"
|
||||
)
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
event: LogEvent(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
internal static func prepareMetadata(
|
||||
base: Logger.Metadata,
|
||||
provider: Logger.MetadataProvider?,
|
||||
explicit: Logger.Metadata?,
|
||||
error: (any Error)?,
|
||||
) -> Logger.Metadata? {
|
||||
var metadata = base
|
||||
|
||||
let provided = provider?.get() ?? [:]
|
||||
|
||||
guard !provided.isEmpty || !((explicit ?? [:]).isEmpty) || error != nil else {
|
||||
// all per-log-statement values are empty
|
||||
return nil
|
||||
}
|
||||
|
||||
if !provided.isEmpty {
|
||||
metadata.merge(provided, uniquingKeysWith: { _, provided in provided })
|
||||
}
|
||||
|
||||
if let explicit = explicit, !explicit.isEmpty {
|
||||
metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
|
||||
}
|
||||
|
||||
if let error {
|
||||
metadata["error.message"] = "\(error)"
|
||||
metadata["error.type"] = "\(String(reflecting: type(of: error)))"
|
||||
}
|
||||
|
||||
return metadata
|
||||
}
|
||||
|
||||
private func prettify(_ metadata: Logger.Metadata) -> String? {
|
||||
if metadata.isEmpty {
|
||||
return nil
|
||||
} else {
|
||||
return metadata.lazy.sorted(by: { $0.key < $1.key }).map { "\($0)=\($1)" }.joined(separator: " ")
|
||||
}
|
||||
}
|
||||
|
||||
private func timestamp() -> String {
|
||||
var buffer = [Int8](repeating: 0, count: 255)
|
||||
#if os(Windows)
|
||||
var timestamp = __time64_t()
|
||||
_ = _time64(×tamp)
|
||||
|
||||
var localTime = tm()
|
||||
_ = _localtime64_s(&localTime, ×tamp)
|
||||
|
||||
_ = strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S%z", &localTime)
|
||||
#else
|
||||
var timestamp = time(nil)
|
||||
guard let localTime = localtime(×tamp) else {
|
||||
return "<unknown>"
|
||||
}
|
||||
strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S%z", localTime)
|
||||
#endif
|
||||
return buffer.withUnsafeBufferPointer {
|
||||
$0.withMemoryRebound(to: CChar.self) {
|
||||
String(cString: $0.baseAddress!)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A wrapper to facilitate `print`-ing to stderr and stdio that
|
||||
/// ensures access to the underlying `FILE` is locked to prevent
|
||||
/// cross-thread interleaving of output.
|
||||
internal struct StdioOutputStream: TextOutputStream, @unchecked Sendable {
|
||||
internal let flushMode: FlushMode
|
||||
private let _writeBytes: (UnsafeBufferPointer<UInt8>) -> Void
|
||||
private let _flush: () -> Void
|
||||
|
||||
// Using a generic initializer lets Swift infer the concrete file-pointer type
|
||||
// at each call site from the values passed. This avoids a CFilePointer typealias
|
||||
// that cannot vary by Android API level (API 23 exposes FILE as
|
||||
// UnsafeMutablePointer<FILE>; API 24+ makes it OpaquePointer).
|
||||
internal init<F>(
|
||||
file: F,
|
||||
flushMode: FlushMode,
|
||||
lock: ((F) -> Void)?,
|
||||
unlock: ((F) -> Void)?,
|
||||
write: @escaping (UnsafeRawPointer, Int, Int, F) -> Int,
|
||||
flush: @escaping (F) -> Int32
|
||||
) {
|
||||
self.flushMode = flushMode
|
||||
self._writeBytes = { bytes in
|
||||
lock?(file)
|
||||
defer { unlock?(file) }
|
||||
if let base = bytes.baseAddress, bytes.count > 0 {
|
||||
_ = write(base, 1, bytes.count, file)
|
||||
}
|
||||
}
|
||||
self._flush = { _ = flush(file) }
|
||||
}
|
||||
|
||||
internal func write(_ string: String) {
|
||||
self.contiguousUTF8(string).withContiguousStorageIfAvailable { utf8Bytes in
|
||||
self._writeBytes(utf8Bytes)
|
||||
if case .always = self.flushMode {
|
||||
self.flush()
|
||||
}
|
||||
}!
|
||||
}
|
||||
|
||||
/// Flush the underlying stream.
|
||||
internal func flush() {
|
||||
self._flush()
|
||||
}
|
||||
|
||||
internal func contiguousUTF8(_ string: String) -> String.UTF8View {
|
||||
var contiguousString = string
|
||||
contiguousString.makeContiguousUTF8()
|
||||
return contiguousString.utf8
|
||||
}
|
||||
|
||||
internal static let stderr: StdioOutputStream = {
|
||||
#if canImport(Darwin)
|
||||
return StdioOutputStream(
|
||||
file: Darwin.stderr,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif os(Windows)
|
||||
return StdioOutputStream(
|
||||
file: CRT.stderr,
|
||||
flushMode: .always,
|
||||
lock: _lock_file,
|
||||
unlock: _unlock_file,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif canImport(Glibc)
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
return StdioOutputStream(
|
||||
file: Glibc.stderr,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#else
|
||||
return StdioOutputStream(
|
||||
file: Glibc.stderr!,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#endif
|
||||
#elseif canImport(Android)
|
||||
return StdioOutputStream(
|
||||
file: Android.stderr,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif canImport(Musl)
|
||||
return StdioOutputStream(
|
||||
file: Musl.stderr!,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif canImport(WASILibc)
|
||||
// no file locking on WASI
|
||||
return StdioOutputStream(
|
||||
file: WASILibc.stderr!,
|
||||
flushMode: .always,
|
||||
lock: nil,
|
||||
unlock: nil,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#else
|
||||
#error("Unsupported runtime")
|
||||
#endif
|
||||
}()
|
||||
|
||||
internal static let stdout: StdioOutputStream = {
|
||||
#if canImport(Darwin)
|
||||
return StdioOutputStream(
|
||||
file: Darwin.stdout,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif os(Windows)
|
||||
return StdioOutputStream(
|
||||
file: CRT.stdout,
|
||||
flushMode: .always,
|
||||
lock: _lock_file,
|
||||
unlock: _unlock_file,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif canImport(Glibc)
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
return StdioOutputStream(
|
||||
file: Glibc.stdout,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#else
|
||||
return StdioOutputStream(
|
||||
file: Glibc.stdout!,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#endif
|
||||
#elseif canImport(Android)
|
||||
return StdioOutputStream(
|
||||
file: Android.stdout,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif canImport(Musl)
|
||||
return StdioOutputStream(
|
||||
file: Musl.stdout!,
|
||||
flushMode: .always,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#elseif canImport(WASILibc)
|
||||
// no file locking on WASI
|
||||
return StdioOutputStream(
|
||||
file: WASILibc.stdout!,
|
||||
flushMode: .always,
|
||||
lock: nil,
|
||||
unlock: nil,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#else
|
||||
#error("Unsupported runtime")
|
||||
#endif
|
||||
}()
|
||||
|
||||
/// Defines the flushing strategy for the underlying stream.
|
||||
internal enum FlushMode {
|
||||
case undefined
|
||||
case always
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,80 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A no-operation log handler, used when no logging is required
|
||||
public struct SwiftLogNoOpLogHandler: LogHandler {
|
||||
/// Creates a no-op log handler.
|
||||
public init() {}
|
||||
|
||||
/// Creates a no-op log handler.
|
||||
public init(_: String) {}
|
||||
|
||||
/// A proxy that discards every log event it receives.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - event: The log event to discard.
|
||||
@inlinable public func log(event: LogEvent) {}
|
||||
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
@inlinable public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {}
|
||||
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
@inlinable public func log(
|
||||
level: Logging.Logger.Level,
|
||||
message: Logging.Logger.Message,
|
||||
metadata: Logging.Logger.Metadata?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {}
|
||||
|
||||
/// Add, change, or remove a logging metadata item.
|
||||
///
|
||||
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
|
||||
@inlinable public subscript(metadataKey _: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
nil
|
||||
}
|
||||
set {}
|
||||
}
|
||||
|
||||
/// Get or set the entire metadata storage as a dictionary.
|
||||
@inlinable public var metadata: Logger.Metadata {
|
||||
get {
|
||||
[:]
|
||||
}
|
||||
set {}
|
||||
}
|
||||
|
||||
/// Get or set the log level configured for this `Logger`.
|
||||
///
|
||||
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
|
||||
/// > It is acceptable for logging backends to have some form of global log level override
|
||||
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
|
||||
/// > certain cases have no effect.
|
||||
@inlinable public var logLevel: Logger.Level {
|
||||
get {
|
||||
.critical
|
||||
}
|
||||
set {}
|
||||
}
|
||||
}
|
||||
+85
-63
@@ -2,7 +2,7 @@
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// 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
|
||||
@@ -16,7 +16,7 @@
|
||||
//
|
||||
// This source file is part of the SwiftNIO open source project
|
||||
//
|
||||
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
|
||||
// Copyright (c) 2017-2026 Apple Inc. and the SwiftNIO project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
@@ -26,20 +26,26 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if canImport(WASILibc)
|
||||
// No locking on WASILibc
|
||||
#elseif canImport(Darwin)
|
||||
#if canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif os(Windows)
|
||||
import ucrt
|
||||
import WinSDK
|
||||
#elseif canImport(Glibc)
|
||||
import Glibc
|
||||
@preconcurrency import Glibc
|
||||
#elseif canImport(Android)
|
||||
import Android
|
||||
@preconcurrency import Android
|
||||
#elseif canImport(Musl)
|
||||
import Musl
|
||||
@preconcurrency import Musl
|
||||
#elseif canImport(Bionic)
|
||||
@preconcurrency import Bionic
|
||||
#elseif canImport(WASILibc)
|
||||
@preconcurrency import WASILibc
|
||||
#if canImport(wasi_pthread)
|
||||
import wasi_pthread
|
||||
#endif
|
||||
#else
|
||||
#error("Unsupported runtime")
|
||||
#error("The concurrency lock module was unable to identify your C library.")
|
||||
#endif
|
||||
|
||||
/// A threading lock based on `libpthread` instead of `libdispatch`.
|
||||
@@ -48,43 +54,56 @@ import Musl
|
||||
/// of lock is safe to use with `libpthread`-based threading models, such as the
|
||||
/// one used by NIO. On Windows, the lock is based on the substantially similar
|
||||
/// `SRWLOCK` type.
|
||||
internal final class Lock: @unchecked Sendable {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
package final class Lock {
|
||||
#if os(Windows)
|
||||
fileprivate let mutex: UnsafeMutablePointer<SRWLOCK> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#else
|
||||
#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))
|
||||
fileprivate let mutex: UnsafeMutablePointer<pthread_mutex_t> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#endif
|
||||
|
||||
/// Create a new lock.
|
||||
public init() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
package init() {
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
var attr = pthread_mutexattr_t(bitPattern: 0)
|
||||
#else
|
||||
var attr = pthread_mutexattr_t()
|
||||
pthread_mutexattr_init(&attr)
|
||||
pthread_mutexattr_settype(&attr, .init(PTHREAD_MUTEX_ERRORCHECK))
|
||||
#endif
|
||||
var err = pthread_mutexattr_init(&attr)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutexattr_init with error \(err)")
|
||||
debugOnly {
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
pthread_mutexattr_settype(&attr, .init(PTHREAD_MUTEX_ERRORCHECK.rawValue))
|
||||
#else
|
||||
pthread_mutexattr_settype(&attr, .init(PTHREAD_MUTEX_ERRORCHECK))
|
||||
#endif
|
||||
}
|
||||
|
||||
let err = pthread_mutex_init(self.mutex, &attr)
|
||||
err = pthread_mutex_init(self.mutex, &attr)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
// `pthread_mutexattr_t` only lives during init; destroy here instead of deinit.
|
||||
let attrDestroyErr = pthread_mutexattr_destroy(&attr)
|
||||
precondition(
|
||||
attrDestroyErr == 0,
|
||||
"\(#function) failed in pthread_mutexattr_destroy with error \(attrDestroyErr)"
|
||||
)
|
||||
#endif
|
||||
}
|
||||
|
||||
deinit {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
// SRWLOCK does not need to be free'd
|
||||
self.mutex.deallocate()
|
||||
#else
|
||||
#if os(Windows)
|
||||
mutex.deallocate()
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_mutex_destroy(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
self.mutex.deallocate()
|
||||
mutex.deallocate()
|
||||
#endif
|
||||
}
|
||||
|
||||
@@ -92,12 +111,10 @@ internal final class Lock: @unchecked Sendable {
|
||||
///
|
||||
/// Whenever possible, consider using `withLock` instead of this method and
|
||||
/// `unlock`, to simplify lock handling.
|
||||
public func lock() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
package func lock() {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.mutex)
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_mutex_lock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
@@ -107,19 +124,15 @@ internal final class Lock: @unchecked Sendable {
|
||||
///
|
||||
/// Whenever possible, consider using `withLock` instead of this method and
|
||||
/// `lock`, to simplify lock handling.
|
||||
public func unlock() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
package func unlock() {
|
||||
#if os(Windows)
|
||||
ReleaseSRWLockExclusive(self.mutex)
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_mutex_unlock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
}
|
||||
}
|
||||
|
||||
extension Lock {
|
||||
/// Acquire the lock for the duration of the given block.
|
||||
///
|
||||
/// This convenience method should be preferred to `lock` and `unlock` in
|
||||
@@ -129,7 +142,7 @@ extension Lock {
|
||||
/// - Parameter body: The block to execute while holding the lock.
|
||||
/// - Returns: The value returned by the block.
|
||||
@inlinable
|
||||
internal func withLock<T>(_ body: () throws -> T) rethrows -> T {
|
||||
package func withLock<T>(_ body: () throws -> T) rethrows -> T {
|
||||
self.lock()
|
||||
defer {
|
||||
self.unlock()
|
||||
@@ -139,11 +152,28 @@ extension Lock {
|
||||
|
||||
// specialise Void return (for performance)
|
||||
@inlinable
|
||||
internal func withLockVoid(_ body: () throws -> Void) rethrows {
|
||||
package func withLockVoid(_ body: () throws -> Void) rethrows {
|
||||
try self.withLock(body)
|
||||
}
|
||||
}
|
||||
|
||||
/// A utility function that runs the body code only in debug builds, without
|
||||
/// emitting compiler warnings.
|
||||
///
|
||||
/// This is currently the only way to do this in Swift: see
|
||||
/// https://forums.swift.org/t/support-debug-only-code/11037 for a discussion.
|
||||
@inlinable
|
||||
internal func debugOnly(_ body: () -> Void) {
|
||||
assert(
|
||||
{
|
||||
body()
|
||||
return true
|
||||
}()
|
||||
)
|
||||
}
|
||||
|
||||
extension Lock: @unchecked Sendable {}
|
||||
|
||||
/// A reader/writer threading lock based on `libpthread` instead of `libdispatch`.
|
||||
///
|
||||
/// This object provides a lock on top of a single `pthread_rwlock_t`. This kind
|
||||
@@ -157,6 +187,9 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
fileprivate let rwlock: UnsafeMutablePointer<SRWLOCK> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
fileprivate var shared: Bool = true
|
||||
#elseif os(FreeBSD) || os(OpenBSD)
|
||||
fileprivate let rwlock: UnsafeMutablePointer<pthread_rwlock_t?> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#else
|
||||
fileprivate let rwlock: UnsafeMutablePointer<pthread_rwlock_t> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
@@ -164,23 +197,18 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
|
||||
/// Create a new lock.
|
||||
public init() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.rwlock)
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_init(self.rwlock, nil)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
}
|
||||
|
||||
deinit {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
// SRWLOCK does not need to be free'd
|
||||
#if os(Windows)
|
||||
self.rwlock.deallocate()
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_destroy(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
self.rwlock.deallocate()
|
||||
@@ -192,12 +220,10 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
/// Whenever possible, consider using `withReaderLock` instead of this
|
||||
/// method and `unlock`, to simplify lock handling.
|
||||
fileprivate func lockRead() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
#if os(Windows)
|
||||
AcquireSRWLockShared(self.rwlock)
|
||||
self.shared = true
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_rdlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -208,12 +234,10 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
/// Whenever possible, consider using `withWriterLock` instead of this
|
||||
/// method and `unlock`, to simplify lock handling.
|
||||
fileprivate func lockWrite() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.rwlock)
|
||||
self.shared = false
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_wrlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -225,15 +249,13 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
/// instead of this method and `lockRead` and `lockWrite`, to simplify lock
|
||||
/// handling.
|
||||
fileprivate func unlock() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
#if os(Windows)
|
||||
if self.shared {
|
||||
ReleaseSRWLockShared(self.rwlock)
|
||||
} else {
|
||||
ReleaseSRWLockExclusive(self.rwlock)
|
||||
}
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_unlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A log event that contains all the information about a single log statement.
|
||||
///
|
||||
/// `LogEvent` is passed to a ``LogHandler`` via ``LogHandler/log(event:)`` and carries every piece of data emitted
|
||||
/// at the log call site. Handlers may inspect, modify, or forward any of the event's properties.
|
||||
///
|
||||
/// All properties are mutable so that handler wrappers (for example ``MultiplexLogHandler``) can rewrite fields
|
||||
/// such as metadata or source before forwarding to downstream handlers.
|
||||
public struct LogEvent: Sendable {
|
||||
/// The log level of this event.
|
||||
public var level: Logger.Level
|
||||
|
||||
/// The message of this event.
|
||||
public var message: Logger.Message
|
||||
|
||||
/// The error associated with this event, if any.
|
||||
public var error: (any Error)?
|
||||
|
||||
/// The metadata associated with this event, if any.
|
||||
///
|
||||
/// Metadata values may carry attributes accessible via ``Logger/MetadataValue/attributes``.
|
||||
public var metadata: Logger.Metadata?
|
||||
|
||||
/// The source where this log event originated, for example the logging module.
|
||||
///
|
||||
/// When no explicit source was provided at the call site, this is derived lazily from ``file``
|
||||
/// every time this property is accessed. Handlers that never read this property pay no
|
||||
/// allocation cost for source computation.
|
||||
public var source: String {
|
||||
@inlinable get { self._source ?? Logger.currentModule(fileID: self.file) }
|
||||
@inlinable set { self._source = newValue }
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal var _source: String?
|
||||
|
||||
/// The file this log event originates from.
|
||||
public var file: String
|
||||
|
||||
/// The function this log event originates from.
|
||||
public var function: String
|
||||
|
||||
/// The line this log event originates from.
|
||||
public var line: UInt
|
||||
|
||||
/// Creates a new log event.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of this event.
|
||||
/// - message: The message of this event.
|
||||
/// - metadata: The metadata associated with this event, if any.
|
||||
/// - source: The source where this log event originated. When `nil`, ``source`` is derived lazily
|
||||
/// from ``file`` on first access so handlers that never read it pay no allocation cost.
|
||||
/// - file: The file this log event originates from.
|
||||
/// - function: The function this log event originates from.
|
||||
/// - line: The line this log event originates from.
|
||||
public init(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.init(
|
||||
level: level,
|
||||
message: message,
|
||||
error: nil,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
|
||||
/// Creates a new log event.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of this event.
|
||||
/// - message: The message of this event.
|
||||
/// - error: The error associated with this event, if any.
|
||||
/// - metadata: The metadata associated with this event, if any.
|
||||
/// - source: The source where this log event originated. When `nil`, ``source`` is derived lazily
|
||||
/// from ``file`` on first access so handlers that never read it pay no allocation cost.
|
||||
/// - file: The file this log event originates from.
|
||||
/// - function: The function this log event originates from.
|
||||
/// - line: The line this log event originates from.
|
||||
public init(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.level = level
|
||||
self.message = message
|
||||
self.error = error
|
||||
self.metadata = metadata
|
||||
self._source = source
|
||||
self.file = file
|
||||
self.function = function
|
||||
self.line = line
|
||||
}
|
||||
}
|
||||
@@ -12,19 +12,19 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A `LogHandler` is an implementation of a logging backend.
|
||||
/// A log handler provides an implementation of a logging backend.
|
||||
///
|
||||
/// This type is an implementation detail and should not normally be used, unless implementing your own logging backend.
|
||||
/// This type is an implementation detail and should not normally be used, unless you implement your own logging backend.
|
||||
/// To use the SwiftLog API, please refer to the documentation of ``Logger``.
|
||||
///
|
||||
/// # Implementation requirements
|
||||
///
|
||||
/// To implement your own `LogHandler` you should respect a few requirements that are necessary so applications work
|
||||
/// as expected regardless of the selected `LogHandler` implementation.
|
||||
/// as expected, regardless of the selected `LogHandler` implementation.
|
||||
///
|
||||
/// - The ``LogHandler`` must be a `struct`.
|
||||
/// - The metadata and `logLevel` properties must be implemented so that setting them on a `Logger` does not affect
|
||||
/// other `Logger`s.
|
||||
/// other instances of `Logger`.
|
||||
///
|
||||
/// ### Treat log level & metadata as values
|
||||
///
|
||||
@@ -52,18 +52,21 @@
|
||||
///
|
||||
/// ### Special cases
|
||||
///
|
||||
/// In certain special cases, the log level behaving like a value on `Logger` might not be what you want. For example,
|
||||
/// you might want to set the log level across _all_ `Logger`s to `.debug` when say a signal (eg. `SIGUSR1`) is received
|
||||
/// to be able to debug special failures in production. This special case is acceptable but we urge you to create a
|
||||
/// solution specific to your `LogHandler` implementation to achieve that. Please find an example implementation of this
|
||||
/// behavior below, on reception of the signal you would call
|
||||
/// In certain special cases, the log level behaving like a value on `Logger` might not be what you want.
|
||||
/// For example, you might want to set the log level across _all_ `Logger`s to `.debug` when a signal
|
||||
/// (for example `SIGUSR1`) is received to be able to debug special failures in production.
|
||||
/// This special case is acceptable but please create a solution specific to your `LogHandler` implementation to achieve that.
|
||||
///
|
||||
/// The following code illustrates an example implementation of this behavior.
|
||||
/// On reception of the signal you would call
|
||||
/// `LogHandlerWithGlobalLogLevelOverride.overrideGlobalLogLevel = .debug`, for example.
|
||||
///
|
||||
/// ```swift
|
||||
/// import class Foundation.NSLock
|
||||
///
|
||||
/// public struct LogHandlerWithGlobalLogLevelOverride: LogHandler {
|
||||
/// // the static properties hold the globally overridden log level (if overridden)
|
||||
/// // The static properties hold the globally overridden
|
||||
/// // log level (if overridden).
|
||||
/// private static let overrideLock = NSLock()
|
||||
/// private static var overrideLogLevel: Logger.Level? = nil
|
||||
///
|
||||
@@ -78,21 +81,22 @@
|
||||
/// }
|
||||
///
|
||||
/// public var logLevel: Logger.Level {
|
||||
/// // when we get asked for the log level, we check if it was globally overridden or not
|
||||
/// // When asked for the log level, check
|
||||
/// // if it was globally overridden or not.
|
||||
/// get {
|
||||
/// LogHandlerWithGlobalLogLevelOverride.overrideLock.lock()
|
||||
/// defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() }
|
||||
/// return LogHandlerWithGlobalLogLevelOverride.overrideLogLevel ?? self._logLevel
|
||||
/// }
|
||||
/// // we set the log level whenever we're asked (note: this might not have an effect if globally
|
||||
/// // overridden)
|
||||
/// // Set the log level whenever asked
|
||||
/// // (note: this might not have an effect if globally
|
||||
/// // overridden).
|
||||
/// set {
|
||||
/// self._logLevel = newValue
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// public func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?,
|
||||
/// source: String, file: String, function: String, line: UInt) {
|
||||
/// public func log(event: LogEvent) {
|
||||
/// // [...]
|
||||
/// }
|
||||
///
|
||||
@@ -105,7 +109,8 @@
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// // this is the function to globally override the log level, it is not part of the `LogHandler` protocol
|
||||
/// // This is the function to globally override the log level,
|
||||
/// // it is not part of the `LogHandler` protocol.
|
||||
/// public static func overrideGlobalLogLevel(_ logLevel: Logger.Level) {
|
||||
/// LogHandlerWithGlobalLogLevelOverride.overrideLock.lock()
|
||||
/// defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() }
|
||||
@@ -114,28 +119,36 @@
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Please note that the above `LogHandler` will still pass the 'log level is a value' test above it iff the global log
|
||||
/// level has not been overridden. And most importantly it passes the requirement listed above: A change to the log
|
||||
/// level on one `Logger` should not affect the log level of another `Logger` variable.
|
||||
/// > Note: The above `LogHandler` still passes the 'log level is a value' test above it if the global log
|
||||
/// > level has not been overridden. Most importantly, it passes the requirement listed above: A change to the log
|
||||
/// > level on one `Logger` should not affect the log level of another `Logger` variable.
|
||||
public protocol LogHandler: _SwiftLogSendableLogHandler {
|
||||
/// The metadata provider this `LogHandler` will use when a log statement is about to be emitted.
|
||||
/// The metadata provider this log handler uses when a log statement is about to be emitted.
|
||||
///
|
||||
/// A ``Logger/MetadataProvider`` may add a constant set of metadata,
|
||||
/// or use task-local values to pick up contextual metadata and add it to emitted logs.
|
||||
var metadataProvider: Logger.MetadataProvider? { get set }
|
||||
|
||||
/// This method is called when a `LogHandler` must emit a log message. There is no need for the `LogHandler` to
|
||||
/// check if the `level` is above or below the configured `logLevel` as `Logger` already performed this check and
|
||||
/// determined that a message should be logged.
|
||||
/// The library calls this method when a log handler must emit a log message.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - level: The log level the message was logged at.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file the log message was emitted from.
|
||||
/// - function: The function the log line was emitted from.
|
||||
/// - line: The line the log message was emitted from.
|
||||
/// There is no need for the `LogHandler` to check if the level is above or below the configured `logLevel`
|
||||
/// as `Logger` already performed this check and determined that a message should be logged.
|
||||
///
|
||||
/// - Parameter event: The log event containing the level, message, metadata, and source location.
|
||||
func log(event: LogEvent)
|
||||
|
||||
/// Please do _not_ implement this method when you create a `LogHandler` implementation.
|
||||
/// Implement ``log(event:)`` instead.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
@@ -146,9 +159,19 @@ public protocol LogHandler: _SwiftLogSendableLogHandler {
|
||||
line: UInt
|
||||
)
|
||||
|
||||
/// SwiftLog 1.0 compatibility method. Please do _not_ implement, implement
|
||||
/// `log(level:message:metadata:source:file:function:line:)` instead.
|
||||
@available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
|
||||
/// SwiftLog 1.0 log compatibility method.
|
||||
///
|
||||
/// Please do _not_ implement this method when you create a LogHandler implementation.
|
||||
/// Implement ``log(event:)`` instead.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
func log(
|
||||
level: Logging.Logger.Level,
|
||||
message: Logging.Logger.Message,
|
||||
@@ -183,8 +206,9 @@ public protocol LogHandler: _SwiftLogSendableLogHandler {
|
||||
}
|
||||
|
||||
extension LogHandler {
|
||||
/// Default implementation for `metadataProvider` which defaults to `nil`.
|
||||
/// This default exists in order to facilitate source-compatible introduction of the `metadataProvider` protocol requirement.
|
||||
/// Default implementation for a metadata provider that defaults to nil.
|
||||
///
|
||||
/// This default exists in order to facilitate the source-compatible introduction of the `metadataProvider` protocol requirement.
|
||||
public var metadataProvider: Logger.MetadataProvider? {
|
||||
get {
|
||||
nil
|
||||
@@ -193,14 +217,16 @@ extension LogHandler {
|
||||
#if DEBUG
|
||||
if LoggingSystem.warnOnceLogHandlerNotSupportedMetadataProvider(Self.self) {
|
||||
self.log(
|
||||
level: .warning,
|
||||
message:
|
||||
"Attempted to set metadataProvider on \(Self.self) that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.",
|
||||
metadata: nil,
|
||||
source: "Logging",
|
||||
file: #file,
|
||||
function: #function,
|
||||
line: #line
|
||||
event: LogEvent(
|
||||
level: .warning,
|
||||
message:
|
||||
"Attempted to set metadataProvider on \(Self.self) that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.",
|
||||
metadata: nil,
|
||||
source: "Logging",
|
||||
file: #file,
|
||||
function: #function,
|
||||
line: #line
|
||||
)
|
||||
)
|
||||
}
|
||||
#endif
|
||||
@@ -209,7 +235,31 @@ extension LogHandler {
|
||||
}
|
||||
|
||||
extension LogHandler {
|
||||
/// Default implementation of ``log(event:)`` for backward compatibility with handlers that implement the
|
||||
/// deprecated flat-parameter method.
|
||||
///
|
||||
/// Handlers that implement ``log(level:message:metadata:source:file:function:line:)`` continue to work
|
||||
/// without any source changes; this default forwards the event's fields to that method.
|
||||
///
|
||||
/// New handlers should implement ``log(event:)`` directly and rely on this default only as a fallback.
|
||||
///
|
||||
/// > Warning: Do not call this default directly. It exists only as a backward-compatibility bridge.
|
||||
/// Implement ``log(event:)`` in your ``LogHandler`` instead.
|
||||
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
|
||||
public func log(event: LogEvent) {
|
||||
self.log(
|
||||
level: event.level,
|
||||
message: event.message,
|
||||
metadata: event.metadata,
|
||||
source: event.source,
|
||||
file: event.file,
|
||||
function: event.function,
|
||||
line: event.line
|
||||
)
|
||||
}
|
||||
|
||||
/// A default implementation for a log message handler that forwards to the SwiftLog 1.0 compatibility method.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
@@ -219,10 +269,18 @@ extension LogHandler {
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.log(level: level, message: message, metadata: metadata, file: file, function: function, line: line)
|
||||
self.log(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
|
||||
/// A default implementation for the SwiftLog 1.0 log message handler.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logging.Logger.Level,
|
||||
message: Logging.Logger.Message,
|
||||
|
||||
@@ -0,0 +1,553 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
// MARK: - MetadataValueAttributes storage
|
||||
|
||||
extension Logger {
|
||||
/// Attributes that can be associated with metadata values.
|
||||
public struct MetadataValueAttributes: Sendable {
|
||||
/// A protocol for defining custom metadata attributes.
|
||||
///
|
||||
/// Conform to this protocol to define a custom attribute that can be stored in
|
||||
/// ``MetadataValueAttributes``. Each conforming type acts as both the key (identified
|
||||
/// by its metatype) and the value.
|
||||
///
|
||||
/// This protocol is designed for **small, fixed-vocabulary attributes**.
|
||||
/// Each attribute value is stored as an `Int64` raw value, so attributes occupy minimal
|
||||
/// space (one inline slot without heap allocation for the common single-attribute case).
|
||||
///
|
||||
/// ## Examples
|
||||
///
|
||||
/// ```swift
|
||||
/// public enum Priority: Int64, Sendable, Logger.MetadataValueAttributes.Attribute {
|
||||
/// case low = 1
|
||||
/// case high = 2
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// ```swift
|
||||
/// public struct Priority: Sendable, Hashable, Logger.MetadataValueAttributes.Attribute {
|
||||
/// public let rawValue: Int64
|
||||
/// public init(rawValue: Int64) {
|
||||
/// self.rawValue = rawValue
|
||||
/// }
|
||||
/// public static let low = Priority(rawValue: 1)
|
||||
/// public static let high = Priority(rawValue: 2)
|
||||
/// }
|
||||
/// ```
|
||||
public protocol Attribute: Sendable, RawRepresentable where RawValue == Int64 {}
|
||||
|
||||
/// An entry in the metadata attributes storage.
|
||||
@usableFromInline
|
||||
internal struct Entry: Sendable, Equatable {
|
||||
@usableFromInline
|
||||
internal var key: ObjectIdentifier
|
||||
|
||||
@usableFromInline
|
||||
internal var value: Int64
|
||||
|
||||
@inlinable
|
||||
internal init(key: ObjectIdentifier, value: Int64) {
|
||||
self.key = key
|
||||
self.value = value
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal var _inline: Entry?
|
||||
|
||||
@usableFromInline
|
||||
internal var _overflow: [Entry]?
|
||||
|
||||
/// Create empty metadata value attributes.
|
||||
@inlinable
|
||||
public init() {}
|
||||
|
||||
/// Get or set a custom attribute by its type.
|
||||
///
|
||||
/// - Parameter attribute: The metatype of the attribute to access.
|
||||
/// - Returns: The attribute value, or `nil` if not set.
|
||||
@inlinable
|
||||
public subscript<Attr: Attribute>(attribute: Attr.Type) -> Attr? {
|
||||
get {
|
||||
let id = ObjectIdentifier(Attr.self)
|
||||
if let inline = self._inline, inline.key == id { return Attr(rawValue: inline.value) }
|
||||
if let overflow = self._overflow {
|
||||
for entry in overflow {
|
||||
if entry.key == id { return Attr(rawValue: entry.value) }
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
set {
|
||||
let id = ObjectIdentifier(Attr.self)
|
||||
if let v = newValue {
|
||||
self._upsert(key: id, value: v.rawValue)
|
||||
} else {
|
||||
self._remove(key: id)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
internal mutating func _upsert(key id: ObjectIdentifier, value: Int64) {
|
||||
let entry = Entry(key: id, value: value)
|
||||
if let inline = self._inline, inline.key == id {
|
||||
self._inline = entry
|
||||
return
|
||||
}
|
||||
if let idx = self._overflow?.firstIndex(where: { $0.key == id }) {
|
||||
self._overflow?[idx] = entry
|
||||
return
|
||||
}
|
||||
if self._inline == nil {
|
||||
self._inline = entry
|
||||
} else {
|
||||
if self._overflow == nil {
|
||||
self._overflow = [entry]
|
||||
} else {
|
||||
self._overflow?.append(entry)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
internal mutating func _remove(key id: ObjectIdentifier) {
|
||||
if let inline = self._inline, inline.key == id {
|
||||
if var overflow = self._overflow, !overflow.isEmpty {
|
||||
self._inline = overflow.removeLast()
|
||||
self._overflow = overflow.isEmpty ? nil : overflow
|
||||
} else {
|
||||
self._inline = nil
|
||||
}
|
||||
return
|
||||
}
|
||||
if let idx = self._overflow?.firstIndex(where: { $0.key == id }) {
|
||||
self._overflow?.remove(at: idx)
|
||||
if self._overflow?.isEmpty == true {
|
||||
self._overflow = nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
internal mutating func _merge(from other: Self) {
|
||||
if let inline = other._inline {
|
||||
self._upsert(key: inline.key, value: inline.value)
|
||||
}
|
||||
if let overflow = other._overflow {
|
||||
for entry in overflow {
|
||||
self._upsert(key: entry.key, value: entry.value)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Compare all entries as an unordered set.
|
||||
///
|
||||
/// The inline slot and overflow array may hold the same logical entries in different
|
||||
/// positions depending on insertion order. This method checks set equality by
|
||||
/// verifying that every entry on one side exists on the other. O(n²) but n is
|
||||
/// typically 1–2.
|
||||
@inlinable
|
||||
internal func _isEqual(to other: Self) -> Bool {
|
||||
let lhsOverflowCount = self._overflow?.count ?? 0
|
||||
let rhsOverflowCount = other._overflow?.count ?? 0
|
||||
let lhsCount = (self._inline != nil ? 1 : 0) + lhsOverflowCount
|
||||
let rhsCount = (other._inline != nil ? 1 : 0) + rhsOverflowCount
|
||||
guard lhsCount == rhsCount else { return false }
|
||||
guard lhsCount > 0 else { return true }
|
||||
|
||||
// Check that every lhs entry exists in rhs.
|
||||
// With matching counts, this is sufficient for set equality.
|
||||
if let inline = self._inline {
|
||||
if !other._contains(inline) { return false }
|
||||
}
|
||||
if let overflow = self._overflow {
|
||||
for entry in overflow {
|
||||
if !other._contains(entry) { return false }
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
@inlinable
|
||||
internal func _contains(_ entry: Entry) -> Bool {
|
||||
if self._inline == entry { return true }
|
||||
if let overflow = self._overflow {
|
||||
for e in overflow {
|
||||
if e == entry { return true }
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger.MetadataValueAttributes: Equatable {
|
||||
@inlinable
|
||||
public static func == (lhs: Self, rhs: Self) -> Bool {
|
||||
lhs._isEqual(to: rhs)
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger.MetadataValueAttributes: ExpressibleByArrayLiteral {
|
||||
/// Creates metadata value attributes from an array literal of attribute values.
|
||||
///
|
||||
/// Each element is any ``Attribute`` conforming value. The key is
|
||||
/// inferred from the concrete type of the value.
|
||||
///
|
||||
/// ```swift
|
||||
/// let attrs: Logger.MetadataValueAttributes = [Sensitivity.sensitive, ValueType.int64]
|
||||
/// ```
|
||||
/// Each element goes through existential boxing to extract `type(of:)` and `.rawValue`.
|
||||
/// This is acceptable for a literal initializer but should not be used in hot paths;
|
||||
/// prefer the type-safe subscript (`attrs[SomeAttribute.self] = value`) for performance-sensitive code.
|
||||
@inlinable
|
||||
public init(arrayLiteral elements: any Logger.MetadataValueAttributes.Attribute...) {
|
||||
self.init()
|
||||
for element in elements {
|
||||
self._upsert(key: ObjectIdentifier(type(of: element)), value: element.rawValue)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - AttributedStringCarrier
|
||||
|
||||
extension Logger {
|
||||
/// Internal carrier that wraps a string with metadata attributes.
|
||||
///
|
||||
/// Produced by `MetadataValue.StringInterpolation` when any interpolation
|
||||
/// segment specifies attributes, or by ``MetadataValue/attributed(_:attributes:)``.
|
||||
/// This is the only type that carries attributes; the `.attributes` property on
|
||||
/// `MetadataValue` checks for it with a concrete type comparison rather than a
|
||||
/// protocol conformance lookup.
|
||||
@usableFromInline
|
||||
internal struct AttributedStringCarrier: CustomStringConvertible, Sendable {
|
||||
@usableFromInline
|
||||
internal let string: String
|
||||
|
||||
@usableFromInline
|
||||
internal let metadataAttributes: Logger.MetadataValueAttributes
|
||||
|
||||
@usableFromInline
|
||||
internal init(string: String, metadataAttributes: Logger.MetadataValueAttributes) {
|
||||
self.string = string
|
||||
self.metadataAttributes = metadataAttributes
|
||||
}
|
||||
|
||||
@inlinable
|
||||
internal var description: String { self.string }
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - MetadataValue attributes API
|
||||
|
||||
extension Logger.MetadataValue {
|
||||
/// The attributes associated with this metadata value, if any.
|
||||
///
|
||||
/// **Getting:** When the value is a ``stringConvertible(_:)`` wrapping an
|
||||
/// `AttributedStringCarrier`, returns that carrier's attributes.
|
||||
/// For all other cases returns empty attributes.
|
||||
///
|
||||
/// **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.
|
||||
///
|
||||
/// Only handlers that inspect attributes pay the cost of the getter check.
|
||||
@inlinable
|
||||
public var attributes: Logger.MetadataValueAttributes {
|
||||
get {
|
||||
if case .stringConvertible(let box) = self,
|
||||
let carrier = box as? Logger.AttributedStringCarrier
|
||||
{
|
||||
return carrier.metadataAttributes
|
||||
}
|
||||
return .init()
|
||||
}
|
||||
set {
|
||||
switch self {
|
||||
case .string(let s):
|
||||
self = .stringConvertible(
|
||||
Logger.AttributedStringCarrier(string: s, metadataAttributes: newValue)
|
||||
)
|
||||
case .stringConvertible(let box):
|
||||
self = .stringConvertible(
|
||||
Logger.AttributedStringCarrier(string: box.description, metadataAttributes: newValue)
|
||||
)
|
||||
case .dictionary, .array:
|
||||
assertionFailure("Cannot set attributes on .dictionary or .array metadata values")
|
||||
return
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Creates an attributed metadata value from a string-convertible value and attributes.
|
||||
///
|
||||
/// This is a convenience factory that behaves like an additional enum case, producing
|
||||
/// a `.stringConvertible(AttributedStringCarrier(...))` value without string interpolation:
|
||||
///
|
||||
/// ```swift
|
||||
/// let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
|
||||
/// ```
|
||||
@inlinable
|
||||
public static func attributed(
|
||||
_ value: some CustomStringConvertible & Sendable,
|
||||
attributes: Logger.MetadataValueAttributes
|
||||
) -> Self {
|
||||
.stringConvertible(
|
||||
Logger.AttributedStringCarrier(
|
||||
string: String(describing: value),
|
||||
metadataAttributes: attributes
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Attributed string interpolation
|
||||
|
||||
// Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for
|
||||
// https://bugs.swift.org/browse/SR-9687
|
||||
extension Logger.MetadataValue: ExpressibleByStringInterpolation {
|
||||
/// Custom string interpolation that optionally captures metadata attributes.
|
||||
///
|
||||
/// When no attributes are specified, produces `.string(...)` — identical to the
|
||||
/// default `DefaultStringInterpolation` behavior. When any interpolation segment
|
||||
/// specifies attributes (via the `attributes:` parameter), the result is
|
||||
/// `.stringConvertible(AttributedStringCarrier(...))` carrying both the string
|
||||
/// and the accumulated attributes.
|
||||
///
|
||||
/// Attribute packages (like `LoggingAttributes`) can add overloads with
|
||||
/// domain-specific parameters (e.g. `sensitivity:`) that call through to
|
||||
/// `appendInterpolation(_:attributes:)`.
|
||||
public struct StringInterpolation: StringInterpolationProtocol, Sendable {
|
||||
@usableFromInline
|
||||
internal var output: String = ""
|
||||
|
||||
@usableFromInline
|
||||
internal var attributes: Logger.MetadataValueAttributes = .init()
|
||||
|
||||
@usableFromInline
|
||||
internal var hasAttributes: Bool = false
|
||||
|
||||
@inlinable
|
||||
public init(literalCapacity: Int, interpolationCount: Int) {
|
||||
self.output.reserveCapacity(literalCapacity + interpolationCount * 2)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendLiteral(_ literal: String) {
|
||||
self.output.append(literal)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
internal mutating func _mergeAttributes(_ attributes: Logger.MetadataValueAttributes) {
|
||||
if self.hasAttributes {
|
||||
self.attributes._merge(from: attributes)
|
||||
} else {
|
||||
self.attributes = attributes
|
||||
}
|
||||
self.hasAttributes = true
|
||||
}
|
||||
|
||||
// MARK: Plain interpolation
|
||||
// The four overloads below mirror `DefaultStringInterpolation`'s shape.
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||||
_ value: T
|
||||
) {
|
||||
value.write(to: &self.output)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||||
_ value: T
|
||||
) {
|
||||
value.write(to: &self.output)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||||
_ value: T
|
||||
) {
|
||||
self.output.append(value.description)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T
|
||||
) {
|
||||
self.output.append(String(describing: value))
|
||||
}
|
||||
|
||||
// MARK: Optional interpolation with a default
|
||||
// The four overloads below mirror `DefaultStringInterpolation`'s `default:`
|
||||
// shape so that `"\(optional, default: "none")"` keeps working when the
|
||||
// literal is inferred as a `Logger.MetadataValue`.
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||||
_ value: T?,
|
||||
default defaultValue: @autoclosure () -> some StringProtocol
|
||||
) {
|
||||
if let value {
|
||||
self.appendInterpolation(value)
|
||||
} else {
|
||||
self.output.append(String(defaultValue()))
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||||
_ value: T?,
|
||||
default defaultValue: @autoclosure () -> some StringProtocol
|
||||
) {
|
||||
if let value {
|
||||
self.appendInterpolation(value)
|
||||
} else {
|
||||
self.output.append(String(defaultValue()))
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||||
_ value: T?,
|
||||
default defaultValue: @autoclosure () -> some StringProtocol
|
||||
) {
|
||||
if let value {
|
||||
self.appendInterpolation(value)
|
||||
} else {
|
||||
self.output.append(String(defaultValue()))
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T?,
|
||||
default defaultValue: @autoclosure () -> some StringProtocol
|
||||
) {
|
||||
if let value {
|
||||
self.appendInterpolation(value)
|
||||
} else {
|
||||
self.output.append(String(defaultValue()))
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: Interpolation with a custom attributes closure
|
||||
//
|
||||
// ```swift
|
||||
// "\(userId, attributes: { $0[MyAttribute.self] = .flagged })"
|
||||
// ```
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||||
_ value: T,
|
||||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||||
) {
|
||||
value.write(to: &self.output)
|
||||
attributes(&self.attributes)
|
||||
self.hasAttributes = true
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||||
_ value: T,
|
||||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||||
) {
|
||||
value.write(to: &self.output)
|
||||
attributes(&self.attributes)
|
||||
self.hasAttributes = true
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||||
_ value: T,
|
||||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||||
) {
|
||||
self.output.append(value.description)
|
||||
attributes(&self.attributes)
|
||||
self.hasAttributes = true
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T,
|
||||
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
|
||||
) {
|
||||
self.output.append(String(describing: value))
|
||||
attributes(&self.attributes)
|
||||
self.hasAttributes = true
|
||||
}
|
||||
|
||||
// MARK: Interpolation with pre-built attributes
|
||||
//
|
||||
// ```swift
|
||||
// "\(userId, attributes: [Sensitivity.sensitive])"
|
||||
// ```
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
|
||||
_ value: T,
|
||||
attributes: Logger.MetadataValueAttributes
|
||||
) {
|
||||
value.write(to: &self.output)
|
||||
self._mergeAttributes(attributes)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: TextOutputStreamable>(
|
||||
_ value: T,
|
||||
attributes: Logger.MetadataValueAttributes
|
||||
) {
|
||||
value.write(to: &self.output)
|
||||
self._mergeAttributes(attributes)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T: CustomStringConvertible>(
|
||||
_ value: T,
|
||||
attributes: Logger.MetadataValueAttributes
|
||||
) {
|
||||
self.output.append(value.description)
|
||||
self._mergeAttributes(attributes)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func appendInterpolation<T>(
|
||||
_ value: T,
|
||||
attributes: Logger.MetadataValueAttributes
|
||||
) {
|
||||
self.output.append(String(describing: value))
|
||||
self._mergeAttributes(attributes)
|
||||
}
|
||||
}
|
||||
|
||||
/// Creates a metadata value from string interpolation.
|
||||
///
|
||||
/// If any interpolation segment specified attributes, the result is
|
||||
/// `.stringConvertible(AttributedStringCarrier(...))`. Otherwise, `.string(...)`.
|
||||
@inlinable
|
||||
public init(stringInterpolation: StringInterpolation) {
|
||||
if stringInterpolation.hasAttributes {
|
||||
self = .stringConvertible(
|
||||
Logger.AttributedStringCarrier(
|
||||
string: stringInterpolation.output,
|
||||
metadataAttributes: stringInterpolation.attributes
|
||||
)
|
||||
)
|
||||
} else {
|
||||
self = .string(stringInterpolation.output)
|
||||
}
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,217 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// The logging system is a global facility where you can configure the default logging backend implementation.
|
||||
///
|
||||
/// `LoggingSystem` is set up just once in a given program to set up the desired logging backend implementation.
|
||||
/// The default behavior, if you don't define otherwise, sets the ``LogHandler`` to use a ``StreamLogHandler`` that presents its output to `STDOUT`.
|
||||
///
|
||||
/// You can configure that handler to present the output to `STDERR` instead using the following code:
|
||||
///
|
||||
/// ```swift
|
||||
/// LoggingSystem.bootstrap(StreamLogHandler.standardError)
|
||||
/// ```
|
||||
///
|
||||
/// The default (``StreamLogHandler``) is intended to be a convenience.
|
||||
/// For production applications, implement the ``LogHandler`` protocol directly, or use a community-maintained backend.
|
||||
public enum LoggingSystem: Sendable {
|
||||
private static let _factory = FactoryBox(
|
||||
{ label, _ in StreamLogHandler.standardError(label: label) },
|
||||
violationErrorMesage: "logging system can only be initialized once per process."
|
||||
)
|
||||
private static let _metadataProviderFactory = MetadataProviderBox(
|
||||
nil,
|
||||
violationErrorMesage: "logging system can only be initialized once per process."
|
||||
)
|
||||
|
||||
#if DEBUG
|
||||
private static let _warnOnceBox: WarnOnceBox = WarnOnceBox()
|
||||
#endif
|
||||
|
||||
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
|
||||
///
|
||||
/// > Warning:
|
||||
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
|
||||
/// > lead to undefined behavior, most likely a crash.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
|
||||
@preconcurrency
|
||||
public static func bootstrap(_ factory: @escaping @Sendable (String) -> any LogHandler) {
|
||||
self._factory.replace(
|
||||
{ label, _ in
|
||||
factory(label)
|
||||
},
|
||||
validate: true
|
||||
)
|
||||
}
|
||||
|
||||
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
|
||||
///
|
||||
/// > Warning:
|
||||
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
|
||||
/// > lead to undefined behavior, most likely a crash.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - metadataProvider: The `MetadataProvider` used to inject runtime-generated metadata from the execution context.
|
||||
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
|
||||
@preconcurrency
|
||||
public static func bootstrap(
|
||||
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
|
||||
metadataProvider: Logger.MetadataProvider?
|
||||
) {
|
||||
self._metadataProviderFactory.replace(metadataProvider, validate: true)
|
||||
self._factory.replace(factory, validate: true)
|
||||
}
|
||||
|
||||
// for our testing we want to allow multiple bootstrapping
|
||||
internal static func bootstrapInternal(_ factory: @escaping @Sendable (String) -> any LogHandler) {
|
||||
self._metadataProviderFactory.replace(nil, validate: false)
|
||||
self._factory.replace(
|
||||
{ label, _ in
|
||||
factory(label)
|
||||
},
|
||||
validate: false
|
||||
)
|
||||
}
|
||||
|
||||
// for our testing we want to allow multiple bootstrapping
|
||||
internal static func bootstrapInternal(
|
||||
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
|
||||
metadataProvider: Logger.MetadataProvider?
|
||||
) {
|
||||
self._metadataProviderFactory.replace(metadataProvider, validate: false)
|
||||
self._factory.replace(factory, validate: false)
|
||||
}
|
||||
|
||||
internal static var factory: (String, Logger.MetadataProvider?) -> any LogHandler {
|
||||
{ label, metadataProvider in
|
||||
self._factory.underlying(label, metadataProvider)
|
||||
}
|
||||
}
|
||||
|
||||
/// System wide ``Logger/MetadataProvider`` that was configured during the logging system's `bootstrap`.
|
||||
///
|
||||
/// When creating a ``Logger`` using the plain ``Logger/init(label:)`` initializer, this metadata provider
|
||||
/// will be provided to it.
|
||||
///
|
||||
/// When using custom log handler factories, make sure to provide the bootstrapped metadata provider to them,
|
||||
/// or the metadata will not be filled in automatically using the provider on log-sites. While using a custom
|
||||
/// factory to avoid using the bootstrapped metadata provider may sometimes be useful, usually it will lead to
|
||||
/// un-expected behavior, so make sure to always propagate it to your handlers.
|
||||
public static var metadataProvider: Logger.MetadataProvider? {
|
||||
self._metadataProviderFactory.underlying
|
||||
}
|
||||
|
||||
#if DEBUG
|
||||
/// Used to warn only once about a specific ``LogHandler`` type when it does not support ``Logger/MetadataProvider``,
|
||||
/// but an attempt was made to set a metadata provider on such handler. In order to avoid flooding the system with
|
||||
/// warnings such warning is only emitted in debug mode, and even then at-most once for a handler type.
|
||||
internal static func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(
|
||||
_ type: Handler.Type
|
||||
) -> Bool {
|
||||
self._warnOnceBox.warnOnceLogHandlerNotSupportedMetadataProvider(type: type)
|
||||
}
|
||||
#endif
|
||||
|
||||
/// Protects an object such that it can only be accessed through a Reader-Writer lock.
|
||||
final class RWLockedValueBox<Value: Sendable>: @unchecked Sendable {
|
||||
private let lock = ReadWriteLock()
|
||||
private var storage: Value
|
||||
|
||||
init(initialValue: Value) {
|
||||
self.storage = initialValue
|
||||
}
|
||||
|
||||
func withReadLock<Result>(_ operation: (Value) -> Result) -> Result {
|
||||
self.lock.withReaderLock {
|
||||
operation(self.storage)
|
||||
}
|
||||
}
|
||||
|
||||
func withWriteLock<Result>(_ operation: (inout Value) -> Result) -> Result {
|
||||
self.lock.withWriterLock {
|
||||
operation(&self.storage)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Protects an object by applying the constraints that it can only be accessed through a Reader-Writer lock
|
||||
/// and can only be updated once from the initial value given.
|
||||
private struct ReplaceOnceBox<BoxedType: Sendable> {
|
||||
private struct ReplaceOnce: Sendable {
|
||||
private var initialized = false
|
||||
private var _underlying: BoxedType
|
||||
private let violationErrorMessage: String
|
||||
|
||||
mutating func replaceUnderlying(_ underlying: BoxedType, validate: Bool) {
|
||||
precondition(!validate || !self.initialized, self.violationErrorMessage)
|
||||
self._underlying = underlying
|
||||
self.initialized = true
|
||||
}
|
||||
|
||||
var underlying: BoxedType {
|
||||
self._underlying
|
||||
}
|
||||
|
||||
init(underlying: BoxedType, violationErrorMessage: String) {
|
||||
self._underlying = underlying
|
||||
self.violationErrorMessage = violationErrorMessage
|
||||
}
|
||||
}
|
||||
|
||||
private let storage: RWLockedValueBox<ReplaceOnce>
|
||||
|
||||
init(_ underlying: BoxedType, violationErrorMesage: String) {
|
||||
self.storage = .init(
|
||||
initialValue: ReplaceOnce(
|
||||
underlying: underlying,
|
||||
violationErrorMessage: violationErrorMesage
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
func replace(_ newUnderlying: BoxedType, validate: Bool) {
|
||||
self.storage.withWriteLock { $0.replaceUnderlying(newUnderlying, validate: validate) }
|
||||
}
|
||||
|
||||
var underlying: BoxedType {
|
||||
self.storage.withReadLock { $0.underlying }
|
||||
}
|
||||
}
|
||||
|
||||
private typealias FactoryBox = ReplaceOnceBox<
|
||||
@Sendable (_ label: String, _ provider: Logger.MetadataProvider?) -> any LogHandler
|
||||
>
|
||||
|
||||
private typealias MetadataProviderBox = ReplaceOnceBox<Logger.MetadataProvider?>
|
||||
}
|
||||
|
||||
// MARK: - Debug only warnings
|
||||
|
||||
#if DEBUG
|
||||
/// Contains state to manage all kinds of "warn only once" warnings which the logging system may want to issue.
|
||||
private final class WarnOnceBox: @unchecked Sendable {
|
||||
private let lock: Lock = Lock()
|
||||
private var warnOnceLogHandlerNotSupportedMetadataProviderPerType = Set<ObjectIdentifier>()
|
||||
|
||||
func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(type: Handler.Type) -> Bool {
|
||||
self.lock.withLock {
|
||||
let id = ObjectIdentifier(type)
|
||||
let (inserted, _) = warnOnceLogHandlerNotSupportedMetadataProviderPerType.insert(id)
|
||||
return inserted // warn about this handler type, it is the first time we encountered it
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -31,7 +31,7 @@ import WASILibc
|
||||
@preconcurrency protocol _SwiftLogSendable: Sendable {}
|
||||
|
||||
extension Logger {
|
||||
/// A `MetadataProvider` is used to automatically inject runtime-generated metadata
|
||||
/// A MetadataProvider automatically injects runtime-generated metadata
|
||||
/// to all logs emitted by a logger.
|
||||
///
|
||||
/// ### Example
|
||||
@@ -53,23 +53,37 @@ extension Logger {
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// ### Metadata with Attributes
|
||||
///
|
||||
/// Metadata providers can return values that carry attributes via string interpolation:
|
||||
///
|
||||
/// ```swift
|
||||
/// let provider = Logger.MetadataProvider {
|
||||
/// [
|
||||
/// "trace-id": "\(Baggage.current?.traceID, sensitivity: .public)",
|
||||
/// "user-id": "\(RequestContext.current.userId, sensitivity: .sensitive)"
|
||||
/// ]
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// We recommend referring to [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing)
|
||||
/// for metadata providers which make use of its tracing and metadata propagation infrastructure. It is however
|
||||
/// possible to make use of metadata providers independently of tracing and instruments provided by that library,
|
||||
/// if necessary.
|
||||
public struct MetadataProvider: _SwiftLogSendable {
|
||||
/// Provide ``Logger.Metadata`` from current context.
|
||||
@usableFromInline
|
||||
internal let _provideMetadata: @Sendable () -> Metadata
|
||||
|
||||
/// Create a new `MetadataProvider`.
|
||||
/// Creates a new metadata provider.
|
||||
///
|
||||
/// - Parameter provideMetadata: A closure extracting metadata from the current execution context.
|
||||
/// - Parameter provideMetadata: A closure that extracts metadata from the current execution context.
|
||||
public init(_ provideMetadata: @escaping @Sendable () -> Metadata) {
|
||||
self._provideMetadata = provideMetadata
|
||||
}
|
||||
|
||||
/// Invoke the metadata provider and return the generated contextual ``Logger/Metadata``.
|
||||
/// Invokes the metadata provider and returns the generated contextual metadata.
|
||||
///
|
||||
/// - Returns: Metadata dictionary, where values may carry attributes.
|
||||
public func get() -> Metadata {
|
||||
self._provideMetadata()
|
||||
}
|
||||
@@ -77,7 +91,7 @@ extension Logger {
|
||||
}
|
||||
|
||||
extension Logger.MetadataProvider {
|
||||
/// A pseudo-`MetadataProvider` that can be used to merge metadata from multiple other `MetadataProvider`s.
|
||||
/// A pseudo metadata provider that merges metadata from multiple other metadata providers.
|
||||
///
|
||||
/// ### Merging conflicting keys
|
||||
///
|
||||
@@ -88,13 +102,12 @@ extension Logger.MetadataProvider {
|
||||
/// - Returns: A pseudo-`MetadataProvider` merging metadata from the given `MetadataProvider`s.
|
||||
public static func multiplex(_ providers: [Logger.MetadataProvider]) -> Logger.MetadataProvider? {
|
||||
assert(!providers.isEmpty, "providers MUST NOT be empty")
|
||||
|
||||
return Logger.MetadataProvider {
|
||||
providers.reduce(into: [:]) { metadata, provider in
|
||||
let providedMetadata = provider.get()
|
||||
guard !providedMetadata.isEmpty else {
|
||||
return
|
||||
}
|
||||
metadata.merge(providedMetadata, uniquingKeysWith: { _, rhs in rhs })
|
||||
providers.reduce(into: Logger.Metadata()) { merged, provider in
|
||||
let provided = provider.get()
|
||||
guard !provided.isEmpty else { return }
|
||||
merged.merge(provided, uniquingKeysWith: { _, rhs in rhs })
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,161 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2022 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 InMemoryLogHandlerTests {
|
||||
@Test
|
||||
func collectsLogs() {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
|
||||
#expect(logHandler.entries.count == 1)
|
||||
#expect(logHandler.entries[0].level == .info)
|
||||
#expect(logHandler.entries[0].message == "hello")
|
||||
#expect(logHandler.entries[0].metadata == ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
}
|
||||
|
||||
@Test
|
||||
func metadataFromLoggerEndsUpInEntry() {
|
||||
var (logHandler, logger) = self.makeTestLogger()
|
||||
logger[metadataKey: "test"] = "value"
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
|
||||
#expect(logHandler.entries.count == 1)
|
||||
#expect(logHandler.entries[0].level == .info)
|
||||
#expect(logHandler.entries[0].message == "hello")
|
||||
#expect(logHandler.entries[0].metadata == ["key1": "value1", "key2": ["a", "b", "c"], "test": "value"])
|
||||
#expect(logger[metadataKey: "test"] == "value")
|
||||
}
|
||||
|
||||
@Test
|
||||
func moreSpecificMetadataOverridesGlobal() {
|
||||
let testProvider = Logger.MetadataProvider {
|
||||
["a": "1", "b": "1", "c": "1"]
|
||||
}
|
||||
var (logHandler, logger) = self.makeTestLogger(metadataProvider: testProvider)
|
||||
logger[metadataKey: "b"] = "2"
|
||||
logger[metadataKey: "c"] = "2"
|
||||
logger.info("hello", metadata: ["c": "3"])
|
||||
|
||||
#expect(logHandler.entries.count == 1)
|
||||
#expect(logHandler.entries[0].level == .info)
|
||||
#expect(logHandler.entries[0].message == "hello")
|
||||
#expect(logHandler.entries[0].metadata == ["a": "1", "b": "1", "c": "3"])
|
||||
}
|
||||
|
||||
@Test
|
||||
func clear() {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
logHandler.clear()
|
||||
logger.info("hello2")
|
||||
|
||||
#expect(logHandler.entries.count == 1)
|
||||
#expect(logHandler.entries[0].level == .info)
|
||||
#expect(logHandler.entries[0].message == "hello2")
|
||||
#expect(logHandler.entries[0].metadata == [:])
|
||||
}
|
||||
|
||||
@Test
|
||||
func metadataWithAttributesIsPreservedInEntry() {
|
||||
var (logHandler, logger) = self.makeTestLogger()
|
||||
logger.logLevel = .trace
|
||||
logger[metadataKey: "global"] = "value"
|
||||
|
||||
logger.log(
|
||||
level: .info,
|
||||
"test",
|
||||
metadata: [
|
||||
"key": "\("value", attributes: { _ in })"
|
||||
]
|
||||
)
|
||||
|
||||
#expect(logHandler.entries.count == 1)
|
||||
#expect(logHandler.entries[0].metadata["key"]?.description == "value")
|
||||
#expect(logHandler.entries[0].metadata["global"]?.description == "value")
|
||||
}
|
||||
|
||||
private func makeTestLogger(metadataProvider: Logger.MetadataProvider? = nil) -> (InMemoryLogHandler, Logger) {
|
||||
var logHandler = InMemoryLogHandler()
|
||||
logHandler.metadataProvider = metadataProvider
|
||||
let logger = Logger(
|
||||
label: "MyApp",
|
||||
factory: { _ in
|
||||
logHandler
|
||||
}
|
||||
)
|
||||
return (logHandler, logger)
|
||||
}
|
||||
|
||||
@Test
|
||||
func errorEquality() throws {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", error: TestError.first)
|
||||
let entry = try #require(logHandler.entries.first)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
== InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: TestError.first,
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
!= InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: nil,
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
!= InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: TestError.second,
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
!= InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: Nested.TestError.first,
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
enum TestError: Error {
|
||||
case first
|
||||
case second
|
||||
}
|
||||
|
||||
struct Nested {
|
||||
enum TestError: Error {
|
||||
case first
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -14,11 +14,11 @@
|
||||
|
||||
// Not testable
|
||||
import Logging
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
final class CompatibilityTest: XCTestCase {
|
||||
struct CompatibilityTest {
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
func testAllLogLevelsWorkWithOldSchoolLogHandlerWorks() {
|
||||
@Test func allLogLevelsWorkWithOldSchoolLogHandlerWorks() {
|
||||
let testLogging = OldSchoolTestLogging()
|
||||
|
||||
var logger = Logger(label: "\(#function)", factory: { testLogging.make(label: $0) })
|
||||
@@ -41,6 +41,31 @@ final class CompatibilityTest: XCTestCase {
|
||||
testLogging.history.assertExist(level: .error, message: "yes: error", source: "no source")
|
||||
testLogging.history.assertExist(level: .critical, message: "yes: critical", source: "no source")
|
||||
}
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
@Test func allLogLevelsWorkWithNewerButStillOldLogHandlerWorks() {
|
||||
let testLogging = NewerButStillOldTestLogging()
|
||||
|
||||
var logger = Logger(label: "\(#function)", factory: { testLogging.make(label: $0) })
|
||||
logger.logLevel = .trace
|
||||
|
||||
logger.trace("yes: trace", source: "yes: trace source")
|
||||
logger.debug("yes: debug", source: "yes: debug source")
|
||||
logger.info("yes: info", source: "yes: info source")
|
||||
logger.notice("yes: notice", source: "yes: notice source")
|
||||
logger.warning("yes: warning", source: "yes: warning source")
|
||||
logger.error("yes: error", source: "yes: error source")
|
||||
logger.critical("yes: critical", source: "yes: critical source")
|
||||
|
||||
// Please note that the source is _not_ propagated (because the backend doesn't support it).
|
||||
testLogging.history.assertExist(level: .trace, message: "yes: trace", source: "yes: trace source")
|
||||
testLogging.history.assertExist(level: .debug, message: "yes: debug", source: "yes: debug source")
|
||||
testLogging.history.assertExist(level: .info, message: "yes: info", source: "yes: info source")
|
||||
testLogging.history.assertExist(level: .notice, message: "yes: notice", source: "yes: notice source")
|
||||
testLogging.history.assertExist(level: .warning, message: "yes: warning", source: "yes: warning source")
|
||||
testLogging.history.assertExist(level: .error, message: "yes: error", source: "yes: error source")
|
||||
testLogging.history.assertExist(level: .critical, message: "yes: critical", source: "yes: critical source")
|
||||
}
|
||||
}
|
||||
|
||||
private struct OldSchoolTestLogging {
|
||||
@@ -96,3 +121,58 @@ private struct OldSchoolLogHandler: LogHandler {
|
||||
|
||||
var logLevel: Logger.Level
|
||||
}
|
||||
|
||||
private struct NewerButStillOldTestLogging {
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
func make(label: String) -> any LogHandler {
|
||||
NewerButStillOldLogHandler(
|
||||
label: label,
|
||||
config: self.config,
|
||||
recorder: self.recorder,
|
||||
metadata: [:],
|
||||
logLevel: .info
|
||||
)
|
||||
}
|
||||
|
||||
var config: Config { self._config }
|
||||
var history: some History { self.recorder }
|
||||
}
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
private struct NewerButStillOldLogHandler: LogHandler {
|
||||
var label: String
|
||||
let config: Config
|
||||
let recorder: Recorder
|
||||
|
||||
func make(label: String) -> some LogHandler {
|
||||
TestLogHandler(label: label, config: self.config, recorder: self.recorder)
|
||||
}
|
||||
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.recorder.record(level: level, metadata: metadata, message: message, source: source)
|
||||
}
|
||||
|
||||
subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self.metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
self.metadata[metadataKey] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
var metadata: Logger.Metadata
|
||||
|
||||
var logLevel: Logger.Level
|
||||
}
|
||||
@@ -12,24 +12,22 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import Dispatch
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if compiler(>=6.0) || canImport(Darwin)
|
||||
import Dispatch
|
||||
#else
|
||||
@preconcurrency import Dispatch
|
||||
#endif
|
||||
|
||||
class GlobalLoggerTest: XCTestCase {
|
||||
func test1() throws {
|
||||
/// This is the only test suite allowed to use global LoggingSystem bootstrapping,
|
||||
/// tests in the suite are executed one by one
|
||||
@Suite(.serialized)
|
||||
struct GlobalLoggerTest {
|
||||
@Test func traceAndAbove() throws {
|
||||
// bootstrap with our test logging impl
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config to log traces and above
|
||||
logging.config.set(value: Logger.Level.debug)
|
||||
// change test logging config to log trace and above
|
||||
logging.config.set(value: Logger.Level.trace)
|
||||
// run our program
|
||||
Struct1().doSomething()
|
||||
// test results
|
||||
@@ -45,12 +43,16 @@ class GlobalLoggerTest: XCTestCase {
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::Local", metadata: ["baz": "qux"])
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::end")
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomething::end")
|
||||
logging.history.assertExist(level: .trace, message: "Struct3::doSomething::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
logging.history.assertExist(level: .trace, message: "Struct1::doSomething::end::lastLine")
|
||||
|
||||
}
|
||||
|
||||
func test2() throws {
|
||||
@Test func errorAndAbove() throws {
|
||||
// bootstrap with our test logging impl
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
@@ -80,12 +82,15 @@ class GlobalLoggerTest: XCTestCase {
|
||||
)
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomething::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct3::doSomething::end::lastLine")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct1::doSomething::end::lastLine")
|
||||
}
|
||||
|
||||
func test3() throws {
|
||||
@Test func warningAndAbove() throws {
|
||||
// bootstrap with our test logging impl
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
@@ -119,6 +124,96 @@ class GlobalLoggerTest: XCTestCase {
|
||||
}
|
||||
}
|
||||
|
||||
/// MetadataProvider tests relying on the global state
|
||||
extension GlobalLoggerTest {
|
||||
@Test func loggingMergesOneOffMetadataWithProvidedMetadataFromExplicitlyPassed() throws {
|
||||
let logging = TestLogging()
|
||||
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
metadataProvider: .init {
|
||||
["common": "initial"]
|
||||
}
|
||||
)
|
||||
|
||||
let logger = Logger(
|
||||
label: #function,
|
||||
metadataProvider: .init {
|
||||
[
|
||||
"common": "provider",
|
||||
"provider": "42",
|
||||
]
|
||||
}
|
||||
)
|
||||
|
||||
logger.log(level: .info, "test", metadata: ["one-off": "42", "common": "one-off"])
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "test",
|
||||
metadata: ["common": "one-off", "one-off": "42", "provider": "42"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func loggerWithoutFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider() {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
metadataProvider: .init { ["provider": "42"] }
|
||||
)
|
||||
|
||||
let logger = Logger(label: #function)
|
||||
|
||||
logger.log(level: .info, "test", metadata: ["one-off": "42"])
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "test",
|
||||
metadata: ["provider": "42", "one-off": "42"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func loggerWithPredefinedLibraryMetadataProvider() {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
metadataProvider: .exampleProvider
|
||||
)
|
||||
|
||||
let logger = Logger(label: #function)
|
||||
|
||||
logger.log(level: .info, "test", metadata: ["one-off": "42"])
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "test",
|
||||
metadata: ["example": "example-value", "one-off": "42"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func loggerWithFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider() {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
metadataProvider: .init { ["provider": "42"] }
|
||||
)
|
||||
|
||||
let logger = Logger(
|
||||
label: #function,
|
||||
factory: { label in
|
||||
logging.makeWithMetadataProvider(label: label, metadataProvider: LoggingSystem.metadataProvider)
|
||||
}
|
||||
)
|
||||
logger.log(level: .info, "test", metadata: ["one-off": "42"])
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "test",
|
||||
metadata: ["provider": "42", "one-off": "42"]
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
private struct Struct1 {
|
||||
private let logger = Logger(label: "GlobalLoggerTest::Struct1")
|
||||
|
||||
@@ -132,6 +227,7 @@ private struct Struct1 {
|
||||
self.logger.debug("Struct1::doSomethingElse")
|
||||
Struct2().doSomething()
|
||||
self.logger.debug("Struct1::doSomethingElse::end")
|
||||
self.logger.trace("Struct1::doSomething::end::lastLine")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -148,6 +244,7 @@ private struct Struct2 {
|
||||
self.logger.info("Struct2::doSomethingElse")
|
||||
Struct3().doSomething()
|
||||
self.logger.debug("Struct2::doSomethingElse::end")
|
||||
self.logger.trace("Struct2::doSomethingElse::end::lastLine")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -159,6 +256,7 @@ private struct Struct3 {
|
||||
self.logger.error("Struct3::doSomething")
|
||||
self.doSomethingElse()
|
||||
self.logger.debug("Struct3::doSomething::end")
|
||||
self.logger.trace("Struct3::doSomething::end::lastLine")
|
||||
}
|
||||
|
||||
private func doSomethingElse() {
|
||||
|
||||
@@ -12,26 +12,21 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import Dispatch
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if compiler(>=6.0) || canImport(Darwin)
|
||||
import Dispatch
|
||||
#else
|
||||
@preconcurrency import Dispatch
|
||||
#endif
|
||||
|
||||
class LocalLoggerTest: XCTestCase {
|
||||
func test1() throws {
|
||||
// bootstrap with our test logging impl
|
||||
struct LocalLoggerTest {
|
||||
@Test func traceAndAbove() throws {
|
||||
// create test logging impl, do not bootstrap global LoggingSystem
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config to log traces and above
|
||||
logging.config.set(value: Logger.Level.debug)
|
||||
// change global test logging config to log trace and above,
|
||||
// local logging context will be modified to debug
|
||||
logging.config.set(value: Logger.Level.trace)
|
||||
// run our program
|
||||
let context = Context()
|
||||
let context = Context { logging.make(label: $0) }
|
||||
Struct1().doSomething(context: context)
|
||||
// test results
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomething", source: "LoggingTests")
|
||||
@@ -41,29 +36,33 @@ class LocalLoggerTest: XCTestCase {
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomething", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomethingElse", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .warning, message: "Struct3::doSomethingElseAsync", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .info, message: "TestLibrary::doSomething")
|
||||
logging.history.assertExist(level: .info, message: "TestLibrary::doSomethingAsync")
|
||||
logging.history.assertExist(
|
||||
level: .debug,
|
||||
message: "Struct3::doSomethingElse::Local",
|
||||
metadata: ["bar": "baz", "baz": "qux"]
|
||||
)
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::end", metadata: ["bar": "baz"])
|
||||
logging.history.assertNotExist(
|
||||
level: .trace,
|
||||
message: "Struct3::doSomethingElse::end::lastLine",
|
||||
metadata: ["bar": "baz"]
|
||||
)
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomething::end", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct1::doSomethingElse::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
}
|
||||
|
||||
func test2() throws {
|
||||
// bootstrap with our test logging impl
|
||||
@Test func errorAndAbove() throws {
|
||||
// create test logging impl, do not bootstrap global LoggingSystem
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config to log errors and above
|
||||
logging.config.set(value: Logger.Level.error)
|
||||
// run our program
|
||||
let context = Context()
|
||||
let context = Context { logging.make(label: $0) }
|
||||
Struct1().doSomething(context: context)
|
||||
// test results
|
||||
// global context
|
||||
@@ -84,20 +83,27 @@ class LocalLoggerTest: XCTestCase {
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomething")
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomethingAsync")
|
||||
// hyper local context
|
||||
// hyper local .debug context
|
||||
logging.history.assertExist(
|
||||
level: .debug,
|
||||
message: "Struct3::doSomethingElse::Local",
|
||||
metadata: ["bar": "baz", "baz": "qux"]
|
||||
)
|
||||
// local context
|
||||
// local .debug context
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::end", metadata: ["bar": "baz"])
|
||||
// local context
|
||||
logging.history.assertNotExist(
|
||||
level: .trace,
|
||||
message: "Struct3::doSomethingElse::end::lastLine",
|
||||
metadata: ["bar": "baz"]
|
||||
)
|
||||
// local .debug context
|
||||
logging.history.assertExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
// local context
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomething::end", metadata: ["bar": "baz"])
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct1::doSomethingElse::end::lastLine")
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
}
|
||||
@@ -105,7 +111,11 @@ class LocalLoggerTest: XCTestCase {
|
||||
|
||||
// systems that follow the context pattern need to implement something like this
|
||||
private struct Context {
|
||||
var logger = Logger(label: "LocalLoggerTest::ContextLogger")
|
||||
var logger: Logger
|
||||
|
||||
init(_ factory: (String) -> any LogHandler) {
|
||||
self.logger = Logger(label: "LocalLoggerTest::ContextLogger", factory: factory)
|
||||
}
|
||||
|
||||
// since logger is a value type, we can reuse our copy to manage logLevel
|
||||
var logLevel: Logger.Level {
|
||||
@@ -152,6 +162,7 @@ private struct Struct2 {
|
||||
c.logger.info("Struct2::doSomethingElse")
|
||||
Struct3().doSomething(context: c)
|
||||
c.logger.debug("Struct2::doSomethingElse::end")
|
||||
c.logger.trace("Struct2::doSomethingElse::end::lastLine")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -164,6 +175,7 @@ private struct Struct3 {
|
||||
c.logger.error("Struct3::doSomething")
|
||||
self.doSomethingElse(context: c)
|
||||
c.logger.debug("Struct3::doSomething::end")
|
||||
c.logger.trace("Struct3::doSomething::end::lastLine")
|
||||
}
|
||||
|
||||
private func doSomethingElse(context: Context) {
|
||||
@@ -184,5 +196,6 @@ private struct Struct3 {
|
||||
l[metadataKey: "baz"] = "qux"
|
||||
l.debug("Struct3::doSomethingElse::Local")
|
||||
context.logger.debug("Struct3::doSomethingElse::end")
|
||||
context.logger.trace("Struct3::doSomethingElse::end::lastLine")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the SwiftNIO open source project
|
||||
//
|
||||
// Copyright (c) 2017-2026 Apple Inc. and the SwiftNIO project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if canImport(Dispatch)
|
||||
import Dispatch
|
||||
private let canImportDispatch = true
|
||||
#else
|
||||
private let canImportDispatch = false
|
||||
#endif
|
||||
|
||||
@Suite("Lock Test Suite")
|
||||
struct LockTestSuite {
|
||||
@Test(.enabled(if: canImportDispatch)) func testLockMutualExclusion() {
|
||||
#if canImport(Dispatch)
|
||||
let l = Lock()
|
||||
|
||||
nonisolated(unsafe) var x = 1
|
||||
let q = DispatchQueue(label: "q")
|
||||
let g = DispatchGroup()
|
||||
let sem1 = DispatchSemaphore(value: 0)
|
||||
let sem2 = DispatchSemaphore(value: 0)
|
||||
|
||||
l.lock()
|
||||
|
||||
q.async(group: g) {
|
||||
sem1.signal()
|
||||
l.lock()
|
||||
x = 2
|
||||
l.unlock()
|
||||
sem2.signal()
|
||||
}
|
||||
|
||||
sem1.wait()
|
||||
#expect(DispatchTimeoutResult.timedOut == g.wait(timeout: .now() + 0.1))
|
||||
#expect(1 == x)
|
||||
|
||||
l.unlock()
|
||||
sem2.wait()
|
||||
|
||||
l.lock()
|
||||
#expect(2 == x)
|
||||
l.unlock()
|
||||
#endif // canImport(Dispatch)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,248 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 LogEventTest {
|
||||
|
||||
// MARK: - Lazy source computation
|
||||
|
||||
@Test func sourceIsDerivedFromFileWhenNotProvided() {
|
||||
let event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.source == "MyModule")
|
||||
}
|
||||
|
||||
@Test func sourceUsesExplicitValueWhenProvided() {
|
||||
let event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: "ExplicitSource",
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.source == "ExplicitSource")
|
||||
}
|
||||
|
||||
@Test func sourceSetterOverridesLazyValue() {
|
||||
var event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.source == "MyModule")
|
||||
|
||||
event.source = "OverriddenSource"
|
||||
#expect(event.source == "OverriddenSource")
|
||||
}
|
||||
|
||||
@Test func sourceLazyDerivationDoesNotStoreComputedValue() {
|
||||
let event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
// Internal _source should be nil when no explicit source was provided.
|
||||
#expect(event._source == nil)
|
||||
// Accessing source derives it from file but does not mutate _source (it's a computed get).
|
||||
_ = event.source
|
||||
#expect(event._source == nil)
|
||||
}
|
||||
|
||||
@Test func metadataSetterStoresThroughComputedProperty() {
|
||||
var event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "M/F.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.metadata == nil)
|
||||
|
||||
event.metadata = ["key": "value"]
|
||||
#expect(event.metadata?["key"] == "value")
|
||||
|
||||
event.metadata = nil
|
||||
#expect(event.metadata == nil)
|
||||
}
|
||||
|
||||
// MARK: - Attributes on metadata values
|
||||
|
||||
@Test func metadataValueCarriesAttributesThroughStringInterpolation() {
|
||||
enum TestAttr: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case flagged = 1
|
||||
}
|
||||
|
||||
let value: Logger.MetadataValue = "\("secret", attributes: { $0[TestAttr.self] = .flagged })"
|
||||
#expect(value.attributes[TestAttr.self] == .flagged)
|
||||
#expect(value.description == "secret")
|
||||
}
|
||||
|
||||
@Test func metadataValueWithoutAttributesProducesString() {
|
||||
let value: Logger.MetadataValue = "\("plain")"
|
||||
#expect(value.attributes == Logger.MetadataValueAttributes())
|
||||
|
||||
if case .string(let s) = value {
|
||||
#expect(s == "plain")
|
||||
} else {
|
||||
Issue.record("Expected .string case for non-attributed interpolation")
|
||||
}
|
||||
}
|
||||
|
||||
@Test func metadataValueAttributesAreEmptyForPlainValues() {
|
||||
let values: [Logger.MetadataValue] = [
|
||||
.string("test"),
|
||||
.stringConvertible(42),
|
||||
.array(["a", "b"]),
|
||||
.dictionary(["k": "v"]),
|
||||
]
|
||||
for value in values {
|
||||
#expect(value.attributes == Logger.MetadataValueAttributes())
|
||||
}
|
||||
}
|
||||
|
||||
@Test func metadataValuesWithAttributesFlowThroughLogEvent() {
|
||||
enum TestAttr: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case flagged = 1
|
||||
}
|
||||
|
||||
let event = LogEvent(
|
||||
level: .info,
|
||||
message: "test",
|
||||
error: nil,
|
||||
metadata: [
|
||||
"secret": "\("value", attributes: { $0[TestAttr.self] = .flagged })",
|
||||
"plain": "no-attrs",
|
||||
],
|
||||
source: nil,
|
||||
file: "M/F.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
|
||||
#expect(event.metadata?["secret"]?.attributes[TestAttr.self] == .flagged)
|
||||
#expect(event.metadata?["secret"]?.description == "value")
|
||||
#expect(event.metadata?["plain"]?.attributes[TestAttr.self] == nil)
|
||||
}
|
||||
|
||||
@Test func loggerDerivedSourceMatchesModuleName() {
|
||||
let recorder = Recorder()
|
||||
let handler = LogEventHandler(recorder: recorder)
|
||||
var logger = Logger(label: "test", handler)
|
||||
logger.logLevel = .trace
|
||||
|
||||
// Log without explicit source — source should be derived from #fileID.
|
||||
logger.info("derived source test")
|
||||
|
||||
let entries = recorder.entries
|
||||
#expect(entries.count == 1)
|
||||
#expect(entries[0].source == "LoggingTests")
|
||||
}
|
||||
|
||||
// MARK: - Default log(event:) forwarding to deprecated flat-parameter method
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
@Test func defaultLogEventForwardsAllFieldsIncludingSourceLocation() {
|
||||
let recorder = Recorder()
|
||||
let handler = FlatParametersHandler(recorder: recorder)
|
||||
var logger = Logger(label: "test", handler)
|
||||
logger.logLevel = .trace
|
||||
|
||||
logger.warning("location test")
|
||||
let line = UInt(#line - 1)
|
||||
|
||||
let entries = recorder.entries
|
||||
#expect(entries.count == 1)
|
||||
#expect(entries[0].level == .warning)
|
||||
#expect(entries[0].message == "location test")
|
||||
#expect(entries[0].file.hasSuffix("LogEventTest.swift"))
|
||||
#expect(entries[0].function.contains("defaultLogEventForwardsAllFieldsIncludingSourceLocation"))
|
||||
#expect(entries[0].line == line)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Test Helpers
|
||||
|
||||
/// A handler that implements `log(event:)` directly and records entries.
|
||||
private struct LogEventHandler: LogHandler {
|
||||
let recorder: Recorder
|
||||
var logLevel: Logger.Level = .trace
|
||||
var metadata: Logger.Metadata = [:]
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
func log(event: LogEvent) {
|
||||
self.recorder.record(level: event.level, metadata: event.metadata, message: event.message, source: event.source)
|
||||
}
|
||||
|
||||
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[key] }
|
||||
set { self.metadata[key] = newValue }
|
||||
}
|
||||
}
|
||||
|
||||
/// A handler that only implements the deprecated flat-parameter method, relying on the
|
||||
/// default `log(event:)` forwarding bridge.
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
private struct FlatParametersHandler: LogHandler {
|
||||
let recorder: Recorder
|
||||
var logLevel: Logger.Level = .trace
|
||||
var metadata: Logger.Metadata = [:]
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.recorder.record(
|
||||
level: level,
|
||||
metadata: metadata,
|
||||
message: message,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
|
||||
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[key] }
|
||||
set { self.metadata[key] = newValue }
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -12,16 +12,12 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
import Dispatch
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
class MDCTest: XCTestCase {
|
||||
func test1() throws {
|
||||
// bootstrap with our test logger
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
struct MDCTest {
|
||||
@Test func test() throws {
|
||||
// run the program
|
||||
MDC.global["foo"] = "bar"
|
||||
let group = DispatchGroup()
|
||||
@@ -36,20 +32,20 @@ class MDCTest: XCTestCase {
|
||||
for i in 0...remove {
|
||||
MDC.global["key-\(i)"] = nil
|
||||
}
|
||||
XCTAssertEqual(add - remove, MDC.global.metadata.count, "expected number of entries to match")
|
||||
#expect((add - remove) == MDC.global.metadata.count, "expected number of entries to match")
|
||||
for i in remove + 1...add {
|
||||
XCTAssertNotNil(MDC.global["key-\(i)"], "expecting value for key-\(i)")
|
||||
#expect(MDC.global["key-\(i)"] != nil, "expecting value for key-\(i)")
|
||||
}
|
||||
for i in 0...remove {
|
||||
XCTAssertNil(MDC.global["key-\(i)"], "not expecting value for key-\(i)")
|
||||
#expect(MDC.global["key-\(i)"] == nil, "not expecting value for key-\(i)")
|
||||
}
|
||||
MDC.global.clear()
|
||||
group.leave()
|
||||
}
|
||||
}
|
||||
group.wait()
|
||||
XCTAssertEqual(MDC.global["foo"], "bar", "expecting to find top items")
|
||||
#expect(MDC.global["foo"] == "bar", "expecting to find top items")
|
||||
MDC.global["foo"] = nil
|
||||
XCTAssertTrue(MDC.global.metadata.isEmpty, "MDC should be empty")
|
||||
#expect(MDC.global.metadata.isEmpty, "MDC should be empty")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,443 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
// MARK: - Test Attribute Keys
|
||||
|
||||
enum AttrA: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case a1 = 1
|
||||
case a2 = 2
|
||||
}
|
||||
|
||||
enum AttrB: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case b1 = 1
|
||||
case b2 = 2
|
||||
}
|
||||
|
||||
enum AttrC: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case c1 = 1
|
||||
case c2 = 2
|
||||
}
|
||||
|
||||
enum AttrD: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case d1 = 1
|
||||
case d2 = 2
|
||||
}
|
||||
|
||||
enum AttrE: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case e1 = 1
|
||||
case e2 = 2
|
||||
}
|
||||
|
||||
// MARK: - Tests
|
||||
|
||||
@Suite("MetadataValueAttributes Tests")
|
||||
struct MetadataAttributesTests {
|
||||
|
||||
@Test("Empty attributes")
|
||||
func testEmpty() {
|
||||
let attrs = Logger.MetadataValueAttributes()
|
||||
#expect(attrs[AttrA.self] == nil)
|
||||
#expect(attrs[AttrB.self] == nil)
|
||||
}
|
||||
|
||||
@Test("Set and get single attribute (inline)")
|
||||
func testSingleInline() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Set and get multiple attributes")
|
||||
func testMultipleAttributes() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
attrs[AttrB.self] = .b2
|
||||
attrs[AttrC.self] = .c1
|
||||
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
#expect(attrs[AttrB.self] == .b2)
|
||||
#expect(attrs[AttrC.self] == .c1)
|
||||
}
|
||||
|
||||
@Test("Update existing attribute")
|
||||
func testUpdate() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
|
||||
attrs[AttrA.self] = .a2
|
||||
#expect(attrs[AttrA.self] == .a2)
|
||||
}
|
||||
|
||||
@Test("Remove inline attribute")
|
||||
func testRemoveInline() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
|
||||
attrs[AttrA.self] = nil
|
||||
#expect(attrs[AttrA.self] == nil)
|
||||
}
|
||||
|
||||
@Test("Remove overflow attribute")
|
||||
func testRemoveOverflow() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
attrs[AttrB.self] = .b1
|
||||
attrs[AttrC.self] = .c1
|
||||
|
||||
attrs[AttrB.self] = nil
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
#expect(attrs[AttrB.self] == nil)
|
||||
#expect(attrs[AttrC.self] == .c1)
|
||||
}
|
||||
|
||||
@Test("Remove inline promotes from overflow")
|
||||
func testRemoveInlinePromotesOverflow() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
attrs[AttrB.self] = .b1 // overflow
|
||||
|
||||
// Remove inline — overflow entry should be promoted
|
||||
attrs[AttrA.self] = nil
|
||||
|
||||
#expect(attrs[AttrA.self] == nil)
|
||||
#expect(attrs[AttrB.self] == .b1)
|
||||
}
|
||||
|
||||
@Test("Five attributes")
|
||||
func testFiveAttributes() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
attrs[AttrB.self] = .b1
|
||||
attrs[AttrC.self] = .c1
|
||||
attrs[AttrD.self] = .d1
|
||||
attrs[AttrE.self] = .e1
|
||||
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
#expect(attrs[AttrB.self] == .b1)
|
||||
#expect(attrs[AttrC.self] == .c1)
|
||||
#expect(attrs[AttrD.self] == .d1)
|
||||
#expect(attrs[AttrE.self] == .e1)
|
||||
}
|
||||
|
||||
@Test("Update overflow attribute")
|
||||
func testUpdateOverflow() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = .a1
|
||||
attrs[AttrB.self] = .b1
|
||||
|
||||
attrs[AttrB.self] = .b2
|
||||
#expect(attrs[AttrB.self] == .b2)
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Equality with same content")
|
||||
func testEquality() {
|
||||
var attrs1 = Logger.MetadataValueAttributes()
|
||||
attrs1[AttrA.self] = .a1
|
||||
attrs1[AttrB.self] = .b1
|
||||
|
||||
var attrs2 = Logger.MetadataValueAttributes()
|
||||
attrs2[AttrA.self] = .a1
|
||||
attrs2[AttrB.self] = .b1
|
||||
|
||||
#expect(attrs1 == attrs2)
|
||||
|
||||
attrs2[AttrB.self] = .b2
|
||||
#expect(attrs1 != attrs2)
|
||||
}
|
||||
|
||||
@Test("Equality is order-independent")
|
||||
func testOrderIndependentEquality() {
|
||||
var attrs1 = Logger.MetadataValueAttributes()
|
||||
attrs1[AttrA.self] = .a1
|
||||
attrs1[AttrB.self] = .b1
|
||||
attrs1[AttrC.self] = .c1
|
||||
|
||||
var attrs2 = Logger.MetadataValueAttributes()
|
||||
attrs2[AttrC.self] = .c1
|
||||
attrs2[AttrA.self] = .a1
|
||||
attrs2[AttrB.self] = .b1
|
||||
|
||||
#expect(attrs1 == attrs2)
|
||||
}
|
||||
|
||||
@Test("Setting nil on non-existent attribute is no-op")
|
||||
func testSetNilNonExistent() {
|
||||
var attrs = Logger.MetadataValueAttributes()
|
||||
attrs[AttrA.self] = nil
|
||||
#expect(attrs[AttrA.self] == nil)
|
||||
|
||||
attrs[AttrB.self] = .b1
|
||||
attrs[AttrA.self] = nil
|
||||
#expect(attrs[AttrA.self] == nil)
|
||||
#expect(attrs[AttrB.self] == .b1)
|
||||
}
|
||||
|
||||
// MARK: - MetadataValue.attributed factory
|
||||
|
||||
@Test("Create attributed value with .attributed factory")
|
||||
func testAttributedFactory() {
|
||||
let value: Logger.MetadataValue = .attributed("hello", attributes: [AttrA.a1])
|
||||
#expect(value.description == "hello")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Attributed factory with multiple attributes")
|
||||
func testAttributedFactoryMultipleAttributes() {
|
||||
let value: Logger.MetadataValue = .attributed("test", attributes: [AttrA.a1, AttrB.b2])
|
||||
#expect(value.description == "test")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
#expect(value.attributes[AttrB.self] == .b2)
|
||||
}
|
||||
|
||||
@Test("Attributed factory with empty attributes")
|
||||
func testAttributedFactoryEmptyAttributes() {
|
||||
let value: Logger.MetadataValue = .attributed("plain", attributes: .init())
|
||||
#expect(value.description == "plain")
|
||||
#expect(value.attributes[AttrA.self] == nil)
|
||||
}
|
||||
|
||||
@Test("Attributed factory produces same result as string interpolation")
|
||||
func testAttributedFactoryMatchesStringInterpolation() {
|
||||
let factory: Logger.MetadataValue = .attributed("42", attributes: [AttrA.a1])
|
||||
let interpolated: Logger.MetadataValue = "\(42, attributes: [AttrA.a1])"
|
||||
#expect(factory.description == interpolated.description)
|
||||
#expect(factory.attributes == interpolated.attributes)
|
||||
}
|
||||
|
||||
// MARK: - Array literal construction
|
||||
|
||||
@Test("Array literal with single attribute")
|
||||
func testArrayLiteralSingle() {
|
||||
let attrs: Logger.MetadataValueAttributes = [AttrA.a1]
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Array literal with multiple attributes")
|
||||
func testArrayLiteralMultiple() {
|
||||
let attrs: Logger.MetadataValueAttributes = [AttrA.a1, AttrB.b2, AttrC.c1]
|
||||
#expect(attrs[AttrA.self] == .a1)
|
||||
#expect(attrs[AttrB.self] == .b2)
|
||||
#expect(attrs[AttrC.self] == .c1)
|
||||
}
|
||||
|
||||
@Test("Array literal with duplicate key uses last value")
|
||||
func testArrayLiteralDuplicateKey() {
|
||||
let attrs: Logger.MetadataValueAttributes = [AttrA.a1, AttrA.a2]
|
||||
#expect(attrs[AttrA.self] == .a2)
|
||||
}
|
||||
|
||||
// MARK: - MetadataValue.attributes setter
|
||||
|
||||
@Test("Set attributes on .string value")
|
||||
func testSetAttributesOnString() {
|
||||
var value: Logger.MetadataValue = "hello"
|
||||
#expect(value.attributes[AttrA.self] == nil)
|
||||
|
||||
value.attributes = [AttrA.a1]
|
||||
|
||||
#expect(value.description == "hello")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Set attributes replaces existing attributes")
|
||||
func testSetAttributesReplacesExisting() {
|
||||
var value: Logger.MetadataValue = .attributed("test", attributes: [AttrA.a1])
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
|
||||
let newAttrs: Logger.MetadataValueAttributes = [AttrB.b2]
|
||||
value.attributes = newAttrs
|
||||
|
||||
#expect(value.description == "test")
|
||||
#expect(value.attributes[AttrA.self] == nil)
|
||||
#expect(value.attributes[AttrB.self] == .b2)
|
||||
}
|
||||
|
||||
// MARK: - Intermediate handler modifies attributes
|
||||
|
||||
@Test("Intermediate handler adds attributes before forwarding")
|
||||
func testIntermediateHandlerAddsAttributes() {
|
||||
let recorder = AttributeRecorder()
|
||||
let inner = AttributeRecordingHandler(recorder: recorder)
|
||||
let enriching = AttributeEnrichingHandler(wrapping: inner)
|
||||
|
||||
var logger = Logger(label: "test") { _ in enriching }
|
||||
logger.logLevel = .trace
|
||||
|
||||
logger.info(
|
||||
"event",
|
||||
metadata: [
|
||||
"tagged": .attributed(42, attributes: [AttrA.a1]),
|
||||
"plain": "no-attrs",
|
||||
]
|
||||
)
|
||||
|
||||
#expect(recorder.messages.count == 1)
|
||||
let metadata = recorder.messages[0]
|
||||
|
||||
// The enriching handler should have added AttrB to all values
|
||||
#expect(metadata["tagged"]?.attributes[AttrA.self] == .a1)
|
||||
#expect(metadata["tagged"]?.attributes[AttrB.self] == .b1)
|
||||
#expect(metadata["plain"]?.attributes[AttrB.self] == .b1)
|
||||
}
|
||||
|
||||
@Test("Intermediate handler replaces attributes before forwarding")
|
||||
func testIntermediateHandlerReplacesAttributes() {
|
||||
let recorder = AttributeRecorder()
|
||||
let inner = AttributeRecordingHandler(recorder: recorder)
|
||||
let stripping = AttributeStrippingHandler(wrapping: inner)
|
||||
|
||||
var logger = Logger(label: "test") { _ in stripping }
|
||||
logger.logLevel = .trace
|
||||
|
||||
logger.info(
|
||||
"event",
|
||||
metadata: [
|
||||
"tagged": .attributed(42, attributes: [AttrA.a1])
|
||||
]
|
||||
)
|
||||
|
||||
#expect(recorder.messages.count == 1)
|
||||
let metadata = recorder.messages[0]
|
||||
|
||||
// The stripping handler should have removed all attributes
|
||||
#expect(metadata["tagged"]?.attributes[AttrA.self] == nil)
|
||||
#expect(metadata["tagged"]?.description == "42")
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Test Helpers for intermediate handler tests
|
||||
|
||||
private final class AttributeRecorder: @unchecked Sendable {
|
||||
private let lock = Lock()
|
||||
private var _messages: [Logger.Metadata] = []
|
||||
|
||||
func record(metadata: Logger.Metadata) {
|
||||
self.lock.withLock { self._messages.append(metadata) }
|
||||
}
|
||||
|
||||
var messages: [Logger.Metadata] {
|
||||
self.lock.withLock { self._messages }
|
||||
}
|
||||
}
|
||||
|
||||
private struct AttributeRecordingHandler: LogHandler {
|
||||
var logLevel: Logger.Level = .trace
|
||||
var metadata = Logger.Metadata()
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
private let recorder: AttributeRecorder
|
||||
|
||||
init(recorder: AttributeRecorder) {
|
||||
self.recorder = recorder
|
||||
}
|
||||
|
||||
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[key] }
|
||||
set { self.metadata[key] = newValue }
|
||||
}
|
||||
|
||||
func log(event: LogEvent) {
|
||||
var merged = self.metadata
|
||||
if let eventMetadata = event.metadata {
|
||||
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
|
||||
}
|
||||
self.recorder.record(metadata: merged)
|
||||
}
|
||||
}
|
||||
|
||||
/// Intermediate handler that enriches all metadata values with AttrB before forwarding.
|
||||
private struct AttributeEnrichingHandler: LogHandler {
|
||||
var logLevel: Logger.Level {
|
||||
get { self.inner.logLevel }
|
||||
set { self.inner.logLevel = newValue }
|
||||
}
|
||||
|
||||
var metadata: Logger.Metadata {
|
||||
get { self.inner.metadata }
|
||||
set { self.inner.metadata = newValue }
|
||||
}
|
||||
|
||||
var metadataProvider: Logger.MetadataProvider? {
|
||||
get { self.inner.metadataProvider }
|
||||
set { self.inner.metadataProvider = newValue }
|
||||
}
|
||||
|
||||
private var inner: any LogHandler
|
||||
|
||||
init(wrapping inner: any LogHandler) {
|
||||
self.inner = inner
|
||||
}
|
||||
|
||||
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.inner[metadataKey: key] }
|
||||
set { self.inner[metadataKey: key] = newValue }
|
||||
}
|
||||
|
||||
func log(event: LogEvent) {
|
||||
var mutatedEvent = event
|
||||
if var eventMetadata = event.metadata {
|
||||
for (key, value) in eventMetadata {
|
||||
var attrs = value.attributes
|
||||
attrs[AttrB.self] = .b1
|
||||
eventMetadata[key]?.attributes = attrs
|
||||
}
|
||||
mutatedEvent.metadata = eventMetadata
|
||||
}
|
||||
self.inner.log(event: mutatedEvent)
|
||||
}
|
||||
}
|
||||
|
||||
/// Intermediate handler that strips all attributes before forwarding.
|
||||
private struct AttributeStrippingHandler: LogHandler {
|
||||
var logLevel: Logger.Level {
|
||||
get { self.inner.logLevel }
|
||||
set { self.inner.logLevel = newValue }
|
||||
}
|
||||
|
||||
var metadata: Logger.Metadata {
|
||||
get { self.inner.metadata }
|
||||
set { self.inner.metadata = newValue }
|
||||
}
|
||||
|
||||
var metadataProvider: Logger.MetadataProvider? {
|
||||
get { self.inner.metadataProvider }
|
||||
set { self.inner.metadataProvider = newValue }
|
||||
}
|
||||
|
||||
private var inner: any LogHandler
|
||||
|
||||
init(wrapping inner: any LogHandler) {
|
||||
self.inner = inner
|
||||
}
|
||||
|
||||
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.inner[metadataKey: key] }
|
||||
set { self.inner[metadataKey: key] = newValue }
|
||||
}
|
||||
|
||||
func log(event: LogEvent) {
|
||||
var mutatedEvent = event
|
||||
if var eventMetadata = event.metadata {
|
||||
for (key, _) in eventMetadata {
|
||||
eventMetadata[key]?.attributes = .init()
|
||||
}
|
||||
mutatedEvent.metadata = eventMetadata
|
||||
}
|
||||
self.inner.log(event: mutatedEvent)
|
||||
}
|
||||
}
|
||||
@@ -12,7 +12,7 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
@@ -26,36 +26,8 @@ import Android
|
||||
import Glibc
|
||||
#endif
|
||||
|
||||
final class MetadataProviderTest: XCTestCase {
|
||||
func testLoggingMergesOneOffMetadataWithProvidedMetadataFromExplicitlyPassed() throws {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
metadataProvider: .init {
|
||||
["common": "initial"]
|
||||
}
|
||||
)
|
||||
|
||||
let logger = Logger(
|
||||
label: #function,
|
||||
metadataProvider: .init {
|
||||
[
|
||||
"common": "provider",
|
||||
"provider": "42",
|
||||
]
|
||||
}
|
||||
)
|
||||
|
||||
logger.log(level: .info, "test", metadata: ["one-off": "42", "common": "one-off"])
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .info,
|
||||
message: "test",
|
||||
metadata: ["common": "one-off", "one-off": "42", "provider": "42"]
|
||||
)
|
||||
}
|
||||
|
||||
func testLogHandlerThatDidNotImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
struct MetadataProviderTest {
|
||||
@Test func logHandlerThatDidNotImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
#if DEBUG
|
||||
// we only emit these warnings in debug mode
|
||||
let logging = TestLogging()
|
||||
@@ -72,11 +44,11 @@ final class MetadataProviderTest: XCTestCase {
|
||||
|
||||
let countBefore = logging.history.entries.count
|
||||
handler.metadataProvider = .simpleTestProvider
|
||||
XCTAssertEqual(countBefore, logging.history.entries.count, "Should only log the warning once")
|
||||
#expect(countBefore == logging.history.entries.count, "Should only log the warning once")
|
||||
#endif
|
||||
}
|
||||
|
||||
func testLogHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
@Test func logHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
#if DEBUG
|
||||
// we only emit these warnings in debug mode
|
||||
let logging = TestLogging()
|
||||
@@ -102,13 +74,13 @@ extension Logger.MetadataProvider {
|
||||
}
|
||||
}
|
||||
|
||||
public struct LogHandlerThatDidNotImplementMetadataProviders: LogHandler {
|
||||
struct LogHandlerThatDidNotImplementMetadataProviders: LogHandler {
|
||||
let testLogging: TestLogging
|
||||
init(testLogging: TestLogging) {
|
||||
self.testLogging = testLogging
|
||||
}
|
||||
|
||||
public subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
|
||||
subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
|
||||
get {
|
||||
nil
|
||||
}
|
||||
@@ -117,38 +89,22 @@ public struct LogHandlerThatDidNotImplementMetadataProviders: LogHandler {
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logging.Logger.Metadata = [:]
|
||||
var metadata: Logging.Logger.Metadata = [:]
|
||||
|
||||
public var logLevel: Logging.Logger.Level = .trace
|
||||
var logLevel: Logging.Logger.Level = .trace
|
||||
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.testLogging.make(label: "fake").log(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
func log(event: LogEvent) {
|
||||
self.testLogging.make(label: "fake").log(event: event)
|
||||
}
|
||||
}
|
||||
|
||||
public struct LogHandlerThatDidImplementMetadataProviders: LogHandler {
|
||||
struct LogHandlerThatDidImplementMetadataProviders: LogHandler {
|
||||
let testLogging: TestLogging
|
||||
init(testLogging: TestLogging) {
|
||||
self.testLogging = testLogging
|
||||
}
|
||||
|
||||
public subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
|
||||
subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
|
||||
get {
|
||||
nil
|
||||
}
|
||||
@@ -157,29 +113,13 @@ public struct LogHandlerThatDidImplementMetadataProviders: LogHandler {
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logging.Logger.Metadata = [:]
|
||||
var metadata: Logging.Logger.Metadata = [:]
|
||||
|
||||
public var logLevel: Logging.Logger.Level = .trace
|
||||
var logLevel: Logging.Logger.Level = .trace
|
||||
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.testLogging.make(label: "fake").log(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
func log(event: LogEvent) {
|
||||
self.testLogging.make(label: "fake").log(event: event)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,349 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Foundation
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
// MARK: - Helper types covering each overload
|
||||
|
||||
/// `TextOutputStreamable & CustomStringConvertible` — exercises the most-specific overload.
|
||||
private struct StreamingAndDescribing: TextOutputStreamable, CustomStringConvertible {
|
||||
let value: Int
|
||||
var description: String { "SD(\(self.value))" }
|
||||
func write<Target: TextOutputStream>(to target: inout Target) {
|
||||
target.write(self.description)
|
||||
}
|
||||
}
|
||||
|
||||
/// `TextOutputStreamable` only — exercises the TOS-only overload. (Rare in practice.)
|
||||
private struct StreamingOnly: TextOutputStreamable {
|
||||
let value: Int
|
||||
func write<Target: TextOutputStream>(to target: inout Target) {
|
||||
target.write("SO(\(self.value))")
|
||||
}
|
||||
}
|
||||
|
||||
/// `CustomStringConvertible` only — exercises the CSC-only overload.
|
||||
private struct DescribingOnly: CustomStringConvertible {
|
||||
let value: Int
|
||||
var description: String { "DO(\(self.value))" }
|
||||
}
|
||||
|
||||
/// Neither TOS nor CSC — exercises the unconstrained fallback.
|
||||
private struct PlainStruct {
|
||||
let value: Int
|
||||
}
|
||||
|
||||
/// Non-`Sendable` reference type — exercises the unconstrained overload and verifies
|
||||
/// that the constraint relaxation in `appendInterpolation` accepts non-`Sendable` arguments.
|
||||
private final class NonSendableBox {
|
||||
var value: Int
|
||||
init(_ value: Int) { self.value = value }
|
||||
}
|
||||
|
||||
@Suite("MetadataValue String Interpolation")
|
||||
struct MetadataValueInterpolationTests {
|
||||
|
||||
// MARK: - Plain interpolation by overload overload
|
||||
|
||||
@Test("String interpolates via TOS & CSC overload")
|
||||
func plainString() {
|
||||
let value: Logger.MetadataValue = "hello \("world")"
|
||||
#expect(value.description == "hello world")
|
||||
}
|
||||
|
||||
@Test("Int interpolates via TOS & CSC overload")
|
||||
func plainInt() {
|
||||
let value: Logger.MetadataValue = "n=\(42)"
|
||||
#expect(value.description == "n=42")
|
||||
}
|
||||
|
||||
@Test("Double interpolates via TOS & CSC overload")
|
||||
func plainDouble() {
|
||||
let value: Logger.MetadataValue = "x=\(1.5)"
|
||||
#expect(value.description == "x=1.5")
|
||||
}
|
||||
|
||||
@Test("Substring interpolates via TOS & CSC overload")
|
||||
func plainSubstring() {
|
||||
let s = "hello world"
|
||||
let value: Logger.MetadataValue = "\(s.dropFirst(6))"
|
||||
#expect(value.description == "world")
|
||||
}
|
||||
|
||||
@Test("Custom TOS & CSC type uses the most-specific overload")
|
||||
func plainStreamingAndDescribing() {
|
||||
let value: Logger.MetadataValue = "\(StreamingAndDescribing(value: 7))"
|
||||
#expect(value.description == "SD(7)")
|
||||
}
|
||||
|
||||
@Test("TOS-only type interpolates via the TOS overload")
|
||||
func plainStreamingOnly() {
|
||||
let value: Logger.MetadataValue = "\(StreamingOnly(value: 9))"
|
||||
#expect(value.description == "SO(9)")
|
||||
}
|
||||
|
||||
@Test("CSC-only type interpolates via .description")
|
||||
func plainDescribingOnly() {
|
||||
let value: Logger.MetadataValue = "\(DescribingOnly(value: 3))"
|
||||
#expect(value.description == "DO(3)")
|
||||
}
|
||||
|
||||
@Test("Array (CSC, not TOS) interpolates via .description")
|
||||
func plainArray() {
|
||||
let value: Logger.MetadataValue = "\([1, 2, 3])"
|
||||
#expect(value.description == "[1, 2, 3]")
|
||||
}
|
||||
|
||||
@Test("Foundation.Data (CSC) interpolates via .description")
|
||||
func plainData() {
|
||||
let data = Data([0x41, 0x42])
|
||||
let value: Logger.MetadataValue = "\(data)"
|
||||
#expect(value.description == data.description)
|
||||
}
|
||||
|
||||
@Test("Plain struct (no CSC, no TOS) falls through to String(describing:)")
|
||||
func plainPlainStruct() {
|
||||
let value: Logger.MetadataValue = "\(PlainStruct(value: 5))"
|
||||
#expect(value.description == String(describing: PlainStruct(value: 5)))
|
||||
}
|
||||
|
||||
@Test("Non-Sendable class falls through to String(describing:) and compiles")
|
||||
func plainNonSendable() {
|
||||
let box = NonSendableBox(11)
|
||||
let value: Logger.MetadataValue = "\(box)"
|
||||
#expect(value.description == String(describing: box))
|
||||
}
|
||||
|
||||
// MARK: - Optional interpolation with a default
|
||||
|
||||
@Test("nil optional uses the default string")
|
||||
func defaultNil() {
|
||||
let value: Int? = nil
|
||||
let result: Logger.MetadataValue = "\(value, default: "none")"
|
||||
#expect(result.description == "none")
|
||||
}
|
||||
|
||||
@Test("non-nil optional interpolates the wrapped value")
|
||||
func defaultSome() {
|
||||
let value: Int? = 42
|
||||
let result: Logger.MetadataValue = "\(value, default: "none")"
|
||||
#expect(result.description == "42")
|
||||
}
|
||||
|
||||
@Test("nil optional of a TOS-only type uses the default")
|
||||
func defaultNilStreamingOnly() {
|
||||
let value: StreamingOnly? = nil
|
||||
let result: Logger.MetadataValue = "\(value, default: "missing")"
|
||||
#expect(result.description == "missing")
|
||||
}
|
||||
|
||||
@Test("non-nil optional of a CSC-only type interpolates via .description")
|
||||
func defaultSomeDescribingOnly() {
|
||||
let value: DescribingOnly? = DescribingOnly(value: 3)
|
||||
let result: Logger.MetadataValue = "\(value, default: "missing")"
|
||||
#expect(result.description == "DO(3)")
|
||||
}
|
||||
|
||||
@Test("nil optional of a non-CSC, non-TOS type uses the default")
|
||||
func defaultNilUnconstrained() {
|
||||
let value: PlainStruct? = nil
|
||||
let result: Logger.MetadataValue = "\(value, default: "absent")"
|
||||
#expect(result.description == "absent")
|
||||
}
|
||||
|
||||
@Test("default accepts a Substring (some StringProtocol)")
|
||||
func defaultSubstring() {
|
||||
let value: Int? = nil
|
||||
let fallback = "n/a value".dropFirst(4)
|
||||
let result: Logger.MetadataValue = "\(value, default: fallback)"
|
||||
#expect(result.description == "value")
|
||||
}
|
||||
|
||||
@Test("default segment mixed with plain segments")
|
||||
func defaultMultiSegment() {
|
||||
let name: String? = nil
|
||||
let result: Logger.MetadataValue = "user=\(name, default: "anon") id=\(42)"
|
||||
#expect(result.description == "user=anon id=42")
|
||||
}
|
||||
|
||||
@Test("default interpolation yields .string case")
|
||||
func defaultYieldsStringCase() {
|
||||
let value: Int? = nil
|
||||
let result: Logger.MetadataValue = "\(value, default: "none")"
|
||||
if case .string(let s) = result {
|
||||
#expect(s == "none")
|
||||
} else {
|
||||
Issue.record("Expected .string case, got \(result)")
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Overloaded return types
|
||||
|
||||
@Test("Overloaded function returning String/Data/[UInt8] disambiguates to String")
|
||||
func overloadedReturnTypeAmbiguity() {
|
||||
func someFunc() -> String { "from-string" }
|
||||
func someFunc() -> Data { Data([0x00]) }
|
||||
func someFunc() -> [UInt8] { [0xFF] }
|
||||
|
||||
// Without the TOS & CSC overload this would fail with "ambiguous use of 'someFunc()'".
|
||||
// String wins because it's TOS & CSC; Data and [UInt8] are CSC-only.
|
||||
let value: Logger.MetadataValue = "\(someFunc())"
|
||||
#expect(value.description == "from-string")
|
||||
}
|
||||
|
||||
// MARK: - Closure-attribute interpolation
|
||||
|
||||
@Test("Closure attributes attach to a TOS & CSC value")
|
||||
func closureAttrsTOSAndCSC() {
|
||||
let value: Logger.MetadataValue = "\(42, attributes: { $0[AttrA.self] = .a1 })"
|
||||
#expect(value.description == "42")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Closure attributes attach to a CSC-only value")
|
||||
func closureAttrsCSC() {
|
||||
let value: Logger.MetadataValue = "\(DescribingOnly(value: 1), attributes: { $0[AttrA.self] = .a1 })"
|
||||
#expect(value.description == "DO(1)")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Closure attributes attach to a TOS-only value")
|
||||
func closureAttrsTOS() {
|
||||
let value: Logger.MetadataValue = "\(StreamingOnly(value: 2), attributes: { $0[AttrA.self] = .a1 })"
|
||||
#expect(value.description == "SO(2)")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Closure attributes attach to a non-CSC, non-TOS value")
|
||||
func closureAttrsUnconstrained() {
|
||||
let s = PlainStruct(value: 4)
|
||||
let value: Logger.MetadataValue = "\(s, attributes: { $0[AttrA.self] = .a1 })"
|
||||
#expect(value.description == String(describing: s))
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Closure attributes accept a non-Sendable value")
|
||||
func closureAttrsNonSendable() {
|
||||
let box = NonSendableBox(13)
|
||||
let value: Logger.MetadataValue = "\(box, attributes: { $0[AttrA.self] = .a1 })"
|
||||
#expect(value.description == String(describing: box))
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
// MARK: - Pre-built attribute interpolation
|
||||
|
||||
@Test("Pre-built attributes attach to a TOS & CSC value")
|
||||
func valueAttrsTOSAndCSC() {
|
||||
let value: Logger.MetadataValue = "\(42, attributes: [AttrA.a1, AttrB.b2])"
|
||||
#expect(value.description == "42")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
#expect(value.attributes[AttrB.self] == .b2)
|
||||
}
|
||||
|
||||
@Test("Pre-built attributes attach to a CSC-only value")
|
||||
func valueAttrsCSC() {
|
||||
let value: Logger.MetadataValue = "\(DescribingOnly(value: 8), attributes: [AttrA.a1])"
|
||||
#expect(value.description == "DO(8)")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Pre-built attributes attach to a non-CSC value")
|
||||
func valueAttrsUnconstrained() {
|
||||
let s = PlainStruct(value: 6)
|
||||
let value: Logger.MetadataValue = "\(s, attributes: [AttrA.a1])"
|
||||
#expect(value.description == String(describing: s))
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Pre-built attributes accept a non-Sendable value")
|
||||
func valueAttrsNonSendable() {
|
||||
let box = NonSendableBox(17)
|
||||
let value: Logger.MetadataValue = "\(box, attributes: [AttrA.a1])"
|
||||
#expect(value.description == String(describing: box))
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Empty attributes still produce an attributed result")
|
||||
func valueAttrsEmpty() {
|
||||
let value: Logger.MetadataValue = "\(42, attributes: Logger.MetadataValueAttributes())"
|
||||
#expect(value.description == "42")
|
||||
// No attribute keys are set, but the carrier exists.
|
||||
#expect(value.attributes[AttrA.self] == nil)
|
||||
}
|
||||
|
||||
// MARK: - Multi-segment interpolation
|
||||
|
||||
@Test("Plain + plain segments concatenate without attributes")
|
||||
func multiPlain() {
|
||||
let value: Logger.MetadataValue = "user=\("alice") id=\(42)"
|
||||
#expect(value.description == "user=alice id=42")
|
||||
#expect(value.attributes[AttrA.self] == nil)
|
||||
}
|
||||
|
||||
@Test("Plain + attributed segments produce attributed result")
|
||||
func multiPlainAndAttributed() {
|
||||
let value: Logger.MetadataValue = "user=\("alice") action=\("login", attributes: [AttrA.a1])"
|
||||
#expect(value.description == "user=alice action=login")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
}
|
||||
|
||||
@Test("Two attributed segments merge their attributes")
|
||||
func multiAttributedMerge() {
|
||||
let value: Logger.MetadataValue = "\("a", attributes: [AttrA.a1])-\("b", attributes: [AttrB.b2])"
|
||||
#expect(value.description == "a-b")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
#expect(value.attributes[AttrB.self] == .b2)
|
||||
}
|
||||
|
||||
@Test("Closure-attributes and value-attributes segments merge")
|
||||
func multiAttributedMixed() {
|
||||
let value: Logger.MetadataValue =
|
||||
"\("x", attributes: { $0[AttrA.self] = .a1 })-\("y", attributes: [AttrB.b2])"
|
||||
#expect(value.description == "x-y")
|
||||
#expect(value.attributes[AttrA.self] == .a1)
|
||||
#expect(value.attributes[AttrB.self] == .b2)
|
||||
}
|
||||
|
||||
@Test("Conflicting attribute keys: later segment wins")
|
||||
func multiAttributedConflict() {
|
||||
let value: Logger.MetadataValue =
|
||||
"\("a", attributes: [AttrA.a1])-\("b", attributes: [AttrA.a2])"
|
||||
#expect(value.description == "a-b")
|
||||
#expect(value.attributes[AttrA.self] == .a2)
|
||||
}
|
||||
|
||||
// MARK: - Result-case discrimination
|
||||
|
||||
@Test("Plain interpolation yields .string case")
|
||||
func plainYieldsStringCase() {
|
||||
let value: Logger.MetadataValue = "\(42)"
|
||||
if case .string(let s) = value {
|
||||
#expect(s == "42")
|
||||
} else {
|
||||
Issue.record("Expected .string case, got \(value)")
|
||||
}
|
||||
}
|
||||
|
||||
@Test("Attributed interpolation yields .stringConvertible case")
|
||||
func attributedYieldsStringConvertibleCase() {
|
||||
let value: Logger.MetadataValue = "\(42, attributes: [AttrA.a1])"
|
||||
if case .stringConvertible = value {
|
||||
// ok
|
||||
} else {
|
||||
Issue.record("Expected .stringConvertible case, got \(value)")
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,357 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Foundation
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif os(Windows)
|
||||
import WinSDK
|
||||
#elseif canImport(Android)
|
||||
import Android
|
||||
#else
|
||||
import Glibc
|
||||
#endif
|
||||
|
||||
struct StreamLogHandlerTest {
|
||||
final class InterceptStream: TextOutputStream {
|
||||
var interceptedText: String?
|
||||
var strings = [String]()
|
||||
|
||||
func write(_ string: String) {
|
||||
// This is a test implementation, a real implementation would include locking
|
||||
self.strings.append(string)
|
||||
self.interceptedText = (self.interceptedText ?? "") + string
|
||||
}
|
||||
}
|
||||
|
||||
@Test func streamLogHandlerWritesToAStream() {
|
||||
let interceptStream = InterceptStream()
|
||||
let log = Logger(
|
||||
label: "test",
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: interceptStream)
|
||||
}
|
||||
)
|
||||
|
||||
let testString = "my message is better than yours"
|
||||
log.critical("\(testString)")
|
||||
|
||||
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
.hasSuffix(testString)
|
||||
|
||||
#expect(messageSucceeded ?? false)
|
||||
#expect(interceptStream.strings.count == 1)
|
||||
}
|
||||
|
||||
@Test func streamLogHandlerOutputFormat() {
|
||||
let interceptStream = InterceptStream()
|
||||
let label = "testLabel"
|
||||
let source = "testSource"
|
||||
let log = Logger(
|
||||
label: label,
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: interceptStream)
|
||||
}
|
||||
)
|
||||
|
||||
let testString = "my message is better than yours"
|
||||
log.critical("\(testString)", source: source)
|
||||
|
||||
let pattern =
|
||||
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label):\\s\\[\(source)\\]\\s\(testString)$"
|
||||
|
||||
let messageSucceeded =
|
||||
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
|
||||
of: pattern,
|
||||
options: .regularExpression
|
||||
) != nil
|
||||
|
||||
#expect(messageSucceeded)
|
||||
#expect(interceptStream.strings.count == 1)
|
||||
}
|
||||
|
||||
@Test func streamLogHandlerOutputFormatWithEmptyLabel() {
|
||||
let interceptStream = InterceptStream()
|
||||
let source = "testSource"
|
||||
let log = Logger(
|
||||
label: "",
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: interceptStream)
|
||||
}
|
||||
)
|
||||
|
||||
let testString = "my message is better than yours"
|
||||
log.critical("\(testString)", source: source)
|
||||
|
||||
let pattern =
|
||||
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical):\\s\\[\(source)\\]\\s\(testString)$"
|
||||
|
||||
let messageSucceeded =
|
||||
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
|
||||
of: pattern,
|
||||
options: .regularExpression
|
||||
) != nil
|
||||
|
||||
#expect(messageSucceeded)
|
||||
#expect(interceptStream.strings.count == 1)
|
||||
}
|
||||
|
||||
@Test func streamLogHandlerOutputFormatWithMetaData() {
|
||||
let interceptStream = InterceptStream()
|
||||
let label = "testLabel"
|
||||
let source = "testSource"
|
||||
let log = Logger(
|
||||
label: label,
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: interceptStream)
|
||||
}
|
||||
)
|
||||
|
||||
let testString = "my message is better than yours"
|
||||
log.critical("\(testString)", metadata: ["test": "test"], source: source)
|
||||
|
||||
let pattern =
|
||||
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label):\\stest=test\\s\\[\(source)\\]\\s\(testString)$"
|
||||
|
||||
let messageSucceeded =
|
||||
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
|
||||
of: pattern,
|
||||
options: .regularExpression
|
||||
) != nil
|
||||
|
||||
#expect(messageSucceeded)
|
||||
#expect(interceptStream.strings.count == 1)
|
||||
}
|
||||
|
||||
@Test func streamLogHandlerOutputFormatWithOrderedMetadata() {
|
||||
let interceptStream = InterceptStream()
|
||||
let log = Logger(
|
||||
label: "testLabel",
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: interceptStream)
|
||||
}
|
||||
)
|
||||
|
||||
let testString = "my message is better than yours"
|
||||
log.critical("\(testString)", metadata: ["a": "a0", "b": "b0"])
|
||||
log.critical("\(testString)", metadata: ["b": "b1", "a": "a1"])
|
||||
|
||||
#expect(interceptStream.strings.count == 2)
|
||||
guard interceptStream.strings.count == 2 else {
|
||||
Issue.record("Intercepted \(interceptStream.strings.count) logs, expected 2")
|
||||
return
|
||||
}
|
||||
|
||||
#expect(interceptStream.strings[0].contains("a=a0 b=b0"), "LINES: \(interceptStream.strings[0])")
|
||||
#expect(interceptStream.strings[1].contains("a=a1 b=b1"), "LINES: \(interceptStream.strings[1])")
|
||||
}
|
||||
|
||||
@Test func streamLogHandlerWritesIncludeMetadataProviderMetadata() {
|
||||
let interceptStream = InterceptStream()
|
||||
let log = Logger(
|
||||
label: "test",
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: interceptStream, metadataProvider: .exampleProvider)
|
||||
}
|
||||
)
|
||||
|
||||
let testString = "my message is better than yours"
|
||||
log.critical("\(testString)")
|
||||
|
||||
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
.hasSuffix(testString)
|
||||
|
||||
#expect(messageSucceeded ?? false)
|
||||
#expect(interceptStream.strings.count == 1)
|
||||
let message = interceptStream.strings.first!
|
||||
#expect(message.contains("example=example-value"), "message must contain metadata, was: \(message)")
|
||||
}
|
||||
|
||||
@Test func stdioOutputStreamWrite() {
|
||||
self.withWriteReadFDsAndReadBuffer(flushMode: .always) { logStream, readFD, readBuffer in
|
||||
let log = Logger(
|
||||
label: "test",
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: logStream)
|
||||
}
|
||||
)
|
||||
let testString = "hello\u{0} world"
|
||||
log.critical("\(testString)")
|
||||
|
||||
#if os(Windows)
|
||||
let size = _read(readFD, readBuffer, 256)
|
||||
#else
|
||||
let size = read(readFD, readBuffer, 256)
|
||||
#endif
|
||||
|
||||
let output = String(
|
||||
decoding: UnsafeRawBufferPointer(start: UnsafeRawPointer(readBuffer), count: numericCast(size)),
|
||||
as: UTF8.self
|
||||
)
|
||||
let messageSucceeded = output.trimmingCharacters(in: .whitespacesAndNewlines).hasSuffix(testString)
|
||||
#expect(messageSucceeded)
|
||||
}
|
||||
}
|
||||
|
||||
@Test func stdioOutputStreamFlush() {
|
||||
// flush on every statement
|
||||
self.withWriteReadFDsAndReadBuffer(flushMode: .always) { logStream, readFD, readBuffer in
|
||||
Logger(
|
||||
label: "test",
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: logStream)
|
||||
}
|
||||
).critical("test")
|
||||
|
||||
#if os(Windows)
|
||||
let size = _read(readFD, readBuffer, 256)
|
||||
#else
|
||||
let size = read(readFD, readBuffer, 256)
|
||||
#endif
|
||||
#expect(size > -1, "expected flush")
|
||||
|
||||
logStream.flush()
|
||||
|
||||
#if os(Windows)
|
||||
let size2 = _read(readFD, readBuffer, 256)
|
||||
#else
|
||||
let size2 = read(readFD, readBuffer, 256)
|
||||
#endif
|
||||
#expect(size2 == -1, "expected no flush")
|
||||
}
|
||||
// default flushing
|
||||
self.withWriteReadFDsAndReadBuffer(flushMode: .undefined) { logStream, readFD, readBuffer in
|
||||
Logger(
|
||||
label: "test",
|
||||
factory: {
|
||||
StreamLogHandler(label: $0, stream: logStream)
|
||||
}
|
||||
).critical("test")
|
||||
|
||||
#if os(Windows)
|
||||
let size = _read(readFD, readBuffer, 256)
|
||||
#else
|
||||
let size = read(readFD, readBuffer, 256)
|
||||
#endif
|
||||
#expect(size == -1, "expected no flush")
|
||||
|
||||
logStream.flush()
|
||||
|
||||
#if os(Windows)
|
||||
let size2 = _read(readFD, readBuffer, 256)
|
||||
#else
|
||||
let size2 = read(readFD, readBuffer, 256)
|
||||
#endif
|
||||
#expect(size2 > -1, "expected flush")
|
||||
}
|
||||
}
|
||||
|
||||
func withWriteReadFDsAndReadBuffer(
|
||||
flushMode: StdioOutputStream.FlushMode,
|
||||
_ body: (StdioOutputStream, CInt, UnsafeMutablePointer<Int8>) -> Void
|
||||
) {
|
||||
var fds: [Int32] = [-1, -1]
|
||||
#if os(Windows)
|
||||
fds.withUnsafeMutableBufferPointer {
|
||||
let err = _pipe($0.baseAddress, 256, _O_BINARY)
|
||||
#expect(err == 0, "_pipe failed \(err)")
|
||||
}
|
||||
guard let writeFD = _fdopen(fds[1], "w") else {
|
||||
Issue.record("Failed to open file")
|
||||
return
|
||||
}
|
||||
#else
|
||||
fds.withUnsafeMutableBufferPointer { ptr in
|
||||
let err = pipe(ptr.baseAddress!)
|
||||
#expect(err == 0, "pipe failed \(err)")
|
||||
}
|
||||
guard let writeFD = fdopen(fds[1], "w") else {
|
||||
Issue.record("Failed to open file")
|
||||
return
|
||||
}
|
||||
#endif
|
||||
|
||||
let writeBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
|
||||
defer {
|
||||
writeBuffer.deinitialize(count: 256)
|
||||
writeBuffer.deallocate()
|
||||
}
|
||||
|
||||
var err = setvbuf(writeFD, writeBuffer, _IOFBF, 256)
|
||||
#expect(err == 0, "setvbuf failed \(err)")
|
||||
|
||||
// Create the stream here while writeFD's concrete type is in scope.
|
||||
// Type inference in the generic StdioOutputStream init picks the right
|
||||
// C functions for whatever FILE representation this platform/API level uses.
|
||||
#if os(Windows)
|
||||
let stream = StdioOutputStream(
|
||||
file: writeFD,
|
||||
flushMode: flushMode,
|
||||
lock: _lock_file,
|
||||
unlock: _unlock_file,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#else
|
||||
let stream = StdioOutputStream(
|
||||
file: writeFD,
|
||||
flushMode: flushMode,
|
||||
lock: flockfile,
|
||||
unlock: funlockfile,
|
||||
write: fwrite,
|
||||
flush: fflush
|
||||
)
|
||||
#endif
|
||||
|
||||
let readFD = fds[0]
|
||||
#if os(Windows)
|
||||
let hPipe: HANDLE = HANDLE(bitPattern: _get_osfhandle(readFD))!
|
||||
#expect(hPipe != INVALID_HANDLE_VALUE)
|
||||
|
||||
var dwMode: DWORD = DWORD(PIPE_NOWAIT)
|
||||
let bSucceeded = SetNamedPipeHandleState(hPipe, &dwMode, nil, nil)
|
||||
#expect(bSucceeded)
|
||||
#else
|
||||
err = fcntl(readFD, F_SETFL, fcntl(readFD, F_GETFL) | O_NONBLOCK)
|
||||
#expect(err == 0, "fcntl failed \(err)")
|
||||
#endif
|
||||
|
||||
let readBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
|
||||
defer {
|
||||
readBuffer.deinitialize(count: 256)
|
||||
readBuffer.deallocate()
|
||||
}
|
||||
|
||||
// the actual test
|
||||
body(stream, readFD, readBuffer)
|
||||
|
||||
for fd in fds {
|
||||
#if os(Windows)
|
||||
_close(fd)
|
||||
#else
|
||||
close(fd)
|
||||
#endif
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Sendable
|
||||
|
||||
// used to test logging stream which requires Sendable conformance
|
||||
// @unchecked Sendable since manages it own state
|
||||
extension StreamLogHandlerTest.InterceptStream: @unchecked Sendable {}
|
||||
@@ -0,0 +1,76 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
struct SwiftLogNoOpLogHandlerTest {
|
||||
@Test func initWithNoArguments() {
|
||||
let handler = SwiftLogNoOpLogHandler()
|
||||
#expect(handler.logLevel == .critical)
|
||||
#expect(handler.metadata == [:])
|
||||
}
|
||||
|
||||
@Test func initWithLabel() {
|
||||
let handler = SwiftLogNoOpLogHandler("some.label")
|
||||
#expect(handler.logLevel == .critical)
|
||||
#expect(handler.metadata == [:])
|
||||
}
|
||||
|
||||
@Test func logLevelIgnoresMutations() {
|
||||
var handler = SwiftLogNoOpLogHandler()
|
||||
handler.logLevel = .trace
|
||||
#expect(handler.logLevel == .critical)
|
||||
}
|
||||
|
||||
@Test func metadataIgnoresMutations() {
|
||||
var handler = SwiftLogNoOpLogHandler()
|
||||
handler.metadata = ["key": "value"]
|
||||
#expect(handler.metadata == [:])
|
||||
}
|
||||
|
||||
@Test func metadataSubscriptAlwaysReturnsNil() {
|
||||
var handler = SwiftLogNoOpLogHandler()
|
||||
#expect(handler[metadataKey: "key"] == nil)
|
||||
handler[metadataKey: "key"] = "value"
|
||||
#expect(handler[metadataKey: "key"] == nil)
|
||||
}
|
||||
|
||||
@Test func logEventDoesNotCrash() {
|
||||
let handler = SwiftLogNoOpLogHandler()
|
||||
let event = LogEvent(
|
||||
level: .critical,
|
||||
message: "message",
|
||||
metadata: ["key": "value"],
|
||||
source: "test",
|
||||
file: #file,
|
||||
function: #function,
|
||||
line: #line
|
||||
)
|
||||
handler.log(event: event)
|
||||
}
|
||||
|
||||
@Test func allLogLevelsDoNotCrash() {
|
||||
var logger = Logger(label: "noop.test", factory: { _ in SwiftLogNoOpLogHandler() })
|
||||
logger[metadataKey: "key"] = "value"
|
||||
logger.trace("trace message")
|
||||
logger.debug("debug message")
|
||||
logger.info("info message")
|
||||
logger.notice("notice message")
|
||||
logger.warning("warning message")
|
||||
logger.error("error message")
|
||||
logger.critical("critical message")
|
||||
}
|
||||
}
|
||||
@@ -12,21 +12,17 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Dispatch
|
||||
import Foundation
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if os(Windows)
|
||||
import WinSDK
|
||||
#endif
|
||||
#if compiler(>=6.0) || canImport(Darwin)
|
||||
import Dispatch
|
||||
#else
|
||||
@preconcurrency import Dispatch
|
||||
#endif
|
||||
|
||||
internal struct TestLogging {
|
||||
struct TestLogging {
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
|
||||
@@ -58,7 +54,7 @@ internal struct TestLogHandler: LogHandler {
|
||||
private var logger: Logger // the actual logger
|
||||
|
||||
let label: String
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
init(label: String, config: Config, recorder: Recorder, metadataProvider: Logger.MetadataProvider?) {
|
||||
self.label = label
|
||||
@@ -78,15 +74,7 @@ internal struct TestLogHandler: LogHandler {
|
||||
self.metadataProvider = LoggingSystem.metadataProvider
|
||||
}
|
||||
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata explicitMetadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
func log(event: LogEvent) {
|
||||
// baseline metadata, that was set on handler:
|
||||
var metadata = self._metadataSet ? self.metadata : MDC.global.metadata
|
||||
// contextual metadata, e.g. from task-locals:
|
||||
@@ -95,20 +83,27 @@ internal struct TestLogHandler: LogHandler {
|
||||
metadata.merge(contextualMetadata, uniquingKeysWith: { _, contextual in contextual })
|
||||
}
|
||||
// override using any explicit metadata passed for this log statement:
|
||||
if let explicitMetadata = explicitMetadata {
|
||||
if let explicitMetadata = event.metadata {
|
||||
metadata.merge(explicitMetadata, uniquingKeysWith: { _, explicit in explicit })
|
||||
}
|
||||
|
||||
self.logger.log(
|
||||
level: level,
|
||||
message,
|
||||
level: event.level,
|
||||
event.message,
|
||||
error: event.error,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
source: event.source,
|
||||
file: event.file,
|
||||
function: event.function,
|
||||
line: event.line
|
||||
)
|
||||
self.recorder.record(
|
||||
level: event.level,
|
||||
metadata: metadata,
|
||||
message: event.message,
|
||||
error: event.error,
|
||||
source: event.source
|
||||
)
|
||||
self.recorder.record(level: level, metadata: metadata, message: message, source: source)
|
||||
}
|
||||
|
||||
private var _logLevel: Logger.Level?
|
||||
@@ -129,7 +124,7 @@ internal struct TestLogHandler: LogHandler {
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logger.Metadata {
|
||||
var metadata: Logger.Metadata {
|
||||
get {
|
||||
self._metadata
|
||||
}
|
||||
@@ -179,10 +174,42 @@ internal class Recorder: History {
|
||||
private let lock = NSLock()
|
||||
private var _entries = [LogEntry]()
|
||||
|
||||
func record(level: Logger.Level, metadata: Logger.Metadata?, message: Logger.Message, source: String) {
|
||||
func record(
|
||||
level: Logger.Level,
|
||||
metadata: Logger.Metadata?,
|
||||
message: Logger.Message,
|
||||
error: (any Error)? = nil,
|
||||
source: String
|
||||
) {
|
||||
self.lock.withLock {
|
||||
self._entries.append(
|
||||
LogEntry(level: level, metadata: metadata, message: message.description, source: source)
|
||||
LogEntry(level: level, metadata: metadata, message: message.description, error: error, source: source)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
func record(
|
||||
level: Logger.Level,
|
||||
metadata: Logger.Metadata?,
|
||||
message: Logger.Message,
|
||||
error: (any Error)? = nil,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.lock.withLock {
|
||||
self._entries.append(
|
||||
LogEntry(
|
||||
level: level,
|
||||
metadata: metadata,
|
||||
message: message.description,
|
||||
error: error,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -228,49 +255,81 @@ internal struct LogEntry {
|
||||
let level: Logger.Level
|
||||
let metadata: Logger.Metadata?
|
||||
let message: String
|
||||
let error: (any Error)?
|
||||
let source: String
|
||||
let file: String
|
||||
let function: String
|
||||
let line: UInt
|
||||
|
||||
init(
|
||||
level: Logger.Level,
|
||||
metadata: Logger.Metadata?,
|
||||
message: String,
|
||||
error: (any Error)?,
|
||||
source: String,
|
||||
file: String = "",
|
||||
function: String = "",
|
||||
line: UInt = 0
|
||||
) {
|
||||
self.level = level
|
||||
self.metadata = metadata
|
||||
self.message = message
|
||||
self.error = error
|
||||
self.source = source
|
||||
self.file = file
|
||||
self.function = function
|
||||
self.line = line
|
||||
}
|
||||
}
|
||||
|
||||
extension History {
|
||||
func assertExist(
|
||||
level: Logger.Level,
|
||||
message: String,
|
||||
error: (any Error)? = nil,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #filePath,
|
||||
file: String = #filePath,
|
||||
fileID: String = #fileID,
|
||||
line: UInt = #line
|
||||
line: Int = #line,
|
||||
column: Int = #column
|
||||
) {
|
||||
let source = source ?? Logger.currentModule(fileID: "\(fileID)")
|
||||
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
|
||||
XCTAssertNotNil(
|
||||
entry,
|
||||
"entry not found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file,
|
||||
line: line
|
||||
let entry = self.find(level: level, message: message, error: error, metadata: metadata, source: source)
|
||||
#expect(
|
||||
entry != nil,
|
||||
"entry not found: \(level), \(source), \(String(describing: metadata)), \(message), \(String(describing: error))",
|
||||
sourceLocation: SourceLocation(fileID: fileID, filePath: file, line: line, column: column)
|
||||
)
|
||||
}
|
||||
|
||||
func assertNotExist(
|
||||
level: Logger.Level,
|
||||
message: String,
|
||||
error: (any Error)? = nil,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #filePath,
|
||||
file: String = #filePath,
|
||||
fileID: String = #file,
|
||||
line: UInt = #line
|
||||
line: Int = #line,
|
||||
column: Int = #column
|
||||
) {
|
||||
let source = source ?? Logger.currentModule(fileID: "\(fileID)")
|
||||
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
|
||||
XCTAssertNil(
|
||||
entry,
|
||||
"entry was found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file,
|
||||
line: line
|
||||
let entry = self.find(level: level, message: message, error: error, metadata: metadata, source: source)
|
||||
#expect(
|
||||
entry == nil,
|
||||
"entry was found: \(level), \(source), \(String(describing: metadata)), \(message), \(String(describing: error))",
|
||||
sourceLocation: SourceLocation(fileID: fileID, filePath: file, line: line, column: column)
|
||||
)
|
||||
}
|
||||
|
||||
func find(level: Logger.Level, message: String, metadata: Logger.Metadata? = nil, source: String) -> LogEntry? {
|
||||
func find(
|
||||
level: Logger.Level,
|
||||
message: String,
|
||||
error: (any Error)? = nil,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String
|
||||
) -> LogEntry? {
|
||||
self.entries.first { entry in
|
||||
if entry.level != level {
|
||||
return false
|
||||
@@ -278,6 +337,9 @@ extension History {
|
||||
if entry.message != message {
|
||||
return false
|
||||
}
|
||||
if !errorsEqual(error, entry.error) {
|
||||
return false
|
||||
}
|
||||
if let lhs = entry.metadata, let rhs = metadata {
|
||||
if lhs.count != rhs.count {
|
||||
return false
|
||||
@@ -304,17 +366,29 @@ extension History {
|
||||
return true
|
||||
}
|
||||
}
|
||||
|
||||
private func errorsEqual(_ lhs: (any Error)?, _ rhs: (any Error)?) -> Bool {
|
||||
switch (lhs, rhs) {
|
||||
case (nil, nil):
|
||||
return true
|
||||
case let (l?, r?):
|
||||
return "\(l)" == "\(r)" && String(reflecting: type(of: l)) == String(reflecting: type(of: r))
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public class MDC {
|
||||
/// MDC stands for Mapped Diagnostic Context
|
||||
class MDC {
|
||||
private let lock = NSLock()
|
||||
private var storage = [Int: Logger.Metadata]()
|
||||
|
||||
public static let global = MDC()
|
||||
static let global = MDC()
|
||||
|
||||
private init() {}
|
||||
|
||||
public subscript(metadataKey: String) -> Logger.Metadata.Value? {
|
||||
subscript(metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self.lock.withLock {
|
||||
self.storage[self.threadId]?[metadataKey]
|
||||
@@ -330,19 +404,19 @@ public class MDC {
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logger.Metadata {
|
||||
var metadata: Logger.Metadata {
|
||||
self.lock.withLock {
|
||||
self.storage[self.threadId] ?? [:]
|
||||
}
|
||||
}
|
||||
|
||||
public func clear() {
|
||||
func clear() {
|
||||
self.lock.withLock {
|
||||
_ = self.storage.removeValue(forKey: self.threadId)
|
||||
}
|
||||
}
|
||||
|
||||
public func with(metadata: Logger.Metadata, _ body: () throws -> Void) rethrows {
|
||||
func with(metadata: Logger.Metadata, _ body: () throws -> Void) rethrows {
|
||||
for (key, value) in metadata {
|
||||
self[key] = value
|
||||
}
|
||||
@@ -354,7 +428,7 @@ public class MDC {
|
||||
try body()
|
||||
}
|
||||
|
||||
public func with<T>(metadata: Logger.Metadata, _ body: () throws -> T) rethrows -> T {
|
||||
func with<T>(metadata: Logger.Metadata, _ body: () throws -> T) rethrows -> T {
|
||||
for (key, value) in metadata {
|
||||
self[key] = value
|
||||
}
|
||||
@@ -378,33 +452,27 @@ public class MDC {
|
||||
return Int(pthread_mach_thread_np(pthread_self()))
|
||||
#elseif os(Windows)
|
||||
return Int(GetCurrentThreadId())
|
||||
#elseif os(FreeBSD)
|
||||
return Int(pthread_getthreadid_np())
|
||||
#elseif os(OpenBSD)
|
||||
return Int(bitPattern: pthread_self())
|
||||
#else
|
||||
return Int(pthread_self())
|
||||
#endif
|
||||
}
|
||||
}
|
||||
|
||||
extension NSLock {
|
||||
func withLock<T>(_ body: () -> T) -> T {
|
||||
self.lock()
|
||||
defer {
|
||||
self.unlock()
|
||||
}
|
||||
return body()
|
||||
}
|
||||
}
|
||||
|
||||
internal struct TestLibrary: Sendable {
|
||||
private let logger = Logger(label: "TestLibrary")
|
||||
private let queue = DispatchQueue(label: "TestLibrary")
|
||||
|
||||
public init() {}
|
||||
init() {}
|
||||
|
||||
public func doSomething() {
|
||||
func doSomething() {
|
||||
self.logger.info("TestLibrary::doSomething")
|
||||
}
|
||||
|
||||
public func doSomethingAsync(completion: @escaping @Sendable () -> Void) {
|
||||
func doSomethingAsync(completion: @escaping @Sendable () -> Void) {
|
||||
// libraries that use global loggers and async, need to make sure they propagate the
|
||||
// logging metadata when creating a new thread
|
||||
let metadata = MDC.global.metadata
|
||||
@@ -417,7 +485,7 @@ internal struct TestLibrary: Sendable {
|
||||
}
|
||||
}
|
||||
|
||||
// Sendable
|
||||
// MARK: - Sendable
|
||||
|
||||
extension TestLogHandler: @unchecked Sendable {}
|
||||
extension Recorder: @unchecked Sendable {}
|
||||
|
||||
Loaded 100 of 102 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user