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 |
No files matched your search
@@ -3,4 +3,6 @@ updates:
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
interval: "daily"
|
||||
labels:
|
||||
- "semver/none"
|
||||
@@ -31,20 +31,11 @@ jobs:
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks (NoTraits)
|
||||
name: macOS benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/NoTraits"
|
||||
macos_xcode_16_4_enabled: true
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
macos-benchmarks-MaxLogLevelWarningBenchmarks-trait:
|
||||
name: macOS benchmarks (MaxLogLevelWarning)
|
||||
needs: macos-benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
|
||||
macos_xcode_26_1_enabled: true
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
macos_swift_6_3_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
@@ -62,14 +53,6 @@ jobs:
|
||||
runner_pool: nightly
|
||||
build_scheme: swift-log-Package
|
||||
debug_output_enabled: true
|
||||
xcode_16_3_enabled: false
|
||||
xcode_16_4_enabled: false
|
||||
xcode_26_0_enabled: false
|
||||
xcode_26_1_enabled: false
|
||||
xcode_26_2_enabled: false
|
||||
swift_6_1_enabled: true
|
||||
swift_6_2_enabled: true
|
||||
swift_6_3_enabled: true
|
||||
macos_xcode_test_enabled: false
|
||||
ios_xcode_test_enabled: false
|
||||
watchos_xcode_test_enabled: false
|
||||
@@ -79,6 +62,8 @@ jobs:
|
||||
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
|
||||
|
||||
@@ -10,7 +10,7 @@ on:
|
||||
jobs:
|
||||
soundness:
|
||||
name: Soundness
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.9
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.11
|
||||
with:
|
||||
license_header_check_project_name: "Swift Logging API"
|
||||
|
||||
@@ -35,23 +35,12 @@ jobs:
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks (NoTraits)
|
||||
name: macOS benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/NoTraits"
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
macos_runner_pool: general
|
||||
macos_xcode_16_4_enabled: true
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
macos-benchmarks-MaxLogLevelWarningBenchmarks-trait:
|
||||
name: macOS benchmarks (MaxLogLevelWarning)
|
||||
# Workaround for reusing the same benchmarks.yml workflow
|
||||
needs: macos-benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
|
||||
macos_runner_pool: general
|
||||
macos_xcode_26_1_enabled: true
|
||||
macos_swift_6_3_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
@@ -88,3 +77,5 @@ jobs:
|
||||
wasm:
|
||||
name: Wasm Swift SDK
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
with:
|
||||
nightly_next_enabled: false
|
||||
@@ -5,7 +5,6 @@
|
||||
.gitattributes
|
||||
.git-blame-ignore-revs
|
||||
.mailfilter
|
||||
.mailmap
|
||||
.spi.yml
|
||||
.swift-format
|
||||
.editorconfig
|
||||
@@ -34,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,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")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 893,
|
||||
"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
|
||||
}
|
||||
+10
@@ -30,4 +30,14 @@ public let benchmarks: @Sendable () -> Void = {
|
||||
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)",
|
||||
]
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version: 6.1
|
||||
// swift-tools-version: 6.2
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 619,
|
||||
"instructions" : 662,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 662,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 619,
|
||||
"instructions" : 658,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1651,
|
||||
"instructions" : 1892,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1651,
|
||||
"instructions" : 1892,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -24,4 +24,40 @@ public let benchmarks: @Sendable () -> Void = {
|
||||
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])"
|
||||
]
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version:6.1
|
||||
// swift-tools-version:6.2
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
-4
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"instructions" : 1649,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 985,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 985,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 984,
|
||||
"instructions" : 970,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5855,
|
||||
"objectAllocCount" : 2
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 7075,
|
||||
"objectAllocCount" : 3
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1368,
|
||||
"instructions" : 1890,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version:6.1
|
||||
// swift-tools-version:6.2
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
@@ -39,7 +39,7 @@ public func makeBenchmark(
|
||||
thresholds: [
|
||||
.instructions: BenchmarkThresholds(
|
||||
relative: [
|
||||
.p90: 1.0 // we only record p90
|
||||
.p90: 10.0 // we only record p90
|
||||
]
|
||||
),
|
||||
.objectAllocCount: BenchmarkThresholds(
|
||||
|
||||
@@ -14,6 +14,40 @@
|
||||
|
||||
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?
|
||||
@@ -31,6 +65,13 @@ struct NoOpLogHandler: LogHandler {
|
||||
func log(
|
||||
event: LogEvent
|
||||
) {
|
||||
// Access metadata attributes
|
||||
if let metadata = event.metadata {
|
||||
for (_, value) in metadata {
|
||||
let _ = value.attributes
|
||||
}
|
||||
}
|
||||
|
||||
// Do nothing
|
||||
}
|
||||
|
||||
@@ -43,6 +84,13 @@ struct NoOpLogHandler: LogHandler {
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
// Access metadata attributes
|
||||
if let metadata = explicitMetadata {
|
||||
for (_, value) in metadata {
|
||||
let _ = value.attributes
|
||||
}
|
||||
}
|
||||
|
||||
// Do nothing
|
||||
}
|
||||
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
# Code of Conduct
|
||||
|
||||
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
|
||||
+10
-20
@@ -45,28 +45,11 @@ 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
|
||||
|
||||
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.
|
||||
|
||||
A good SwiftLog patch is:
|
||||
|
||||
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.
|
||||
|
||||
### Commit Message Template
|
||||
|
||||
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
|
||||
## Make sure Tests work on Linux
|
||||
|
||||
SwiftLog uses Swift Testing to run tests on all supported platforms.
|
||||
|
||||
### Run CI checks locally
|
||||
## Run CI checks locally
|
||||
|
||||
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
|
||||
@@ -117,7 +100,14 @@ For more information please refer to `swift package benchmark --help` or the [do
|
||||
|
||||
## 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
|
||||
|
||||
@@ -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`
|
||||
@@ -1,17 +1,4 @@
|
||||
// swift-tools-version:6.2
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 PackageDescription
|
||||
|
||||
|
||||
@@ -1,17 +1,4 @@
|
||||
// swift-tools-version:6.1
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 PackageDescription
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -57,18 +57,23 @@ public struct InMemoryLogHandler: LogHandler {
|
||||
self.metadata = metadata
|
||||
}
|
||||
|
||||
public init(level: Logger.Level, message: Logger.Message, error: (any Error)?, metadata: Logger.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: InMemoryLogHandler.Entry, rhs: InMemoryLogHandler.Entry) -> Bool {
|
||||
public static func == (lhs: Entry, rhs: Entry) -> Bool {
|
||||
lhs.level == rhs.level
|
||||
&& lhs.message == rhs.message
|
||||
&& errorsEqual(lhs.error, rhs.error)
|
||||
&& lhs.metadata == rhs.metadata
|
||||
&& errorsEqual(lhs.error, rhs.error)
|
||||
}
|
||||
|
||||
private static func errorsEqual(_ lhs: (any Error)?, _ rhs: (any Error)?) -> Bool {
|
||||
@@ -126,14 +131,23 @@ public struct InMemoryLogHandler: LogHandler {
|
||||
}
|
||||
|
||||
public func log(event: LogEvent) {
|
||||
// Start with the metadata provider..
|
||||
var mergedMetadata: Logger.Metadata = self.metadataProvider?.get() ?? [:]
|
||||
// ..merge in self.metadata, overwriting existing keys
|
||||
mergedMetadata = mergedMetadata.merging(self.metadata) { $1 }
|
||||
// ..merge in metadata from this log call, overwriting existing keys
|
||||
mergedMetadata = mergedMetadata.merging(event.metadata ?? [:]) { $1 }
|
||||
var merged = self.metadata
|
||||
|
||||
self.logStore.append(level: event.level, message: event.message, error: event.error, metadata: mergedMetadata)
|
||||
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:)")
|
||||
|
||||
@@ -3,7 +3,9 @@
|
||||
SwiftLog provides compile-time traits to eliminate less severe log levels from
|
||||
your binary reducing the runtime overhead.
|
||||
|
||||
## Motivation
|
||||
## 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
|
||||
@@ -11,7 +13,7 @@ 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
|
||||
### Available traits
|
||||
|
||||
SwiftLog defines seven maximum log level traits, ordered from most permissive
|
||||
to most restrictive:
|
||||
@@ -39,7 +41,7 @@ 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
|
||||
### Example
|
||||
|
||||
To enable a trait, specify it when declaring your package dependency:
|
||||
|
||||
@@ -71,3 +73,12 @@ 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.
|
||||
@@ -23,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)
|
||||
@@ -51,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]
|
||||
@@ -128,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]
|
||||
@@ -199,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.
|
||||
|
||||
@@ -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`.
|
||||
@@ -1,467 +0,0 @@
|
||||
# SLG-0004: Metadata values privacy attribute
|
||||
|
||||
Introduce an attributed metadata system that allows attaching attributes to metadata values, with privacy level as the first attribute enabling developers to mark metadata as `.private` or `.public`.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0004
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Deferred**
|
||||
- Issue: https://github.com/apple/swift-log/issues/204
|
||||
- Implementation:
|
||||
- [apple/swift-log#418](https://github.com/apple/swift-log/pull/418)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
- [Review discussion](https://forums.swift.org/t/proposal-slg-0004-metadata-values-privacy-attribute/85249/16)
|
||||
|
||||
### Introduction
|
||||
|
||||
This proposal introduces an **attributed metadata system** that allows attaching attributes to metadata values. Privacy level is the first concrete attribute, enabling developers to mark metadata values as `.private` or `.public` so `LogHandler` implementations can redact sensitive values before logging.
|
||||
|
||||
### Motivation
|
||||
|
||||
SwiftLog lacks a mechanism to attach attributes to metadata values. This prevents marking metadata as sensitive and limits future extensibility for other metadata attributes.
|
||||
|
||||
Applications need privacy controls for:
|
||||
- Compliance with privacy regulations.
|
||||
- Backend integration with privacy-aware logging systems.
|
||||
- Systematic control over what data appears in logs.
|
||||
|
||||
Beyond privacy, an attributed metadata system provides a foundation for future extensions such as retention policies, data classification, or other metadata attributes.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Introduce new `AttributedMetadata` data type, enabling users to mark metadata values with `.private` and `.public` privacy label:
|
||||
|
||||
```swift
|
||||
// Add privacy level to metadata values obtained through a metadata provider
|
||||
let serviceIp = "127.0.0.1"
|
||||
var logger = Logger(label: "my-app", metadataProvider: .init {[
|
||||
"service.ip": "\(serviceIp, privacy: .private)",
|
||||
]})
|
||||
|
||||
// Add privacy level to metadata values attached to a `Loghandler` instance
|
||||
let requestId = UUID()
|
||||
logger[attributedMetadataKey: "request.id"] = "\(requestId, privacy: .private)"
|
||||
|
||||
// Mark sensitive values as private and non-sensitive as public at logging call site
|
||||
let userId = UUID()
|
||||
let action = "login"
|
||||
logger.info("User action", attributedMetadata: [
|
||||
"user.id": "\(userId, privacy: .private)",
|
||||
"action": "\(action)" // default is .public for ease of adoption
|
||||
])
|
||||
```
|
||||
|
||||
This allows `Logger` users to mark certain metadata values as "I only trust LogHandlers, who know how to handle sensitive data, to see this value".
|
||||
|
||||
### Detailed design
|
||||
|
||||
#### Attributed Metadata
|
||||
|
||||
To support privacy labels and enable future extensibility, we introduce a generalized **attributed metadata** system. This provides a foundation for attaching arbitrary attributes to metadata values, with privacy labels being the first concrete use case:
|
||||
|
||||
```swift
|
||||
// Plain metadata (existing)
|
||||
let metadataValue: MetadataValue = .string("value")
|
||||
logger.info("Message", metadata: ["key": metadataValue])
|
||||
|
||||
// Attributed metadata (new) — a value with attributes
|
||||
logger.info("Message", attributedMetadata: [
|
||||
"key": AttributedMetadataValue(value: metadataValue, attributes: ...)
|
||||
])
|
||||
```
|
||||
|
||||
The attributed metadata system instroduces new public API:
|
||||
|
||||
1. **`AttributedMetadataValue`**: Wraps a standard `MetadataValue` with associated attributes.
|
||||
2. **`MetadataValueAttributes`**: Container for attributes.
|
||||
3. **`AttributedMetadata`**: Dictionary type mapping `String` keys to attributed values.
|
||||
4. **Parallel logging API**: New log methods accepting `attributedMetadata` parameter.
|
||||
|
||||
This design separates the transport mechanism (attributed metadata) from specific attribute semantics (privacy labels), allowing future extensions without breaking existing attributed metadata code.
|
||||
|
||||
#### Privacy levels
|
||||
|
||||
With attributed metadata as the foundation, privacy labels are implemented as the first concrete attribute:
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
/// A metadata value with associated privacy attributes.
|
||||
///
|
||||
/// `AttributedMetadataValue` wraps a standard `MetadataValue` with privacy attributes,
|
||||
/// allowing you to mark metadata as private or public for privacy-aware logging.
|
||||
///
|
||||
/// ## Creating Attributed Metadata
|
||||
///
|
||||
/// Use string interpolation with privacy parameter:
|
||||
///
|
||||
/// ```swift
|
||||
/// // Preferred: String interpolation with privacy level specified
|
||||
/// let userId = "12345"
|
||||
/// let action = "login"
|
||||
/// logger.info("User action", attributedMetadata: [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "action": "\(action, privacy: .public)" // explicit .public for non-sensitive data
|
||||
/// ])
|
||||
///
|
||||
/// // Direct creation
|
||||
/// let attributed = Logger.AttributedMetadataValue(
|
||||
/// .string("12345"),
|
||||
/// privacy: .private
|
||||
/// )
|
||||
/// ```
|
||||
///
|
||||
/// ## Important Limitations
|
||||
///
|
||||
/// - **No nested privacy**: When marking a dictionary or array as private, all contained
|
||||
/// values are treated with the same privacy level. Fine-grained privacy within nested
|
||||
/// structures is not currently supported.
|
||||
///
|
||||
/// - **Metadata only**: Privacy levels apply only to metadata values, not to log messages.
|
||||
/// Avoid including sensitive data in log message string interpolation.
|
||||
public struct AttributedMetadataValue: CustomStringConvertible, Sendable {
|
||||
/// The redaction marker used for private values.
|
||||
internal static let redactionMarker = "<private>"
|
||||
|
||||
public let value: MetadataValue
|
||||
public let attributes: MetadataValueAttributes
|
||||
|
||||
/// String representation redacts private values to the redaction marker.
|
||||
public var description: String {
|
||||
attributes.privacy == .public ? value.description : Self.redactionMarker
|
||||
}
|
||||
|
||||
public init(_ value: MetadataValue, attributes: MetadataValueAttributes)
|
||||
public init(_ value: MetadataValue, privacy: PrivacyLevel)
|
||||
}
|
||||
|
||||
extension AttributedMetadataValue {
|
||||
/// Attributes that can be associated with metadata values.
|
||||
public struct MetadataValueAttributes: CustomStringConvertible, Hashable, Sendable {
|
||||
/// Privacy level for metadata values.
|
||||
///
|
||||
/// Privacy levels allow you to mark metadata values as either private (sensitive data that should be
|
||||
/// protected) or public (safe to log in any context).
|
||||
///
|
||||
/// ## Usage
|
||||
///
|
||||
/// Use string interpolation with the privacy parameter to create attributed metadata values:
|
||||
///
|
||||
/// ```swift
|
||||
/// let userId = "12345"
|
||||
/// let action = "login"
|
||||
/// logger.info("User action", attributedMetadata: [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "action": "\(action, privacy: .public)",
|
||||
/// "ip": "\(ipAddress, privacy: .private)"
|
||||
/// ])
|
||||
/// ```
|
||||
@frozen
|
||||
public enum PrivacyLevel: Sendable, CaseIterable, Equatable, Hashable, CustomStringConvertible {
|
||||
/// Private data that should be redacted in non-secure contexts.
|
||||
case `private`
|
||||
|
||||
/// Public data safe for general logging.
|
||||
case `public`
|
||||
}
|
||||
|
||||
/// The privacy level of this metadata value.
|
||||
public var privacy: PrivacyLevel
|
||||
|
||||
/// Create metadata value attributes with the specified privacy level.
|
||||
///
|
||||
/// - Parameter privacy: The privacy level for this metadata. Defaults to `.public`.
|
||||
public init(privacy: PrivacyLevel = .public)
|
||||
}
|
||||
|
||||
/// The underlying metadata value without privacy attributes.
|
||||
public var value: MetadataValue
|
||||
|
||||
/// The privacy attributes associated with this metadata value.
|
||||
public var attributes: MetadataValueAttributes
|
||||
|
||||
/// Create an attributed metadata value with the specified attributes.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - value: The metadata value to wrap.
|
||||
/// - attributes: The attributes for this value.
|
||||
public init(_ value: MetadataValue, attributes: MetadataValueAttributes)
|
||||
|
||||
/// Convenience initializer for creating attributed metadata with a privacy level.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - value: The metadata value to wrap.
|
||||
/// - privacy: The privacy level for this value.
|
||||
public init(_ value: MetadataValue, privacy: PrivacyLevel)
|
||||
}
|
||||
|
||||
/// Metadata dictionary with privacy attributes.
|
||||
///
|
||||
/// A dictionary mapping string keys to ``AttributedMetadataValue`` instances, used with
|
||||
/// the `attributedMetadata` parameter of logging methods.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let userId = "12345"
|
||||
/// let requestId = "req-789"
|
||||
/// let metadata: Logger.AttributedMetadata = [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "request.id": "\(requestId, privacy: .public)",
|
||||
/// "action": "purchase" // String literal defaults to .public
|
||||
/// ]
|
||||
/// logger.info("User action", attributedMetadata: metadata)
|
||||
/// ```
|
||||
public typealias AttributedMetadata = [String: AttributedMetadataValue]
|
||||
}
|
||||
```
|
||||
|
||||
#### String interpolation for attributed metadata
|
||||
|
||||
```swift
|
||||
extension Logger.AttributedMetadataValue: ExpressibleByStringLiteral, ExpressibleByStringInterpolation {
|
||||
/// Custom string interpolation that captures privacy levels from interpolated values.
|
||||
///
|
||||
/// This enables syntax like:
|
||||
/// ```swift
|
||||
/// logger.info("User action", attributedMetadata: [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "action": "\(action, privacy: .public)"
|
||||
/// ])
|
||||
/// ```
|
||||
public struct StringInterpolation: StringInterpolationProtocol {
|
||||
public init(literalCapacity: Int, interpolationCount: Int)
|
||||
public mutating func appendLiteral(_ literal: String)
|
||||
|
||||
/// Interpolation with explicit privacy parameter.
|
||||
public mutating func appendInterpolation<T>(_ value: T, privacy: Logger.PrivacyLevel = .public)
|
||||
where T: CustomStringConvertible
|
||||
}
|
||||
|
||||
/// Creates an attributed metadata value from a string literal (defaults to .public).
|
||||
public init(stringLiteral value: String)
|
||||
|
||||
/// Creates an attributed metadata value from string interpolation.
|
||||
public init(stringInterpolation: StringInterpolation)
|
||||
}
|
||||
```
|
||||
|
||||
#### New Logger methods
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
// Attributed metadata storage
|
||||
var attributedMetadata: Logger.AttributedMetadata { get set }
|
||||
subscript(attributedMetadataKey: String) -> Logger.AttributedMetadataValue? { get set }
|
||||
|
||||
// Log family of methods
|
||||
public func log(level: Level, _ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func trace(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func debug(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func info(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func notice(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func warning(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func error(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func critical(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
}
|
||||
```
|
||||
|
||||
#### AttributedMetadata support in LogHandler protocol
|
||||
|
||||
```swift
|
||||
protocol LogHandler {
|
||||
func log(level: Logger.Level, message: Logger.Message,
|
||||
attributedMetadata: Logger.AttributedMetadata?, source: String,
|
||||
file: String, function: String, line: UInt)
|
||||
|
||||
var attributedMetadata: Logger.AttributedMetadata { get set }
|
||||
subscript(attributedMetadataKey: String) -> Logger.AttributedMetadataValue? { get set }
|
||||
}
|
||||
|
||||
// Default implementations provided for backward compatibility
|
||||
extension LogHandler {
|
||||
// Default attributed metadata log method - redacts private values using helper
|
||||
public func log(level: Logger.Level, message: Logger.Message,
|
||||
attributedMetadata: Logger.AttributedMetadata?,
|
||||
source: String, file: String, function: String, line: UInt) {
|
||||
let processedMetadata = attributedMetadata.flatMap(Self.attributedToPlain)
|
||||
self.log(level: level, message: message, metadata: processedMetadata,
|
||||
source: source, file: file, function: function, line: line)
|
||||
}
|
||||
|
||||
// Default attributed metadata storage - uses helpers for conversion
|
||||
public var attributedMetadata: Logger.AttributedMetadata {
|
||||
get { self.metadata.mapValues(Self.plainToAttributed) }
|
||||
set { self.metadata = newValue.mapValues(Self.attributedToPlain) }
|
||||
}
|
||||
|
||||
public subscript(attributedMetadataKey key: String) -> Logger.AttributedMetadataValue? {
|
||||
get {
|
||||
guard let plainValue = self[metadataKey: key] else { return nil }
|
||||
return Self.plainToAttributed(plainValue)
|
||||
}
|
||||
set {
|
||||
if let attributedValue = newValue {
|
||||
self[metadataKey: key] = Self.attributedToPlain(attributedValue)
|
||||
} else {
|
||||
self[metadataKey: key] = nil
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### AttributedMetadata support in MetadataProvider
|
||||
|
||||
```swift
|
||||
extension Logger.MetadataProvider {
|
||||
/// Creates a new metadata provider that returns attributed metadata.
|
||||
///
|
||||
/// Attributed metadata providers allow you to specify privacy levels and other
|
||||
/// attributes for each metadata value. When accessed through the plain ``get()``
|
||||
/// method (for backward compatibility), private values are redacted to `"<private>"`.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let provider = Logger.MetadataProvider {
|
||||
/// [
|
||||
/// "request-id": "\(RequestContext.current.id, privacy: .public)",
|
||||
/// "user-id": "\(RequestContext.current.userId, privacy: .private)"
|
||||
/// ]
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter provideAttributed: A closure that extracts attributed metadata from the current execution context.
|
||||
/// - Returns: A metadata provider that returns attributed metadata.
|
||||
@_disfavoredOverload
|
||||
public static func init(_ provideAttributed: @escaping @Sendable () -> AttributedMetadata) -> MetadataProvider
|
||||
|
||||
/// Returns attributed metadata if this is an attributed provider.
|
||||
///
|
||||
/// Handlers supporting attributed metadata should call this first,
|
||||
/// falling back to `get()` if it returns nil.
|
||||
public func getAttributed() -> AttributedMetadata?
|
||||
}
|
||||
```
|
||||
|
||||
### API stability
|
||||
|
||||
- All existing APIs unchanged.
|
||||
- Plain and attributed metadata APIs coexist.
|
||||
- No deprecation planned.
|
||||
- Adoption is optional and incremental on both application and Log Handler sides.
|
||||
- Default implementation ensures existing handlers work; logging private metadata is an application concern requiring a compatible `LogHandler`.
|
||||
|
||||
### Future directions
|
||||
|
||||
- Add more attributes (e.g., value data type, etc) and potential future unification of plain and attributed metadata APIs.
|
||||
- Introduce "custom attributes", allowing applications to define application-specific attributes to work with application-specific log handlers.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
1. **Key-based redaction:** Configure which keys should be treated as private rather than marking each value:
|
||||
|
||||
```swift
|
||||
logger.privateKeys = ["user.id", "password", "email"]
|
||||
logger.info("User action", metadata: [
|
||||
"user.id": "12345", // Automatically private
|
||||
"action": "login" // Automatically public
|
||||
])
|
||||
```
|
||||
|
||||
Advantages:
|
||||
- Simpler API (no new types).
|
||||
- Centralized configuration.
|
||||
- Safer at scale (new sensitive fields update all logs automatically).
|
||||
- Easier migration.
|
||||
|
||||
**Not chosen because:**
|
||||
|
||||
- **Privacy belongs to data, not identifiers:** The same private data might be logged under different keys ("email", "user.email", "contact"), and the same key might contain different data with different privacy requirements in different contexts. Key-based redaction creates a synchronization problem—developers must maintain a separate list of "private keys" that stays in sync with actual logging code across the codebase, with no compile-time or review-time verification.
|
||||
|
||||
- **Code review visibility:** With value-based privacy, reviewers see privacy decisions at the call site: `"email": user.email.private()` makes it immediately clear that data is sensitive. With key-based redaction, reviewers must cross-reference a separate configuration file, making security review significantly harder.
|
||||
|
||||
- **No synchronization needed:** Value-based privacy is self-contained—privacy travels with the data at the point of use. No separate configuration to maintain, no risk of configuration drift, no runtime surprises when a key is missing from the private keys list.
|
||||
|
||||
- **Pattern complexity:** Supporting patterns/regex adds complexity and potential performance concerns.
|
||||
|
||||
The current design prioritizes **explicitness and data-centric privacy** over **configuration-based simplicity**. Privacy decisions are made where data is logged, making them visible during code review and keeping privacy attributes coupled to the data they protect.
|
||||
|
||||
2. **Convenience methods (`.private()` and `.public()`):** Add extension methods to `String` and `MetadataValue` for creating attributed metadata:
|
||||
|
||||
```swift
|
||||
extension String {
|
||||
public func `private`() -> Logger.AttributedMetadataValue
|
||||
public func `public`() -> Logger.AttributedMetadataValue
|
||||
}
|
||||
|
||||
logger.info("User action", attributedMetadata: [
|
||||
"user.id": "12345".private(),
|
||||
"action": "login".public()
|
||||
])
|
||||
```
|
||||
|
||||
**Not chosen because:**
|
||||
|
||||
- **Consistency with existing patterns:** `Logger.Message` and `Logger.MetadataValue` already use string interpolation extensively.
|
||||
- **Natural syntax:** `"\(value, privacy: .private)"` reads clearly and fits Swift's interpolation conventions.
|
||||
- **Less API surface:** No need for multiple extension methods across different types.
|
||||
|
||||
Metadata values already support string interpolation in SwiftLog. Rather than inventing additional API surface area with new methods, we leverage the existing string interpolation infrastructure with a custom `StringInterpolation` type. This provides:
|
||||
|
||||
3. **Default privacy level to `.private`:** Make attributed metadata values default to `.private` privacy level when no explicit privacy parameter is provided:
|
||||
|
||||
```swift
|
||||
logger.info("User action", attributedMetadata: [
|
||||
"user.id": "\(userId, privacy: .private)", // Explicit private (redundant with default)
|
||||
"action": "\(action, privacy: .public)" // Must explicitly mark as public
|
||||
])
|
||||
```
|
||||
|
||||
Advantages:
|
||||
- Security-by-default: requires explicit opt-out for logging non-sensitive data.
|
||||
- Safer for accidental inclusion of sensitive data.
|
||||
|
||||
**Not chosen because:**
|
||||
|
||||
Privacy should be an explicit opt-in action from the user. The current design (defaulting to `.public`) prioritizes **ease of adoption** over **security-by-default**:
|
||||
- Easier adoption - less boilerplate for common non-sensitive metadata.
|
||||
- Matches the mental model that "most data is safe to log".
|
||||
- Lower friction for migration from plain metadata.
|
||||
- Forces developers to think about privacy only for sensitive data, rather than requiring `.public` annotations everywhere.
|
||||
|
||||
4. **Pass all metadata to non-privacy-aware handlers:** Security risk; current design filters private data by default.
|
||||
|
||||
5. **Message-level privacy:** Less granular than metadata-level privacy and requires message handling changes.
|
||||
|
||||
6. **Privacy level handling configuration** to be an attribute of the `Logger` instead of LogHandler configuration. This would centralize the configuration across various `LogHandler` implementations. However, existing `LogHandler` already have configurations and they might want to customize the behavior even further.
|
||||
|
||||
7. **Handler metadata merging:** LogHandlers are responsible for merging their own `metadata` property, `metadataProvider` output, and the explicit `attributedMetadata` parameter. This is consistent with how plain metadata works - handlers control merging. Plain handler metadata and provider values should be treated as public (`.public` privacy level). Attributed metadata from the log call takes precedence.
|
||||
|
||||
8. **Add a third `.auto`/`.default` privacy attribute value:** Libraries and applications can mark a metadata value as `privacy: .default` and rely on the `LogHandler` to configure what the default is. While this might've been a solution to overcome default `.public` values for all the attributed metadata, in reality it is confusing from the semantic point of view. If someone wants to mark something as `.default`, because this _might_ be sensitive, then it should be marked as `.private` or not logged at all. If something does not need to be marked as `.private`, then it is `.public`. A custom `LogHandler` with an allow list of metadata keys/messages/modules can be used as an escape hatch in case the application does not trust its dependencies.
|
||||
@@ -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``
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
### 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``
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
### Creating a metadata provider
|
||||
|
||||
- ``init(_:)``
|
||||
- ``init(_:)-(()->Logger.Metadata)``
|
||||
|
||||
### Invoking the provider
|
||||
|
||||
|
||||
@@ -14,35 +14,49 @@
|
||||
|
||||
- ``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``
|
||||
@@ -52,6 +66,10 @@
|
||||
- ``subscript(metadataKey:)``
|
||||
- ``MetadataValue``
|
||||
|
||||
### Metadata attribute types
|
||||
|
||||
- ``MetadataValueAttributes``
|
||||
|
||||
### Inspecting a logger
|
||||
|
||||
- ``label``
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)``
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
@@ -11,6 +11,7 @@
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)``
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# ``Logging/SwiftLogNoOpLogHandler``
|
||||
|
||||
A log handler that silently discards all log messages.
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a Swift Log no-op log handler
|
||||
@@ -9,7 +11,9 @@
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)``
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
- ``log(level:message:metadata:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ 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 package if you're writing a cross-platform application (for example, Linux and
|
||||
macOS) or library, and want to target this logging API.
|
||||
@@ -84,6 +84,7 @@ backend.
|
||||
### Log Handlers
|
||||
|
||||
- ``LogHandler``
|
||||
- ``LogEvent``
|
||||
- ``MultiplexLogHandler``
|
||||
- ``StreamLogHandler``
|
||||
- ``SwiftLogNoOpLogHandler``
|
||||
|
||||
@@ -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 {}
|
||||
}
|
||||
}
|
||||
@@ -30,12 +30,9 @@ public struct LogEvent: Sendable {
|
||||
public var error: (any Error)?
|
||||
|
||||
/// The metadata associated with this event, if any.
|
||||
public var metadata: Logger.Metadata? {
|
||||
get { self._metadata }
|
||||
set { self._metadata = newValue }
|
||||
}
|
||||
|
||||
private var _metadata: Logger.Metadata?
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
@@ -116,7 +113,7 @@ public struct LogEvent: Sendable {
|
||||
self.level = level
|
||||
self.message = message
|
||||
self.error = error
|
||||
self._metadata = metadata
|
||||
self.metadata = metadata
|
||||
self._source = source
|
||||
self.file = file
|
||||
self.function = function
|
||||
|
||||
@@ -96,14 +96,7 @@
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// 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) {
|
||||
/// // [...]
|
||||
/// }
|
||||
///
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -12,22 +12,6 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#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
|
||||
|
||||
/// A Logger emits log messages using methods that correspond to a log level.
|
||||
///
|
||||
/// `Logger` is a value type with respect to the ``Logger/Level`` and the ``Metadata`` (as well as the immutable `label`
|
||||
@@ -267,6 +251,7 @@ extension Logger {
|
||||
/// - parameters:
|
||||
/// - level: The severity level of the `message`.
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` related to the event.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
@@ -329,9 +314,23 @@ extension Logger {
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
) {
|
||||
self.log(level: level, message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
|
||||
self.log(
|
||||
level: level,
|
||||
message(),
|
||||
error: nil,
|
||||
metadata: metadata(),
|
||||
source: nil,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
|
||||
/// Log a message using the log level and attributed metadata that you provide.
|
||||
///
|
||||
/// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library
|
||||
/// logs the message, otherwise nothing will happen.
|
||||
///
|
||||
/// Add, change, or remove a logging metadata item.
|
||||
///
|
||||
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
|
||||
@@ -341,7 +340,9 @@ extension Logger {
|
||||
self.handler[metadataKey: metadataKey]
|
||||
}
|
||||
set {
|
||||
#if !MaxLogLevelNone
|
||||
self.handler[metadataKey: metadataKey] = newValue
|
||||
#endif
|
||||
}
|
||||
}
|
||||
|
||||
@@ -357,7 +358,9 @@ extension Logger {
|
||||
self.handler.logLevel
|
||||
}
|
||||
set {
|
||||
#if !MaxLogLevelNone
|
||||
self.handler.logLevel = newValue
|
||||
#endif
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1078,192 +1081,6 @@ extension Logger {
|
||||
}
|
||||
}
|
||||
|
||||
/// 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)
|
||||
}
|
||||
|
||||
fileprivate 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?>
|
||||
}
|
||||
|
||||
extension Logger {
|
||||
/// The type of the metadata storage.
|
||||
///
|
||||
@@ -1359,6 +1176,9 @@ extension Logger {
|
||||
/// `.array([.string("foo"), .string("bar \(buz)")])`, instead use the more natural `["foo", "bar \(buz)"]`.
|
||||
case array([Metadata.Value])
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger {
|
||||
|
||||
/// The log level.
|
||||
///
|
||||
@@ -1551,687 +1371,6 @@ extension Logger {
|
||||
}
|
||||
}
|
||||
|
||||
/// 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])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// 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
|
||||
}
|
||||
}
|
||||
|
||||
/// 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 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 {}
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger {
|
||||
@inlinable
|
||||
internal static func currentModule(filePath: String = #file) -> String {
|
||||
@@ -2287,10 +1426,6 @@ extension Logger.MetadataValue: CustomStringConvertible {
|
||||
}
|
||||
}
|
||||
|
||||
// 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 {}
|
||||
|
||||
// Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for
|
||||
// https://bugs.swift.org/browse/SR-9686
|
||||
extension Logger.MetadataValue: ExpressibleByDictionaryLiteral {
|
||||
@@ -2319,27 +1454,10 @@ extension Logger.MetadataValue: ExpressibleByArrayLiteral {
|
||||
}
|
||||
}
|
||||
|
||||
// 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
|
||||
|
||||
// MARK: - Sendable support helpers
|
||||
|
||||
extension Logger.MetadataValue: Sendable {}
|
||||
|
||||
extension Logger: Sendable {}
|
||||
extension Logger.Level: Sendable {}
|
||||
extension Logger.Message: Sendable {}
|
||||
@@ -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
|
||||
@@ -53,12 +53,24 @@ 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 the current context.
|
||||
@usableFromInline
|
||||
internal let _provideMetadata: @Sendable () -> Metadata
|
||||
|
||||
@@ -70,6 +82,8 @@ extension Logger {
|
||||
}
|
||||
|
||||
/// Invokes the metadata provider and returns the generated contextual metadata.
|
||||
///
|
||||
/// - Returns: Metadata dictionary, where values may carry attributes.
|
||||
public func get() -> Metadata {
|
||||
self._provideMetadata()
|
||||
}
|
||||
@@ -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 })
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -22,15 +22,10 @@ struct InMemoryLogHandlerTests {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "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
|
||||
@@ -39,16 +34,10 @@ struct InMemoryLogHandlerTests {
|
||||
logger[metadataKey: "test"] = "value"
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: ["key1": "value1", "key2": ["a", "b", "c"], "test": "value"]
|
||||
)
|
||||
]
|
||||
)
|
||||
// Metadata also sticks onto the logger
|
||||
#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")
|
||||
}
|
||||
|
||||
@@ -62,11 +51,54 @@ struct InMemoryLogHandlerTests {
|
||||
logger[metadataKey: "c"] = "2"
|
||||
logger.info("hello", metadata: ["c": "3"])
|
||||
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(level: .info, message: "hello", metadata: ["a": "1", "b": "2", "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
|
||||
@@ -81,7 +113,7 @@ struct InMemoryLogHandlerTests {
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: TestError.first,
|
||||
metadata: [:],
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
|
||||
@@ -91,7 +123,7 @@ struct InMemoryLogHandlerTests {
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: nil,
|
||||
metadata: [:],
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
|
||||
@@ -116,33 +148,6 @@ struct InMemoryLogHandlerTests {
|
||||
)
|
||||
}
|
||||
|
||||
@Test
|
||||
func clear() {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
logHandler.clear()
|
||||
logger.info("hello2")
|
||||
|
||||
// Only hello2 is here
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(level: .info, message: "hello2", metadata: [:])
|
||||
]
|
||||
)
|
||||
}
|
||||
|
||||
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)
|
||||
}
|
||||
|
||||
enum TestError: Error {
|
||||
case first
|
||||
case second
|
||||
|
||||
@@ -98,6 +98,65 @@ struct LogEventTest {
|
||||
#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)
|
||||
|
||||
@@ -17,15 +17,10 @@ import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif os(Windows)
|
||||
import WinSDK
|
||||
#elseif canImport(Android)
|
||||
import Android
|
||||
#else
|
||||
import Glibc
|
||||
#endif
|
||||
private enum TestAttr: Int64, Logger.MetadataValueAttributes.Attribute {
|
||||
case x = 1
|
||||
case y = 2
|
||||
}
|
||||
|
||||
extension LogHandler {
|
||||
fileprivate func with(logLevel: Logger.Level) -> any LogHandler {
|
||||
@@ -862,6 +857,73 @@ struct LoggingTest {
|
||||
logger1.error("hey")
|
||||
}
|
||||
|
||||
@Test func multiplexLogHandlerMetadataWithAttributes_settingAndReading() {
|
||||
let logging1 = TestLogging()
|
||||
let logging2 = TestLogging()
|
||||
|
||||
let logger1 = logging1.make(label: "1")
|
||||
let logger2 = logging2.make(label: "2")
|
||||
|
||||
var multiplexLogger = Logger(
|
||||
label: "test",
|
||||
factory: { _ in
|
||||
MultiplexLogHandler([logger1, logger2])
|
||||
}
|
||||
)
|
||||
|
||||
// Set metadata with attributes via string interpolation
|
||||
multiplexLogger[metadataKey: "key1"] = "\("value1", attributes: { $0[TestAttr.self] = .x })"
|
||||
|
||||
// The value survives the round-trip
|
||||
let retrieved = multiplexLogger[metadataKey: "key1"]
|
||||
#expect(retrieved != nil)
|
||||
#expect(retrieved?.description == "value1")
|
||||
|
||||
// Attributes are preserved inside .stringConvertible
|
||||
#expect(retrieved?.attributes[TestAttr.self] == .x)
|
||||
}
|
||||
|
||||
@Test func multiplexLogHandlerMetadataWithAttributes_forwardsEventWithAttributes() {
|
||||
let logging1 = TestLogging()
|
||||
let logging2 = TestLogging()
|
||||
|
||||
var logger = Logger(
|
||||
label: "test",
|
||||
factory: {
|
||||
MultiplexLogHandler([logging1.make(label: $0), logging2.make(label: $0)])
|
||||
}
|
||||
)
|
||||
logger.logLevel = .debug
|
||||
|
||||
// Log with metadata containing attributed values
|
||||
logger.info("hello", metadata: ["request-id": "\("abc123")"])
|
||||
|
||||
// Both handlers should receive the message
|
||||
logging1.history.assertExist(level: .info, message: "hello")
|
||||
logging2.history.assertExist(level: .info, message: "hello")
|
||||
}
|
||||
|
||||
@Test func metadataWithAttributes_flowsThroughHandler() {
|
||||
let logging = TestLogging()
|
||||
|
||||
var logger = Logger(
|
||||
label: "test",
|
||||
factory: { logging.make(label: $0) }
|
||||
)
|
||||
logger.logLevel = .debug
|
||||
|
||||
// Log with metadata values that carry attributes
|
||||
logger.info(
|
||||
"attributed event",
|
||||
metadata: [
|
||||
"user-id": "\("12345", attributes: { $0[TestAttr.self] = .x })"
|
||||
]
|
||||
)
|
||||
|
||||
// The handler should receive the message via LogEvent
|
||||
logging.history.assertExist(level: .info, message: "attributed event")
|
||||
}
|
||||
|
||||
/// Protects an object such that it can only be accessed while holding a lock.
|
||||
private final class LockedValueBox<Value: Sendable>: @unchecked Sendable {
|
||||
private let lock = Lock()
|
||||
@@ -1007,327 +1069,6 @@ struct LoggingTest {
|
||||
#expect(Logger.Level(level.rawValue.uppercased()) == level)
|
||||
}
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
|
||||
@Test func overloadingError() {
|
||||
struct Dummy: Error, LocalizedError {
|
||||
var errorDescription: String? {
|
||||
@@ -1426,12 +1167,8 @@ extension Logger.MetadataProvider {
|
||||
}
|
||||
}
|
||||
|
||||
// Sendable
|
||||
// MARK: - Sendable
|
||||
|
||||
// used to test logging metadata which requires Sendable conformance
|
||||
// @unchecked Sendable since manages it own state
|
||||
extension LoggingTest.LazyMetadataBox: @unchecked Sendable {}
|
||||
|
||||
// used to test logging stream which requires Sendable conformance
|
||||
// @unchecked Sendable since manages it own state
|
||||
extension LoggingTest.InterceptStream: @unchecked Sendable {}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
@@ -485,7 +485,7 @@ internal struct TestLibrary: Sendable {
|
||||
}
|
||||
}
|
||||
|
||||
// Sendable
|
||||
// MARK: - Sendable
|
||||
|
||||
extension TestLogHandler: @unchecked Sendable {}
|
||||
extension Recorder: @unchecked Sendable {}
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
One line description of your change
|
||||
|
||||
Motivation:
|
||||
|
||||
Explain here the context, and why you're making that change.
|
||||
What is the problem you're trying to solve.
|
||||
|
||||
Modifications:
|
||||
|
||||
Describe the modifications you've done.
|
||||
|
||||
Result:
|
||||
|
||||
After your change, what will change.
|
||||
Reference in new issue
Block a user