mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
82cf87d893 | ||
|
|
47655e0c23 | ||
|
|
d05c8efdae | ||
|
|
c7413d967b | ||
|
|
34b131f794 | ||
|
|
e3da040787 | ||
|
|
209524e4da | ||
|
|
c44b210eee | ||
|
|
d0f784af9e | ||
|
|
c9c6bb9d27 | ||
|
|
6404842475 | ||
|
|
fcd893317d | ||
|
|
65b3417512 | ||
|
|
666b45a252 | ||
|
|
4038b6a4f7 | ||
|
|
109c380c23 | ||
|
|
c29472f010 | ||
|
|
bca880e799 | ||
|
|
c581740960 | ||
|
|
9c9acde6dc | ||
|
|
cf3e828428 | ||
|
|
3be27be290 | ||
|
|
9c6fb14227 | ||
|
|
53d00853e6 | ||
|
|
c5ece24786 | ||
|
|
172948a4b5 | ||
|
|
47a917767f | ||
|
|
f054da4c19 | ||
|
|
3ffafb9722 | ||
|
|
7af2de138f | ||
|
|
e83726cb15 | ||
|
|
8056dbfb08 | ||
|
|
1032aed8a5 | ||
|
|
1895d78a91 | ||
|
|
8a6b9eab84 | ||
|
|
c4e96785bf | ||
|
|
54ec9e35cd | ||
|
|
e3b5d65fc9 | ||
|
|
a878e7f8f4 | ||
|
|
2c52ee25d2 | ||
|
|
ca61184698 | ||
|
|
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"
|
||||
+55
-78
@@ -10,87 +10,64 @@ on:
|
||||
- cron: "0 8,20 * * *"
|
||||
|
||||
jobs:
|
||||
unit-tests:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
tests:
|
||||
name: Tests
|
||||
uses: swiftlang/github-workflows/.github/workflows/package_test.yml@0.0.18
|
||||
with:
|
||||
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
# After https://github.com/swiftlang/github-workflows/pull/362 fix is available, this can be simplified to:
|
||||
# windows_command: |
|
||||
# Debug-Test: swift test
|
||||
# Release-Build: swift build -c release
|
||||
# windows_version_overrides: |
|
||||
# default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
# nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
# nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
windows_env_vars: '{"COMMON_SWIFT_FLAGS": "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"}'
|
||||
windows_command: |
|
||||
Debug-Test:
|
||||
command: swift test -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
|
||||
versions: ["current-2", "current-1", "current"]
|
||||
Release-Build:
|
||||
command: swift build -c release -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
|
||||
versions: ["current-2", "current-1", "current"]
|
||||
Debug-Test-Nightly:
|
||||
command: swift test %COMMON_SWIFT_FLAGS%
|
||||
versions: ["nightly-release", "nightly-main"]
|
||||
Release-Build-Nightly:
|
||||
command: swift build -c release %COMMON_SWIFT_FLAGS%
|
||||
versions: ["nightly-release", "nightly-main"]
|
||||
# The Windows runner installs a pinned Swift patch release. The container image tracks the newest patch release.
|
||||
# Context: https://github.com/swiftlang/github-workflows/issues/356
|
||||
windows_use_docker: true
|
||||
# Strict flags for the release toolchains. The nightly toolchains skip -warnings-as-errors.
|
||||
linux_version_overrides: |
|
||||
default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
macos_runner_pool: nightly
|
||||
xcode_scheme: swift-log-Package
|
||||
xcode_targets: |
|
||||
macOS:
|
||||
build: true
|
||||
test: true
|
||||
wasm_sdk_versions: '["current", "nightly-main"]'
|
||||
enable_embedded_wasm_sdk_build: false
|
||||
enable_macos_swiftly: false
|
||||
enable_freebsd: false
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks (NoTraits)
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
name: macOS benchmarks
|
||||
uses: swiftlang/github-workflows/.github/workflows/benchmarks.yml@0.0.18
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/NoTraits"
|
||||
macos_xcode_16_4_enabled: true
|
||||
macos_xcode_26_1_enabled: true
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
enable_linux: false
|
||||
enable_macos: true
|
||||
macos_swift_versions: '["current-1", "current"]'
|
||||
macos_runner_pool: nightly
|
||||
|
||||
macos-benchmarks-MaxLogLevelWarningBenchmarks-trait:
|
||||
name: macOS benchmarks (MaxLogLevelWarning)
|
||||
needs: macos-benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
cmake-build:
|
||||
name: CMake build
|
||||
uses: swiftlang/github-workflows/.github/workflows/cmake_build.yml@0.0.18
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
static-linux:
|
||||
name: Static Linux Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
|
||||
|
||||
macos-tests:
|
||||
name: macOS tests
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
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
|
||||
tvos_xcode_test_enabled: false
|
||||
visionos_xcode_test_enabled: false
|
||||
|
||||
wasm:
|
||||
name: Wasm Swift SDK
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
|
||||
android:
|
||||
name: Android Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/android_swift_sdk.yml@main
|
||||
|
||||
release-builds:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
enable_windows_checks: false
|
||||
linux_pre_build_command: apt-get update && apt-get install -y ninja-build
|
||||
@@ -10,81 +10,68 @@ 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.18
|
||||
with:
|
||||
license_header_check_project_name: "Swift Logging API"
|
||||
|
||||
unit-tests:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
tests:
|
||||
name: Tests
|
||||
uses: swiftlang/github-workflows/.github/workflows/package_test.yml@0.0.18
|
||||
with:
|
||||
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
# After https://github.com/swiftlang/github-workflows/pull/362 fix is available, this can be simplified to:
|
||||
# windows_command: |
|
||||
# Debug-Test: swift test
|
||||
# Release-Build: swift build -c release
|
||||
# windows_version_overrides: |
|
||||
# default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
# nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
# nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
windows_env_vars: '{"COMMON_SWIFT_FLAGS": "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"}'
|
||||
windows_command: |
|
||||
Debug-Test:
|
||||
command: swift test -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
|
||||
versions: ["current-2", "current-1", "current"]
|
||||
Release-Build:
|
||||
command: swift build -c release -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
|
||||
versions: ["current-2", "current-1", "current"]
|
||||
Debug-Test-Nightly:
|
||||
command: swift test %COMMON_SWIFT_FLAGS%
|
||||
versions: ["nightly-release", "nightly-main"]
|
||||
Release-Build-Nightly:
|
||||
command: swift build -c release %COMMON_SWIFT_FLAGS%
|
||||
versions: ["nightly-release", "nightly-main"]
|
||||
# The Windows runner installs a pinned Swift patch release. The container image tracks the newest patch release.
|
||||
# Context: https://github.com/swiftlang/github-workflows/issues/356
|
||||
windows_use_docker: true
|
||||
# Strict flags for the release toolchains. The nightly toolchains skip -warnings-as-errors.
|
||||
linux_version_overrides: |
|
||||
default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
|
||||
macos_runner_pool: general
|
||||
xcode_scheme: swift-log-Package
|
||||
xcode_targets: |
|
||||
macOS:
|
||||
build: true
|
||||
test: true
|
||||
wasm_sdk_versions: '["current", "nightly-main"]'
|
||||
enable_embedded_wasm_sdk_build: false
|
||||
enable_macos_swiftly: false
|
||||
enable_freebsd: false
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks (NoTraits)
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
name: macOS benchmarks
|
||||
uses: swiftlang/github-workflows/.github/workflows/benchmarks.yml@0.0.18
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/NoTraits"
|
||||
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
|
||||
enable_linux: false
|
||||
enable_macos: true
|
||||
macos_swift_versions: '["current-1", "current"]'
|
||||
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
|
||||
cmake-build:
|
||||
name: CMake build
|
||||
uses: swiftlang/github-workflows/.github/workflows/cmake_build.yml@0.0.18
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
|
||||
macos_runner_pool: general
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
static-linux:
|
||||
name: Static Linux Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
|
||||
|
||||
macos-tests:
|
||||
name: macOS tests
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
runner_pool: general
|
||||
build_scheme: swift-log-Package
|
||||
swift_test_enabled: true
|
||||
|
||||
android:
|
||||
name: Android Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/android_swift_sdk.yml@main
|
||||
|
||||
release-builds:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
|
||||
wasm:
|
||||
name: Wasm Swift SDK
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
enable_windows_checks: false
|
||||
linux_pre_build_command: apt-get update && apt-get install -y ninja-build
|
||||
@@ -2,6 +2,7 @@ name: PR label
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
@@ -10,12 +11,4 @@ on:
|
||||
jobs:
|
||||
semver-label-check:
|
||||
name: Semantic version label check
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 1
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Check for Semantic Version label
|
||||
uses: apple/swift-nio/.github/actions/pull_request_semver_label_checker@main
|
||||
uses: swiftlang/github-workflows/.github/workflows/pull_request_label.yml@0.0.18
|
||||
@@ -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.3
|
||||
// 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/benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "MaxLogLevelNone",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/MaxLogLevelNoneBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1651,
|
||||
"instructions" : 6771,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1651,
|
||||
"instructions" : 6767,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6775,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6771,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6875,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6879,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6895,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6867,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+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.3
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
@@ -19,19 +19,19 @@ let package = Package(
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "MaxLogLevelWarning",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/MaxLogLevelWarningBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
.plugin(name: "BenchmarkPlugin", package: "benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 619,
|
||||
"instructions" : 6775,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6747,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 619,
|
||||
"instructions" : 6775,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1251327,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1251327,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6847,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6863,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 6871,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1189887,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1189887,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -18,10 +18,89 @@ import Foundation
|
||||
import Logging
|
||||
|
||||
public let benchmarks: @Sendable () -> Void = {
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_generic") { logger in
|
||||
logger.log(level: .error, "hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_generic") { logger in
|
||||
logger.log(level: .debug, "hello, benchmarking world")
|
||||
}
|
||||
|
||||
// MARK: - Task-local logger benchmarks
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_current_read_fallback") { _ in
|
||||
blackHole(Logger.current)
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_current_read_inside_scope") {
|
||||
logger in
|
||||
blackHole(Logger.current)
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_withLogger_mergingMetadata") {
|
||||
logger in
|
||||
withLogger(mergingMetadata: ["key": "value"]) { inner in
|
||||
blackHole(inner)
|
||||
}
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_withLogger_handler") { logger in
|
||||
withLogger(handler: logger.handler) { inner in
|
||||
blackHole(inner)
|
||||
}
|
||||
}
|
||||
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_1_attribute") { logger in
|
||||
logger.log(
|
||||
level: .error,
|
||||
"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])"
|
||||
]
|
||||
)
|
||||
}
|
||||
|
||||
// MARK: - metadata serialization performance
|
||||
|
||||
func nestedArrayMetadataValue(depth: Int) -> Logger.MetadataValue {
|
||||
var value: Logger.MetadataValue = .string("leaf")
|
||||
for _ in 0..<depth {
|
||||
value = .array([value])
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
for depth in [1, 5, 20, 1_000] {
|
||||
let nested = nestedArrayMetadataValue(depth: depth)
|
||||
makeBenchmark(loggerLevel: .info, logLevel: .debug, "_metadata_nesting_depth_\(depth)") { _ in
|
||||
blackHole(nested.description)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version:6.1
|
||||
// swift-tools-version:6.2.3
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
@@ -18,19 +18,19 @@ let package = Package(
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "NoTraits",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/NoTraitsBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
.plugin(name: "BenchmarkPlugin", package: "benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 324863,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 324863,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 984,
|
||||
"instructions" : 320767,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 4751359,
|
||||
"objectAllocCount" : 1000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5039157355,
|
||||
"objectAllocCount" : 2016000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 81723391,
|
||||
"objectAllocCount" : 37000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 17661951,
|
||||
"objectAllocCount" : 6000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5644287,
|
||||
"objectAllocCount" : 2000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 7065599,
|
||||
"objectAllocCount" : 3000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 272895,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 284927,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1368,
|
||||
"instructions" : 1249279,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 3273000,
|
||||
"objectAllocCount" : 1000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 9117695,
|
||||
"objectAllocCount" : 4000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 324863,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 324863,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 893,
|
||||
"instructions" : 323071,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 4415487,
|
||||
"objectAllocCount" : 1000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 4322989256,
|
||||
"objectAllocCount" : 2016000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 68354047,
|
||||
"objectAllocCount" : 37000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 14581759,
|
||||
"objectAllocCount" : 6000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 5795839,
|
||||
"objectAllocCount" : 2000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 7192575,
|
||||
"objectAllocCount" : 3000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 301055,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 243967,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
{
|
||||
"instructions" : 1649,
|
||||
"instructions" : 1189887,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 2841000,
|
||||
"objectAllocCount" : 1000
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 8929279,
|
||||
"objectAllocCount" : 4000
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version:6.1
|
||||
// swift-tools-version:6.2.3
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
@@ -12,14 +12,14 @@ let package = Package(
|
||||
.library(name: "BenchmarksFactory", targets: ["BenchmarksFactory"])
|
||||
],
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
|
||||
.package(path: "../"), // swift-log
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "BenchmarksFactory",
|
||||
dependencies: [
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Benchmark", package: "benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
]
|
||||
)
|
||||
|
||||
@@ -19,6 +19,7 @@ import Logging
|
||||
public func makeBenchmark(
|
||||
loggerLevel: Logger.Level,
|
||||
logLevel: Logger.Level,
|
||||
setScopedLogger: Bool = false,
|
||||
_ suffix: String = "",
|
||||
_ body: @escaping (Logger) -> Void
|
||||
) {
|
||||
@@ -35,11 +36,12 @@ public func makeBenchmark(
|
||||
"\(logLevel)_log_with_\(loggerLevel)_log_level\(suffix)",
|
||||
configuration: .init(
|
||||
metrics: metrics,
|
||||
scalingFactor: .kilo,
|
||||
maxIterations: iterations,
|
||||
thresholds: [
|
||||
.instructions: BenchmarkThresholds(
|
||||
relative: [
|
||||
.p90: 1.0 // we only record p90
|
||||
.p90: 10.0 // we only record p90
|
||||
]
|
||||
),
|
||||
.objectAllocCount: BenchmarkThresholds(
|
||||
@@ -49,7 +51,21 @@ public func makeBenchmark(
|
||||
),
|
||||
]
|
||||
)
|
||||
) { _ in
|
||||
body(logger)
|
||||
) { benchmark in
|
||||
if setScopedLogger {
|
||||
withLogger(logger) { logger in
|
||||
benchmark.startMeasurement()
|
||||
for _ in benchmark.scaledIterations {
|
||||
body(logger)
|
||||
}
|
||||
benchmark.stopMeasurement()
|
||||
}
|
||||
} else {
|
||||
benchmark.startMeasurement()
|
||||
for _ in benchmark.scaledIterations {
|
||||
body(logger)
|
||||
}
|
||||
benchmark.stopMeasurement()
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
|
||||
# Licensed under Apache License v2.0
|
||||
#
|
||||
# See LICENSE.txt for license information
|
||||
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
cmake_minimum_required(VERSION 3.19)
|
||||
|
||||
# Initialize C language first to inspect the compiler environment
|
||||
project(swift-log LANGUAGES C)
|
||||
|
||||
# Set Swift compiler target from C compiler target if not manually set for Windows
|
||||
if(WIN32 AND NOT CMAKE_Swift_COMPILER_TARGET)
|
||||
if(CMAKE_C_COMPILER_ARCHITECTURE_ID MATCHES "(ARM64|arm64|aarch64)")
|
||||
set(CMAKE_Swift_COMPILER_TARGET "aarch64-unknown-windows-msvc" CACHE STRING "Swift compiler target triple")
|
||||
elseif(CMAKE_C_COMPILER_ARCHITECTURE_ID MATCHES "(X86|x64|AMD64|x86_64)")
|
||||
set(CMAKE_Swift_COMPILER_TARGET "x86_64-unknown-windows-msvc" CACHE STRING "Swift compiler target triple")
|
||||
endif()
|
||||
endif()
|
||||
|
||||
# Enable Swift after C defines the architecture
|
||||
enable_language(Swift)
|
||||
|
||||
option(BUILD_SHARED_LIBS "Build shared libraries by default" YES)
|
||||
|
||||
set(CMAKE_Swift_LANGUAGE_VERSION 6)
|
||||
|
||||
if(CMAKE_Swift_COMPILER_VERSION VERSION_LESS "6.2.3")
|
||||
message(FATAL_ERROR "swift-log requires Swift compiler version 6.2.3 or newer. Detected version: ${CMAKE_Swift_COMPILER_VERSION}")
|
||||
endif()
|
||||
|
||||
set(SWIFT_LOG_COMMON_COMPILE_OPTIONS
|
||||
"SHELL:-enable-upcoming-feature ExistentialAny"
|
||||
"SHELL:-enable-upcoming-feature MemberImportVisibility"
|
||||
"SHELL:-enable-upcoming-feature InternalImportsByDefault"
|
||||
"SHELL:-enable-upcoming-feature NonisolatedNonsendingByDefault"
|
||||
"SHELL:-Xfrontend -require-explicit-sendable"
|
||||
"SHELL:-package-name swift_log")
|
||||
|
||||
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
|
||||
|
||||
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
|
||||
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
|
||||
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
|
||||
|
||||
set(CMAKE_Swift_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/swift)
|
||||
|
||||
if(MSVC)
|
||||
message(STATUS "MSVC condition triggered successfully!")
|
||||
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
|
||||
set(CMAKE_Swift_COMPILE_OPTIONS_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
|
||||
endif()
|
||||
|
||||
include(GNUInstallDirs)
|
||||
include(SwiftSupport)
|
||||
|
||||
if(NOT APPLE)
|
||||
find_package(dispatch QUIET)
|
||||
find_package(Foundation QUIET)
|
||||
endif()
|
||||
|
||||
add_subdirectory(Sources)
|
||||
|
||||
add_subdirectory(cmake/modules)
|
||||
@@ -1,3 +0,0 @@
|
||||
# Code of Conduct
|
||||
|
||||
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
|
||||
+14
-24
@@ -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
|
||||
@@ -104,20 +87,27 @@ directory, for example:
|
||||
## Benchmarks
|
||||
|
||||
Benchmarks for `swift-log` are in a separate Swift Package in the `Benchmarks` subfolder of this repository.
|
||||
They use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin.
|
||||
Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `package-benchmark` to capture memory allocation statistics.
|
||||
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `package-benchmark`.
|
||||
They use the [`benchmark`](https://github.com/ordo-one/benchmark) plugin.
|
||||
On Swift versions prior to 6.3 Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `benchmark` to capture memory allocation statistics.
|
||||
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `benchmark`.
|
||||
Afterwards you can run the benchmarks from CLI by going to the `Benchmarks` subfolder (e.g. `cd Benchmarks`) and invoking:
|
||||
```
|
||||
swift package benchmark
|
||||
```
|
||||
|
||||
For more information please refer to `swift package benchmark --help` or the [documentation of `package-benchmark`](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark).
|
||||
For more information please refer to `swift package benchmark --help` or the [documentation of `benchmark`](https://swiftpackageindex.com/ordo-one/benchmark/documentation/benchmark).
|
||||
|
||||
|
||||
## How to contribute your work
|
||||
|
||||
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`
|
||||
+5
-16
@@ -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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
// swift-tools-version:6.2.3
|
||||
|
||||
import PackageDescription
|
||||
|
||||
@@ -42,11 +29,13 @@ let package = Package(
|
||||
targets: [
|
||||
.target(
|
||||
name: "Logging",
|
||||
dependencies: []
|
||||
dependencies: [],
|
||||
exclude: ["CMakeLists.txt"]
|
||||
),
|
||||
.target(
|
||||
name: "InMemoryLogging",
|
||||
dependencies: ["Logging"]
|
||||
dependencies: ["Logging"],
|
||||
exclude: ["CMakeLists.txt"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "LoggingTests",
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
// 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
|
||||
|
||||
let package = Package(
|
||||
name: "swift-log",
|
||||
products: [
|
||||
.library(name: "Logging", targets: ["Logging"]),
|
||||
.library(name: "InMemoryLogging", targets: ["InMemoryLogging"]),
|
||||
],
|
||||
traits: [
|
||||
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
|
||||
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
|
||||
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
|
||||
.trait(
|
||||
name: "MaxLogLevelWarning",
|
||||
description: "Warning and above available (compiles out trace, debug, info, notice)"
|
||||
),
|
||||
.trait(
|
||||
name: "MaxLogLevelError",
|
||||
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
|
||||
),
|
||||
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
|
||||
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
|
||||
|
||||
// By default, no traits are enabled (all log levels available)
|
||||
.default(enabledTraits: []),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "Logging",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "InMemoryLogging",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "LoggingTests",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "InMemoryLoggingTests",
|
||||
dependencies: ["InMemoryLogging", "Logging"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
for target in package.targets
|
||||
where [.executable, .test, .regular].contains(
|
||||
target.type
|
||||
) {
|
||||
var settings = target.swiftSettings ?? []
|
||||
|
||||
// https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md
|
||||
// Require `any` for existential types.
|
||||
settings.append(.enableUpcomingFeature("ExistentialAny"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
|
||||
settings.append(.enableUpcomingFeature("MemberImportVisibility"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
|
||||
settings.append(.enableUpcomingFeature("InternalImportsByDefault"))
|
||||
|
||||
target.swiftSettings = settings
|
||||
}
|
||||
@@ -1,5 +1,10 @@
|
||||
# SwiftLog
|
||||
|
||||
[](https://swiftpackageindex.com/apple/swift-log/documentation)
|
||||
[](https://github.com/apple/swift-log/releases)
|
||||
[](https://swiftpackageindex.com/apple/swift-log)
|
||||
[](https://swiftpackageindex.com/apple/swift-log)
|
||||
|
||||
This repository contains a logging API implementation for Swift.
|
||||
SwiftLog provides a unified, performant, and ergonomic logging API that can be
|
||||
adopted by libraries and applications across the Swift ecosystem.
|
||||
@@ -7,7 +12,7 @@ adopted by libraries and applications across the Swift ecosystem.
|
||||
- 📚 **Documentation** and **tutorials** are available on the [Swift Package Index](https://swiftpackageindex.com/apple/swift-log)
|
||||
- 🚀 **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- 🪪 **License** is Apache 2.0, repeated in [LICENSE.txt](LICENSE.txt)
|
||||
- 🔒 **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md)
|
||||
- 🔒 **Security** issues should be reported via the process in [Security](https://github.com/apple/swift-log?tab=security-ov-file)
|
||||
- 🔀 **Available Logging Backends**: SwiftLog is an API package - you'll want to
|
||||
choose from the many
|
||||
[community-maintained logging backends](#available-log-handler-backends) for production use
|
||||
@@ -17,7 +22,7 @@ choose from the many
|
||||
The following snippet shows how to add SwiftLog to your Swift Package:
|
||||
|
||||
```swift
|
||||
// swift-tools-version: 6.1
|
||||
// swift-tools-version: 6.2.3
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
@@ -62,3 +67,8 @@ The community has built numerous specialized logging backends.
|
||||
A great way to discover available log backend implementations is searching the
|
||||
[Swift Package Index](https://swiftpackageindex.com/search?query=swift-log)
|
||||
for the `swift-log` keyword.
|
||||
|
||||
## Building with CMake
|
||||
|
||||
While Swift Package Manager (SPM) is the primary build system for development and testing, CMake build support is also available for integrated or mixed build environments if needed. Note that tests are not included in the CMake build, they are managed through Swift Package Manager with `swift test`.
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
|
||||
# Licensed under Apache License v2.0
|
||||
#
|
||||
# See LICENSE.txt for license information
|
||||
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
add_subdirectory(Logging)
|
||||
add_subdirectory(InMemoryLogging)
|
||||
@@ -0,0 +1,28 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
|
||||
# Licensed under Apache License v2.0
|
||||
#
|
||||
# See LICENSE.txt for license information
|
||||
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
add_library(InMemoryLogging
|
||||
"InMemoryLogHandler.swift"
|
||||
)
|
||||
|
||||
set_target_properties(InMemoryLogging PROPERTIES
|
||||
INTERFACE_INCLUDE_DIRECTORIES "$<BUILD_INTERFACE:$<TARGET_PROPERTY:Swift_MODULE_DIRECTORY>>;$<BUILD_INTERFACE:$<TARGET_FILE_DIR:InMemoryLogging>>")
|
||||
|
||||
target_compile_options(InMemoryLogging PRIVATE
|
||||
${SWIFT_LOG_COMMON_COMPILE_OPTIONS})
|
||||
|
||||
target_link_libraries(InMemoryLogging PRIVATE Logging)
|
||||
|
||||
_install_target(InMemoryLogging)
|
||||
set_property(GLOBAL APPEND PROPERTY SwiftLog_EXPORTS InMemoryLogging)
|
||||
@@ -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:)")
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
#===----------------------------------------------------------------------===#
|
||||
#
|
||||
# This source file is part of the Swift Logging API open source project
|
||||
#
|
||||
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
|
||||
# Licensed under Apache License v2.0
|
||||
#
|
||||
# See LICENSE.txt for license information
|
||||
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
#
|
||||
#===----------------------------------------------------------------------===#
|
||||
|
||||
add_library(Logging
|
||||
"Handlers/MultiplexLogHandler.swift"
|
||||
"Handlers/StreamLogHandler.swift"
|
||||
"Handlers/SwiftLogNoOpLogHandler.swift"
|
||||
"Locks.swift"
|
||||
"LogEvent.swift"
|
||||
"LogHandler.swift"
|
||||
"Logger+Attributes.swift"
|
||||
"Logger+With.swift"
|
||||
"Logger.swift"
|
||||
"LoggingSystem.swift"
|
||||
"MetadataProvider.swift"
|
||||
)
|
||||
|
||||
set_target_properties(Logging PROPERTIES
|
||||
INTERFACE_INCLUDE_DIRECTORIES "$<BUILD_INTERFACE:$<TARGET_PROPERTY:Swift_MODULE_DIRECTORY>>;$<BUILD_INTERFACE:$<TARGET_FILE_DIR:Logging>>")
|
||||
|
||||
target_compile_options(Logging PRIVATE
|
||||
${SWIFT_LOG_COMMON_COMPILE_OPTIONS})
|
||||
|
||||
_install_target(Logging)
|
||||
set_property(GLOBAL APPEND PROPERTY SwiftLog_EXPORTS Logging)
|
||||
@@ -1,29 +1,88 @@
|
||||
# 003: Accepting loggers in libraries
|
||||
# 003: Logger propagation in libraries
|
||||
|
||||
Accept loggers through method parameters to ensure proper metadata propagation.
|
||||
Propagate caller context by accepting a `Logger` parameter or reading the task-local
|
||||
``Logger/current`` — never by constructing your own logger.
|
||||
|
||||
## Overview
|
||||
|
||||
Libraries should accept logger instances through method parameters rather than
|
||||
storing them as instance variables. This practice ensures metadata (such as
|
||||
correlation IDs) is properly propagated down the call stack, while giving
|
||||
applications control over logging configuration.
|
||||
Libraries should obtain a `Logger` in one of two ways: accept one through a method
|
||||
parameter or read ``Logger/current`` from the task-local. Both approaches
|
||||
preserve the caller's metadata, log level, and handler choice. Constructing a logger
|
||||
inside a library — via ``Logger/init(label:)`` — takes those choices away from the
|
||||
application and breaks metadata propagation.
|
||||
|
||||
### Motivation
|
||||
|
||||
When libraries accept loggers as method parameters, they enable automatic
|
||||
propagation of contextual metadata attached to the logger instance. This is
|
||||
especially important for distributed systems where correlation IDs must flow
|
||||
through the entire request processing pipeline.
|
||||
The application controls logging: which backend, which log level, which metadata
|
||||
travels with each request. Libraries that participate in this picture obtain a logger
|
||||
the application has set up, rather than constructing their own from scratch. This
|
||||
ensures correlation IDs and other contextual metadata flow through the entire call
|
||||
stack, and gives the application a single place to redirect or filter all log output.
|
||||
|
||||
Two propagation mechanisms are available, and they coexist. Choose the explicit
|
||||
parameter when the library's API already accepts a `Logger` (or it's natural to add
|
||||
one) — the call site stays declarative about what gets logged where. Choose the
|
||||
task-local when adding a `logger:` parameter would pollute an API that otherwise has
|
||||
no logging concern in its signature. Application code binds the initial task-local;
|
||||
library code reads it and updates the metadata.
|
||||
|
||||
### Example
|
||||
|
||||
#### Recommended: Accept logger through method parameters
|
||||
#### Recommended: Read ``Logger/current`` from the task-local
|
||||
|
||||
When there is no `logger:` parameter in the API, read the
|
||||
task-local. The application's accumulated metadata (`request.id`, etc.) flows in
|
||||
automatically without an explicit hand-off.
|
||||
|
||||
```swift
|
||||
// ✅ Good: Pass the logger through method parameters.
|
||||
// ✅ Good: Library reads Logger.current; caller scopes context via withLogger.
|
||||
public struct AnalyticsClient {
|
||||
public func track(_ event: String) {
|
||||
Logger.current.info("event", metadata: ["event.name": "\(event)"])
|
||||
}
|
||||
}
|
||||
|
||||
// Application binds at @main and scopes per-request metadata.
|
||||
@main
|
||||
struct MyServer {
|
||||
static func main() async throws {
|
||||
let logger = Logger(label: "my-server")
|
||||
try await withLogger(logger) { _ in
|
||||
try await runServices()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func handleRequest(_ req: HTTPRequest) async throws {
|
||||
try await withLogger(mergingMetadata: ["request.id": "\(req.id)"]) { _ in
|
||||
AnalyticsClient().track("request.received") // sees request.id automatically
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For per-statement metadata, pass it via the `metadata:` parameter on the log call:
|
||||
|
||||
```swift
|
||||
Logger.current.info("step", metadata: ["step.name": "validate"])
|
||||
```
|
||||
|
||||
For a few back-to-back lines, take a local copy and stamp metadata there — also no
|
||||
propagation:
|
||||
|
||||
```swift
|
||||
var local = Logger.current
|
||||
local[metadataKey: "step.name"] = "validate"
|
||||
local.info("entering")
|
||||
local.info("done")
|
||||
```
|
||||
|
||||
#### Alternative: Accept logger through method parameters
|
||||
|
||||
```swift
|
||||
// ✅ Good: Pass the logger through method parameters,
|
||||
// default to Logger.current in the public API.
|
||||
struct RequestProcessor {
|
||||
func processRequest(_ request: HTTPRequest, logger: Logger) async throws -> HTTPResponse {
|
||||
func processRequest(_ request: HTTPRequest, logger: Logger = Logger.current) async throws -> HTTPResponse {
|
||||
// Add structured metadata that every log statement should contain.
|
||||
var logger = logger
|
||||
logger[metadataKey: "request.method"] = "\(request.method)"
|
||||
@@ -31,44 +90,40 @@ struct RequestProcessor {
|
||||
logger[metadataKey: "request.id"] = "\(request.id)"
|
||||
|
||||
logger.debug("Processing request")
|
||||
|
||||
|
||||
// Pass the logger down to maintain metadata context.
|
||||
let validatedData = try validateRequest(request, logger: logger)
|
||||
let result = try await executeBusinessLogic(validatedData, logger: logger)
|
||||
|
||||
|
||||
logger.debug("Request processed successfully")
|
||||
return result
|
||||
}
|
||||
|
||||
|
||||
private func validateRequest(_ request: HTTPRequest, logger: Logger) throws -> ValidatedRequest {
|
||||
logger.debug("Validating request parameters")
|
||||
// Include validation logic that uses the same logger context.
|
||||
return ValidatedRequest(request)
|
||||
}
|
||||
|
||||
|
||||
private func executeBusinessLogic(_ data: ValidatedRequest, logger: Logger) async throws -> HTTPResponse {
|
||||
logger.debug("Executing business logic")
|
||||
|
||||
// Further propagate the logger to other services.
|
||||
let dbResult = try await databaseService.query(data.query, logger: logger)
|
||||
|
||||
logger.debug("Business logic completed")
|
||||
return HTTPResponse(data: dbResult)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Alternative: Accept logger through initializer when appropriate
|
||||
#### Alternative: Accept logger through initializer for long-lived components
|
||||
|
||||
```swift
|
||||
// ✅ Acceptable: Logger through initializer for long-lived components
|
||||
// ⚠️ Acceptable: Logger through initializer for long-lived components
|
||||
final class BackgroundJobProcessor {
|
||||
private let logger: Logger
|
||||
|
||||
|
||||
init(logger: Logger) {
|
||||
self.logger = logger
|
||||
}
|
||||
|
||||
|
||||
func run() async {
|
||||
// Execute some long running work
|
||||
logger.debug("Update about long running work")
|
||||
@@ -79,22 +134,52 @@ final class BackgroundJobProcessor {
|
||||
|
||||
#### Avoid: Libraries creating their own loggers
|
||||
|
||||
Libraries might create their own loggers; however, this leads to two problems.
|
||||
First, users of the library can't inject their own loggers which means they have
|
||||
no control in customizing the log level or log handler. Secondly, it breaks the
|
||||
metadata propagation since users can't pass in a logger with already attached
|
||||
metadata.
|
||||
Constructing ``Logger/init(label:)`` inside a library takes control over the handler, log
|
||||
level, and base metadata away from the application. The application cannot redirect,
|
||||
filter, or silence the library's output.
|
||||
|
||||
```swift
|
||||
// ❌ Bad: Library creates its own logger
|
||||
// ❌ Bad: Library creates its own logger — loses caller's context.
|
||||
final class MyLibrary {
|
||||
private let logger = Logger(label: "MyLibrary") // Loses all context
|
||||
}
|
||||
|
||||
// ✅ Good: Library accepts logger from caller
|
||||
final class MyLibrary {
|
||||
func operation(logger: Logger) {
|
||||
// Maintains caller's context and metadata
|
||||
}
|
||||
private let logger = Logger(label: "MyLibrary")
|
||||
}
|
||||
```
|
||||
|
||||
``Logger/init(label:)`` is for the application — typically at `@main` paired with `.withLogger()`.
|
||||
Library code, including internal application modules, should not construct loggers.
|
||||
If they do, setting up the global factory with ``LoggingSystem/bootstrap(_:)`` allows
|
||||
enforcing a specific factory on all the loggers constructed in the process. This
|
||||
does not necessary need to be the same factory as was used to create the task-local
|
||||
logger.
|
||||
|
||||
#### Avoid: Relying on ``Logger/current`` across non-Task boundaries
|
||||
|
||||
``Logger/current`` is backed by a `TaskLocal` and propagates through Swift's structured
|
||||
concurrency model only. Callbacks invoked on non-Task threads — GCD blocks,
|
||||
`URLSession` completion handlers, delegate methods dispatched onto specific queues,
|
||||
`NotificationCenter` observers, C-API callbacks — see the *default* fallback logger,
|
||||
not the bound one. Metadata bound by the calling `Task` is invisible inside those
|
||||
callbacks.
|
||||
|
||||
```swift
|
||||
// ❌ Bad: completion handler runs without the Task context; Logger.current is the fallback.
|
||||
try await withLogger(mergingMetadata: ["request.id": "r1"]) { _ in
|
||||
URLSession.shared.dataTask(with: req) { data, _, _ in
|
||||
Logger.current.info("response") // empty-label fallback, no request.id
|
||||
}.resume()
|
||||
}
|
||||
```
|
||||
|
||||
For libraries with async completion-handler APIs, accept an explicit `Logger` parameter.
|
||||
If capturing and rebinding across the boundary is the only option:
|
||||
|
||||
```swift
|
||||
// ✅ Good: capture before the boundary, rebind on the other side.
|
||||
try await withLogger(mergingMetadata: ["request.id": "r1"]) { captured in
|
||||
URLSession.shared.dataTask(with: req) { data, _, _ in
|
||||
withLogger(captured) { _ in // Bind Logger.current inside the callback
|
||||
Logger.current.info("response") // Logger.current now has request.id
|
||||
}
|
||||
}.resume()
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,81 @@
|
||||
# 004: Testing code that logs
|
||||
|
||||
Validate what you code logs by capturing entries in memory rather than bootstrapping a process-wide backend.
|
||||
|
||||
## Overview
|
||||
|
||||
Import and use `InMemoryLogging`, which provides an `InMemoryLogHandler` that collects every emitted record into an array you can inspect.
|
||||
Keep a handler you create local to each test.
|
||||
Each handler that you create in a test has no shared state, so the test stays isolated is safe to run on parallel with other tests.
|
||||
Don't use ``LoggingSystem/bootstrap(_:)`` in a test, it sets one process-wide backend and traps if called twice.
|
||||
|
||||
Add the product to your test target:
|
||||
|
||||
```swift
|
||||
.product(name: "InMemoryLogging", package: "swift-log")
|
||||
```
|
||||
|
||||
### Capture logs from a logger you pass in
|
||||
|
||||
When the code under test accepts a `Logger` (see <doc:003-AcceptingLoggers>), back it with
|
||||
an `InMemoryLogHandler` and validate the results on `entries`.
|
||||
|
||||
The following code illustrates how to set up and validate a handler using `InMemoryLogging` to check the expected results:
|
||||
|
||||
```swift
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct RequestProcessor {
|
||||
func handle(id: String, logger: Logger) {
|
||||
logger.info("request received", metadata: ["request.id": "\(id)"])
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func stampsRequestID() {
|
||||
let handler = InMemoryLogHandler()
|
||||
let logger = Logger(label: "test", factory: { _ in handler })
|
||||
|
||||
RequestProcessor().handle(id: "42", logger: logger)
|
||||
|
||||
#expect(handler.entries.count == 1)
|
||||
#expect(handler.entries[0].message == "request received")
|
||||
#expect(handler.entries[0].metadata["request.id"] == "42")
|
||||
}
|
||||
```
|
||||
|
||||
Each `Entry` is equatable and exposes `level`, `message`, `metadata`, and `error`.
|
||||
The handler log level defaults to ``Logger/Level/info``; set `handler.logLevel = .trace` before you use it to
|
||||
capture lower levels.
|
||||
|
||||
### Capture logs from code that reads `Logger.current`
|
||||
|
||||
When the code you want to test reads the task-local ``Logger/current`` instead of taking a parameter, bind an `InMemoryLogHandler` for the scope of that by using ``withLogger(logLevel:handler:metadata:_:)-2pd9p``.
|
||||
The handler shares its storage by reference, so the copy you hold sees what was logged.
|
||||
|
||||
Bind the handler for the scope of the call and validate the captured entry:
|
||||
|
||||
```swift
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct AnalyticsClient {
|
||||
func track(_ event: String) {
|
||||
Logger.current.info("event", metadata: ["event.name": "\(event)"])
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func tracksEvent() {
|
||||
let handler = InMemoryLogHandler()
|
||||
withLogger(handler: handler) { _ in
|
||||
AnalyticsClient().track("signup") // calls Logger.current.info(...)
|
||||
}
|
||||
|
||||
#expect(handler.entries.count == 1)
|
||||
#expect(handler.entries[0].metadata["event.name"] == "signup")
|
||||
}
|
||||
```
|
||||
@@ -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]
|
||||
@@ -110,6 +102,136 @@ public struct PrintLogHandler: LogHandler {
|
||||
|
||||
```
|
||||
|
||||
### Constructing handlers that need more than a label
|
||||
|
||||
Many log handler backends need more than a `label` in order to construct them: a file path, a remote address, credentials, or
|
||||
a buffer. A handler is an ordinary value that you construct, so nothing constrains its
|
||||
initializer — it can take any parameters it needs, and it can `throw`. There is no
|
||||
protocol-required `init(label:)`. The single `label` argument on factory methods such as
|
||||
`StreamLogHandler.standardOutput(label:)` is a convention, not a requirement.
|
||||
|
||||
Open expensive or fallible resources, such as a file, a socket, early and up front in your own initializer that can `throw`, so that failures surface at setup time.
|
||||
``LogHandler/log(event:)`` cannot throw, so an error deferred to logging time has nowhere to go.
|
||||
Keep the handler `struct` cheap and copyable by placing any shared resource behind a thread-safe reference type.
|
||||
Value semantics apply to a handler's *configuration* — its level and metadata — not its *destination*, so copies writing to
|
||||
the same file are correct and expected.
|
||||
|
||||
The `FileLogHandler` below opens its file once, in an initializer that throws and exception when you create it with an overlapping `Destination`.
|
||||
The handler `struct` itself stays a cheap, copyable value:
|
||||
|
||||
```swift
|
||||
import Foundation
|
||||
import Logging
|
||||
import Synchronization
|
||||
|
||||
/// A log handler that appends formatted log lines to a file on disk.
|
||||
public struct FileLogHandler: LogHandler {
|
||||
/// The shared, thread-safe destination. Open it once, then share it across handlers: because
|
||||
/// the destination is a reference type, all those value-semantic handlers write through a single
|
||||
/// locked file handle.
|
||||
public final class Destination: @unchecked Sendable {
|
||||
private let fileHandle: Mutex<FileHandle>
|
||||
|
||||
/// Opens `url` for appending. All validation happens here, at setup time.
|
||||
public init(writingTo url: URL) throws {
|
||||
let fileManager = FileManager.default
|
||||
if !fileManager.fileExists(atPath: url.path) {
|
||||
guard fileManager.createFile(atPath: url.path, contents: nil) else {
|
||||
throw Failure.cannotCreateFile(url)
|
||||
}
|
||||
}
|
||||
self.fileHandle = .init(try FileHandle(forWritingTo: url))
|
||||
_ = try self.fileHandle.withLock { try $0.seekToEnd() }
|
||||
}
|
||||
|
||||
func write(_ line: String) {
|
||||
// `log(event:)` cannot throw, so a write failure is handled here, not propagated.
|
||||
do {
|
||||
try self.fileHandle.withLock { try $0.write(contentsOf: Data(line.utf8)) }
|
||||
} catch {
|
||||
// Surface the failure without crashing the application.
|
||||
try? FileHandle.standardError.write(contentsOf: Data("FileLogHandler: \(error)\n".utf8))
|
||||
}
|
||||
}
|
||||
|
||||
/// Flushes and closes the file. Call this during shutdown.
|
||||
public func close() {
|
||||
self.fileHandle.withLock { try? $0.close() }
|
||||
}
|
||||
}
|
||||
|
||||
/// Errors thrown while opening a ``Destination``.
|
||||
public enum Failure: Error {
|
||||
case cannotCreateFile(URL)
|
||||
}
|
||||
|
||||
private let label: String
|
||||
private let destination: Destination
|
||||
|
||||
// Per-logger configuration — this is what must carry value semantics.
|
||||
public var logLevel: Logger.Level = .info
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
/// Cheap and non-throwing, so it is safe to call from a bootstrap factory closure per label.
|
||||
public init(label: String, destination: Destination, metadataProvider: Logger.MetadataProvider? = nil) {
|
||||
self.label = label
|
||||
self.destination = destination
|
||||
self.metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
public func log(event: LogEvent) {
|
||||
var merged = self.metadata
|
||||
if let provided = self.metadataProvider?.get() {
|
||||
merged.merge(provided, uniquingKeysWith: { _, new in new })
|
||||
}
|
||||
if let explicit = event.metadata {
|
||||
merged.merge(explicit, uniquingKeysWith: { _, new in new })
|
||||
}
|
||||
let renderedMetadata =
|
||||
merged.isEmpty
|
||||
? ""
|
||||
: " " + merged.sorted { $0.key < $1.key }.map { "\($0.key)=\($0.value)" }.joined(separator: " ")
|
||||
self.destination.write("\(event.level) \(self.label):\(renderedMetadata) \(event.message)\n")
|
||||
}
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[key] }
|
||||
set { self.metadata[key] = newValue }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Using your log handler
|
||||
|
||||
Construct the destination where you can use `try` to build a logger backed by your handler, then bind it
|
||||
as ``Logger/current`` for the application's lifetime using `withLogger`:
|
||||
|
||||
```swift
|
||||
// Open the file once, where setup can throw.
|
||||
let destination = try FileLogHandler.Destination(writingTo: URL(fileURLWithPath: "/var/log/myapp.log"))
|
||||
defer { destination.close() }
|
||||
|
||||
// Build a logger backed by the handler, then bind it for the scope.
|
||||
let logger = Logger(label: "app") { label in
|
||||
FileLogHandler(label: label, destination: destination)
|
||||
}
|
||||
try await withLogger(logger) { logger in
|
||||
logger.info("Application started")
|
||||
// Code in this scope reads the handler through Logger.current.
|
||||
}
|
||||
```
|
||||
|
||||
The `try` on `Destination` is where setup fails if the path is unwritable: validation happens
|
||||
before the logger is constructed, so you never need a throwing factory overload.
|
||||
Use the same pattern for handlers that connect to a remote service:
|
||||
- validate and connect up front
|
||||
- keep ``LogHandler/log(event:)`` non-blocking by buffering onto a background task
|
||||
- provide a `close()` or `shutdown()` (or use [Swift Service Lifecycle](https://github.com/swift-server/swift-service-lifecycle) service) to flush on shutdown
|
||||
|
||||
For runtime failures the handler can't avoid, such as a full disk or a broken pipe, degrade gracefully inside `log(event:)` by dropping the log message, retrying, or reporting to `stderr`.
|
||||
Never call `fatalError` on the logging path.
|
||||
|
||||
### Advanced features
|
||||
|
||||
#### Metadata providers
|
||||
@@ -128,41 +250,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]
|
||||
@@ -176,7 +287,7 @@ public struct PrintLogHandler: LogHandler {
|
||||
base: Logger.Metadata,
|
||||
provider: Logger.MetadataProvider?,
|
||||
explicit: Logger.Metadata?
|
||||
) -> Logger.Metadata? {
|
||||
) -> Logger.Metadata {
|
||||
var metadata = base
|
||||
|
||||
let provided = provider?.get() ?? [:]
|
||||
@@ -199,6 +310,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.
|
||||
|
||||
@@ -41,3 +41,4 @@ practice includes:
|
||||
- <doc:001-ChoosingLogLevels>
|
||||
- <doc:002-StructuredLogging>
|
||||
- <doc:003-AcceptingLoggers>
|
||||
- <doc:004-TestingLogging>
|
||||
@@ -35,4 +35,15 @@ If you have any questions, ask in an issue on GitHub.
|
||||
|
||||
## Topics
|
||||
|
||||
### Implemented Proposals
|
||||
|
||||
- <doc:SLG-0001-metadata-providers>
|
||||
- <doc:SLG-0002>
|
||||
- <doc:SLG-0003>
|
||||
- <doc:SLG-0004-metadata-value-attributes>
|
||||
- <doc:SLG-0005-log-event-LogHandler-API>
|
||||
- <doc:SLG-0006-task-local-logger>
|
||||
|
||||
### Proposal Template
|
||||
|
||||
- <doc:SLG-NNNN>
|
||||
@@ -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: **Approved**
|
||||
- Issue: [apple/swift-log#204](https://github.com/apple/swift-log/issues/204)
|
||||
- Implementation:
|
||||
- [apple/swift-log#453](https://github.com/apple/swift-log/pull/453)
|
||||
- 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,439 @@
|
||||
# SLG-0006: Task-local logger with automatic metadata propagation
|
||||
|
||||
Accumulate structured logging metadata across async call stacks using task-local storage.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0006
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#261](https://github.com/apple/swift-log/issues/261)
|
||||
- Implementation: [apple/swift-log#459](https://github.com/apple/swift-log/pull/459)
|
||||
- Feature flag: none
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
This proposal adds task-local logger storage so that metadata can accumulate across async
|
||||
call stacks without threading a `Logger` through every function signature.
|
||||
|
||||
### Motivation
|
||||
|
||||
Metadata propagation requires threading a logger through every layer. Every function on
|
||||
the path from request ingress to the bottom of the call stack has to accept, mutate, and
|
||||
forward a `Logger`:
|
||||
|
||||
```swift
|
||||
func handleHTTPRequest(_ request: HTTPRequest, logger: Logger) async throws {
|
||||
var logger = logger
|
||||
logger[metadataKey: "request.id"] = "\(request.id)"
|
||||
try await processBusinessLogic(request, logger: logger)
|
||||
}
|
||||
```
|
||||
|
||||
Libraries must choose between polluting their public API with a `logger:` parameter and
|
||||
losing all the caller's context. There is no third option today.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Use Swift's `@TaskLocal` to propagate a logger with accumulated metadata. The caller sets up
|
||||
a scope, callees read `Logger.current`:
|
||||
|
||||
```swift
|
||||
func handleRequest(_ request: HTTPRequest) async throws -> HTTPResponse {
|
||||
try await withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
logger.info("Handling request") // Has request.id automatically
|
||||
return try await processRequest(request) // no logger parameter needed
|
||||
}
|
||||
}
|
||||
|
||||
func processRequest(_ request: HTTPRequest) async throws -> User {
|
||||
Logger.current.debug("Processing...") // Has request.id automatically
|
||||
DatabaseClient.query(request.sqlQuery)
|
||||
}
|
||||
```
|
||||
|
||||
Libraries keep their APIs clean while still emitting logs with the caller's full context.
|
||||
A library reads `Logger.current` directly — the caller's accumulated metadata flows in
|
||||
automatically without a `logger:` parameter:
|
||||
|
||||
```swift
|
||||
public struct DatabaseClient {
|
||||
public static func query(_ sql: String) async throws -> [Row] {
|
||||
Logger.current.debug("Executing", metadata: ["sql": "\(sql)"])
|
||||
return try await performQuery(sql)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Wiring it up with swift-service-lifecycle.** At the application entry point, bind the
|
||||
bootstrapped logger once; service lifecycle propagates the task-local through the
|
||||
`ServiceGroup` and into every task spawned from its `run()`:
|
||||
|
||||
```swift
|
||||
@main
|
||||
struct MyServer {
|
||||
static func main() async throws {
|
||||
let logger = Logger(label: "my-server")
|
||||
try await withLogger(logger) { _ in
|
||||
let serviceGroup = ServiceGroup(
|
||||
configuration: .init(
|
||||
services: [HTTPServer(), BackgroundWorker()],
|
||||
gracefulShutdownSignals: [.sigint],
|
||||
cancellationSignals: [.sigterm],
|
||||
logger: logger
|
||||
)
|
||||
)
|
||||
try await serviceGroup.run()
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Metadata accumulates through nesting and task-local values propagate through structured
|
||||
concurrency (`async let`, `withTaskGroup`, child `Task {}`). `Task.detached` does not
|
||||
inherit context — capture the logger explicitly if needed.
|
||||
|
||||
### Detailed design
|
||||
|
||||
#### `Logger.current`
|
||||
|
||||
Returns the logger bound by the nearest enclosing `withLogger` scope. If none is active,
|
||||
returns the process-wide unbound default: a `Logger(label: "")` constructed via
|
||||
`LoggingSystem.factory` the first time the task-local is touched.
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
/// The current task-local logger.
|
||||
///
|
||||
/// Returns the logger bound by the nearest enclosing ``withLogger(_:_:)`` scope.
|
||||
/// If none is active, returns the process-wide unbound default: a
|
||||
/// `Logger(label: "")` cached from the first time the task-local is touched.
|
||||
///
|
||||
/// Task-local values propagate through structured concurrency (`async let`,
|
||||
/// `withTaskGroup`, child `Task {}`) but are **not** inherited by `Task.detached`.
|
||||
/// Capture the logger explicitly across detached boundaries.
|
||||
///
|
||||
/// For many log calls in a tight scope, prefer extracting the logger once —
|
||||
/// either `let logger = Logger.current` or the closure's `logger` parameter
|
||||
/// from `withLogger { logger in ... }` — instead of re-reading the task-local
|
||||
/// on every call.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
public static var current: Logger { get }
|
||||
}
|
||||
```
|
||||
|
||||
The per-symbol `@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)` mirrors
|
||||
`@TaskLocal`'s own runtime availability.
|
||||
|
||||
#### `withLogger` free functions
|
||||
|
||||
Three overload groups, each with sync and async variants. The closure receives the logger
|
||||
as a parameter to avoid repeated task-local lookups inside the closure body.
|
||||
|
||||
**Bind a specific logger:**
|
||||
|
||||
```swift
|
||||
/// Runs `operation` with `logger` bound to the task-local context.
|
||||
///
|
||||
/// Code called within `operation` can read the logger via ``Logger/current`` without an
|
||||
/// explicit parameter. Binding a different logger with this overload **replaces** the
|
||||
/// current task-local logger; any metadata accumulated by an outer
|
||||
/// ``withLogger(mergingMetadata:_:)`` or
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)`` scope is not carried over.
|
||||
///
|
||||
/// This overload is the application-bootstrap binding mechanism: pass a `Logger`
|
||||
/// constructed via ``Logger/init(label:)`` at your application entry point. Because
|
||||
/// ``Logger/init(label:)`` consults ``LoggingSystem/factory``, the constructed `Logger`
|
||||
/// only carries a useful handler once ``LoggingSystem/bootstrap(_:)`` has been called.
|
||||
/// For mid-call-tree backend swaps that should work without bootstrap (tests, scoped
|
||||
/// routing), use ``withLogger(logLevel:handler:metadata:_:)`` instead — it modifies the
|
||||
/// current logger's handler in place without constructing a new one.
|
||||
///
|
||||
/// let logger = Logger(label: "app")
|
||||
/// await withLogger(logger) { logger in
|
||||
/// logger.info("Application started")
|
||||
/// await handleRequests() // reads Logger.current
|
||||
/// }
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The closure to run with `logger` bound. Receives `logger` as a
|
||||
/// parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result
|
||||
|
||||
/// Runs `operation` with `logger` bound to the task-local context. Async variant of
|
||||
/// ``withLogger(_:_:)``; see that function for full semantics.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The async closure to run with `logger` bound. Receives `logger` as
|
||||
/// a parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result
|
||||
```
|
||||
|
||||
**Append metadata for a scope:**
|
||||
|
||||
```swift
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` **layered on
|
||||
/// top of** the inherited base metadata. Keys present in `metadata` override existing
|
||||
/// keys with the same name; other inherited metadata is preserved. Handler and log
|
||||
/// level are unchanged.
|
||||
///
|
||||
/// Use this overload at request boundaries and any point where context should
|
||||
/// accumulate. Nested ``withLogger(mergingMetadata:_:)`` scopes layer on top of each
|
||||
/// other.
|
||||
///
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
/// logger.info("Handling request")
|
||||
/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in
|
||||
/// logger.info("Authenticated") // sees both request.id and user.id
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` layered on
|
||||
/// top of the inherited base metadata. Async variant of ``withLogger(mergingMetadata:_:)``;
|
||||
/// see that function for full semantics.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The async closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result
|
||||
```
|
||||
|
||||
**Replace aspects of the current logger:**
|
||||
|
||||
```swift
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are **replaced** by
|
||||
/// the provided arguments. `nil` parameters leave the corresponding aspect unchanged.
|
||||
///
|
||||
/// Unlike ``withLogger(mergingMetadata:_:)``, which layers metadata on top of the
|
||||
/// inherited base, this overload **replaces** the base metadata when `metadata` is
|
||||
/// non-nil. Pass `metadata: [:]` to wipe the inherited metadata entirely.
|
||||
///
|
||||
/// With no arguments, this overload re-binds ``Logger/current`` unchanged — a convenient
|
||||
/// way to extract it into a local variable for repeated use inside the closure.
|
||||
///
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { _ in
|
||||
/// // Background job: start a scope with metadata unrelated to the request.
|
||||
/// withLogger(metadata: ["job.id": "\(job.id)"]) { logger in
|
||||
/// logger.info("running") // metadata: job.id only — request.id wiped
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When
|
||||
/// `nil`, the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for
|
||||
/// the scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to
|
||||
/// start a scope from a known state. When `nil`, the inherited base metadata is
|
||||
/// preserved.
|
||||
/// - operation: The closure to run with the modified logger bound. Receives the
|
||||
/// modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are replaced by
|
||||
/// the provided arguments. Async variant of
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)``; see that function for full semantics.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When
|
||||
/// `nil`, the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for
|
||||
/// the scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to
|
||||
/// start a scope from a known state. When `nil`, the inherited base metadata is
|
||||
/// preserved.
|
||||
/// - operation: The async closure to run with the modified logger bound. Receives
|
||||
/// the modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result
|
||||
```
|
||||
|
||||
Calling `withLogger { logger in ... }` with no arguments is the single-lookup idiom for
|
||||
extracting `Logger.current` into a local variable for repeated use inside the closure —
|
||||
analogous to `withSpan { span in ... }` in `swift-distributed-tracing`.
|
||||
|
||||
|
||||
#### Relationship to `MetadataProvider`
|
||||
|
||||
Metadata merged via `withLogger(mergingMetadata:)` is written into the handler's base
|
||||
metadata on the per-task logger copy. If a handler has a `MetadataProvider` attached — for
|
||||
example a bootstrapped OpenTelemetry provider that reads `trace.id` from `ServiceContext` —
|
||||
the provider still runs at log-emission time and follows the handler's conventional merge
|
||||
order (base < provider < per-statement).
|
||||
|
||||
This proposal does **not** add a `metadataProvider:` parameter to the modifying overload.
|
||||
Application code that wants to swap the provider for a scope should construct a new `Logger`
|
||||
and use the binding overload. Keeping the two concerns separate avoids shipping the
|
||||
replace-vs-compose question as part of the core API.
|
||||
|
||||
### API stability
|
||||
|
||||
**For existing `Logger` users:** no changes. The new API is purely additive.
|
||||
|
||||
**For existing `LogHandler` implementations:** no changes required. Task-local loggers use
|
||||
the same `LogHandler` interface; no new protocol requirements are added.
|
||||
|
||||
**Package platform minimums.** `Package.swift` intentionally does not gain a `platforms:`
|
||||
clause. Each new symbol carries `@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)`
|
||||
to match `@TaskLocal`'s runtime availability. Callers targeting older deployment versions
|
||||
keep working; they just can't call the task-local API.
|
||||
|
||||
**ABI and resilience.** The `withLogger` overloads are `@inlinable`: their bodies are thin
|
||||
glue — read `Logger.current`, copy-and-modify the logger, then bind it for the scope — so
|
||||
inlining them removes a cross-module call at each scope entry. The internal
|
||||
`withTaskLocalLogger` bridge over `TaskLocal.withValue` is `@usableFromInline` (not
|
||||
`@inlinable`), letting the inlinable bodies reach it without exposing the `@TaskLocal`
|
||||
storage. That storage, the bridge, and `Logger.current` all stay non-`@inlinable`, so the
|
||||
genuinely evolvable state — how the task-local is stored and how the unbound default is
|
||||
resolved — remains behind a resilient boundary and can change without breaking
|
||||
already-compiled clients. Only the small, settled control flow of the wrappers is committed
|
||||
to ABI.
|
||||
|
||||
**Source compatibility caveat.** The name `withLogger` is added at the top-level namespace.
|
||||
Codebases that previously defined their own free `withLogger` function may need to
|
||||
fully-qualify calls (`Logging.withLogger(...)`) or rename their own.
|
||||
|
||||
### Future directions
|
||||
|
||||
- **`Logger.withMetadata(merging:) -> Logger` and `Logger.withMetadata(replacing:) -> Logger`
|
||||
value-level instance methods.** Construct a derived `Logger` value (not a scope) with
|
||||
metadata layered onto or wholly replacing the receiver's metadata. The scope-level
|
||||
equivalents (`withLogger(mergingMetadata:)` and `withLogger(metadata:)`) ship in this
|
||||
proposal; the value-level forms are useful for per-statement metadata that should not
|
||||
propagate via the task-local — for example, a library that wants to stamp a key on its
|
||||
own log lines without pushing it onto `Logger.current` (avoiding leakage into downstream
|
||||
callees).
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Task-local metadata dictionary instead of task-local logger
|
||||
|
||||
Make only the metadata dictionary task-local, so ad-hoc `Logger(label:)` calls automatically
|
||||
merge it. Rejected because it changes default behavior for all existing logger creation
|
||||
(breaking semantic change) and overlaps with `swift-distributed-tracing`'s
|
||||
`ServiceContext`.
|
||||
|
||||
#### Static methods on `Logger` instead of free functions
|
||||
|
||||
`Logger.withCurrent(...)` instead of `withLogger(...)`. Rejected — inconsistent with
|
||||
`withSpan(...)` from `swift-distributed-tracing` and `withMetricsFactory(...)` from
|
||||
`swift-metrics`. Free functions follow the established ecosystem convention.
|
||||
|
||||
#### Use `ServiceContext` from swift-distributed-tracing instead of a new task-local
|
||||
|
||||
Store metadata in the existing `ServiceContext` — propagated by `swift-service-context`,
|
||||
the leaf package already designed as a shared propagation primitive — rather than
|
||||
introducing a second `@TaskLocal`. Rejected because the two propagation channels serve
|
||||
different use cases: `ServiceContext` carries *distributed* correlation (trace/span IDs,
|
||||
baggage) that flows across process boundaries, while `withLogger(mergingMetadata:)`
|
||||
accumulates *local* per-scope logger configuration (log level, handler, and application
|
||||
metadata like `request.id`) that is meaningful only within a single process. The
|
||||
task-local logger also carries more than metadata — it holds the `LogHandler`, log
|
||||
level, and label, none of which belong in a context intended for cross-process propagation.
|
||||
The existing `MetadataProvider` already bridges the two systems at log-emission time:
|
||||
handlers read trace/span IDs from `ServiceContext` without swift-log depending on it.
|
||||
|
||||
#### No closure parameter — require `Logger.current` inside the closure
|
||||
|
||||
`withLogger(logger) { ... }` without a parameter, reading `Logger.current` inside. Rejected
|
||||
because passing the logger avoids repeated task-local lookups, follows the `withSpan`
|
||||
convention, and makes it obvious at the call site which logger is in use.
|
||||
|
||||
#### Not propagating metadata across module boundaries by default
|
||||
|
||||
Expose a public `TaskLocal<Logger>` extension surface so that each module can declare
|
||||
its own scoped logger and stay structurally isolated from other modules — pushes on one
|
||||
module's task-local would be invisible to another's reads. Rejected for two reasons.
|
||||
|
||||
First, the public surface cost: `@TaskLocal`-declared task-locals require the `$logger`
|
||||
projection syntax for the scope methods (`MyApp.$logger.withMetadata(merging: …) { … }`),
|
||||
which is unfamiliar and easy to get wrong; alternatively, exposing `TaskLocal<Logger>`
|
||||
typed properties would leak a stdlib type into the swift-log surface that we'd rather
|
||||
keep internal. Hiding the task-local behind `Logger.current` and the `withLogger` free
|
||||
functions trades isolation for a cleaner API.
|
||||
|
||||
Second, the leak case is disciplinable. The only way library code propagates its own
|
||||
metadata downstream through `Logger.current` is by calling `withLogger(mergingMetadata:)`
|
||||
or `withLogger(metadata:)`. The documented contract is that those overloads are
|
||||
application-side APIs: libraries read `Logger.current` and use per-statement `metadata:`
|
||||
or a local copy for their own context; they do not push. Per-module isolation would make
|
||||
the leak impossible *by construction* even when discipline fails, but it would also
|
||||
fragment cross-cutting metadata propagation (`request.id` accumulated at the application
|
||||
layer would not appear on library log lines without an explicit bridge from one
|
||||
task-local to another) — which is the propagation we most want by default.
|
||||
|
||||
If structural isolation turns out to matter for specific use cases, the public
|
||||
`TaskLocal<Logger>` extension surface can be added as a non-breaking follow-up.
|
||||
|
||||
#### Use another third-party dependency management package
|
||||
|
||||
Swift packages ecosystem has packages for managing dependencies, one of those can
|
||||
be used to handle a task-local `Logger` instance. Rejected because if a library
|
||||
wants to benefit from a common logger without adding it to its API surface,
|
||||
it would have to depend on that extra package, effectively imposing that choice on
|
||||
the application. But the dependency mechanism is an application-level decision,
|
||||
an app may prefer a different approach, which leads to fragmentation or extra solutions
|
||||
to bridge them.
|
||||
|
||||
#### Let applications create their own task-local logger objects
|
||||
|
||||
Applications can declare their own task-local `Logger` instance and API explicitly,
|
||||
or via another dependency mechanism package. Rejected because it leaves library
|
||||
dependencies out of the picture and hurts discoverability and composability
|
||||
of the solution.
|
||||
@@ -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``
|
||||
|
||||
@@ -9,3 +9,8 @@
|
||||
- ``array(_:)``
|
||||
- ``dictionary(_:)``
|
||||
|
||||
### Working with attributes
|
||||
|
||||
- ``attributed(_:attributes:)``
|
||||
- ``attributes``
|
||||
|
||||
@@ -10,39 +10,63 @@
|
||||
- ``init(label:factory:)-6iktu``
|
||||
- ``MetadataProvider``
|
||||
|
||||
### Task-local logger
|
||||
|
||||
- ``current``
|
||||
- ``withLogger(_:_:)-3dt06``
|
||||
- ``withLogger(_:_:)-70nli``
|
||||
- ``withLogger(mergingMetadata:_:)-2c7dy``
|
||||
- ``withLogger(mergingMetadata:_:)-3eduo``
|
||||
- ``withLogger(logLevel:handler:metadata:_:)-2pd9p``
|
||||
- ``withLogger(logLevel:handler:metadata:_:)-5nmw6``
|
||||
|
||||
### Sending trace log messages
|
||||
|
||||
- ``trace(_:metadata:file:function:line:)``
|
||||
- ``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 +76,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
|
||||
|
||||
@@ -8,9 +8,12 @@
|
||||
- ``standardOutput(label:metadataProvider:)``
|
||||
- ``standardError(label:)``
|
||||
- ``standardError(label:metadataProvider:)``
|
||||
- ``init(label:stream:)``
|
||||
- ``init(label:stream:metadataProvider:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(event:)``
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
@@ -22,3 +25,8 @@
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
|
||||
### Configuring the timestamp
|
||||
|
||||
- ``timestampPrecision``
|
||||
- ``TimestampPrecision``
|
||||
@@ -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,246 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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.
|
||||
///
|
||||
/// Setting this property sets the provider on all underlying handlers and replaces
|
||||
/// the provider passed to ``init(_:metadataProvider:)``.
|
||||
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 {
|
||||
// Also replace this handler's own provider, otherwise the provider passed to the
|
||||
// initializer keeps overriding the new one, and setting `nil` would not remove it.
|
||||
self._metadataProvider = newValue
|
||||
self.mutatingForEachHandler { $0.metadataProvider = newValue }
|
||||
}
|
||||
}
|
||||
|
||||
/// Log a message using the log level and source that you provide.
|
||||
///
|
||||
/// Metadata from this handler's metadata provider overrides metadata from
|
||||
/// the underlying handlers and their providers. Explicit metadata in the
|
||||
/// log event takes precedence over this handler's provider.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - event: The log event containing the level, message, metadata, and source location.
|
||||
public func log(event: LogEvent) {
|
||||
var event = event
|
||||
if let provider = self._metadataProvider {
|
||||
var metadata = provider.get()
|
||||
if let explicit = event.metadata {
|
||||
metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
|
||||
}
|
||||
if !metadata.isEmpty {
|
||||
event.metadata = metadata
|
||||
}
|
||||
}
|
||||
for handler in self.handlers where handler.logLevel <= event.level {
|
||||
handler.log(event: event)
|
||||
}
|
||||
}
|
||||
|
||||
@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.
|
||||
///
|
||||
/// The getter merges the metadata of the underlying handlers in initialization order.
|
||||
/// On a key conflict, the first handler's value wins, as in ``subscript(metadataKey:)``.
|
||||
/// The dictionary does not contain values from metadata providers.
|
||||
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)
|
||||
|
||||
// Keep the existing value on a conflict, so the first handler wins.
|
||||
for handler in self.handlers {
|
||||
effective.merge(handler.metadata, uniquingKeysWith: { current, _ in current })
|
||||
}
|
||||
|
||||
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,516 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 {
|
||||
/// 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 TextOutputStream & Sendable
|
||||
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?
|
||||
|
||||
/// The precision of the timestamp written at the start of each log line.
|
||||
///
|
||||
/// Defaults to ``TimestampPrecision/seconds``, which keeps the output format
|
||||
/// that `StreamLogHandler` has always used, for example `2025-06-01T14:03:07+0000`.
|
||||
/// Some tools parse this output, so the extra precision is opt-in rather than the default.
|
||||
///
|
||||
/// Set it to ``TimestampPrecision/milliseconds`` to include milliseconds,
|
||||
/// for example `2025-06-01T14:03:07.042+0000`.
|
||||
///
|
||||
/// > Note: On WASI the wall clock is only read with second precision, so
|
||||
/// > ``TimestampPrecision/milliseconds`` always prints `.000` there.
|
||||
public var timestampPrecision: TimestampPrecision = .seconds
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
|
||||
/// Creates a ``StreamLogHandler`` that directs its output to the stream you provide,
|
||||
/// using the global metadata provider from ``LoggingSystem``.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - label: The label for this log handler.
|
||||
/// - stream: The stream to write log output to.
|
||||
public init(label: String, stream: any TextOutputStream & Sendable) {
|
||||
self.init(label: label, stream: stream, metadataProvider: LoggingSystem.metadataProvider)
|
||||
}
|
||||
|
||||
/// Creates a ``StreamLogHandler`` that directs its output to the stream you provide,
|
||||
/// using the metadata provider you provide.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - label: The label for this log handler.
|
||||
/// - stream: The stream to write log output to.
|
||||
/// - metadataProvider: The metadata provider to use, or `nil` for no provider.
|
||||
public init(label: String, stream: any TextOutputStream & Sendable, metadataProvider: Logger.MetadataProvider?) {
|
||||
self.label = label
|
||||
self.stream = stream
|
||||
self.metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
/// 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(precision: self.timestampPrecision)) \(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(precision: TimestampPrecision) -> String {
|
||||
var buffer = [Int8](repeating: 0, count: 255)
|
||||
var tzBuffer = [Int8](repeating: 0, count: 16)
|
||||
let milliseconds: Int
|
||||
#if os(Windows)
|
||||
// _ftime64_s gives wall-clock time with millisecond resolution.
|
||||
var timeBuffer = __timeb64()
|
||||
_ = _ftime64_s(&timeBuffer)
|
||||
var localTime = tm()
|
||||
_ = _localtime64_s(&localTime, &timeBuffer.time)
|
||||
_ = strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S", &localTime)
|
||||
_ = strftime(&tzBuffer, tzBuffer.count, "%z", &localTime)
|
||||
milliseconds = Int(timeBuffer.millitm)
|
||||
#elseif canImport(WASILibc)
|
||||
// CLOCK_REALTIME isn't importable on WASI (it's a pointer-to-struct macro),
|
||||
// so fall back to time(nil), which only has second resolution.
|
||||
var timestamp = time(nil)
|
||||
guard let localTime = localtime(×tamp) else {
|
||||
return "<unknown>"
|
||||
}
|
||||
strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S", localTime)
|
||||
strftime(&tzBuffer, tzBuffer.count, "%z", localTime)
|
||||
milliseconds = 0
|
||||
#else
|
||||
var timeSpec = timespec()
|
||||
clock_gettime(CLOCK_REALTIME, &timeSpec)
|
||||
guard let localTime = localtime(&timeSpec.tv_sec) else {
|
||||
return "<unknown>"
|
||||
}
|
||||
strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S", localTime)
|
||||
strftime(&tzBuffer, tzBuffer.count, "%z", localTime)
|
||||
milliseconds = Int(timeSpec.tv_nsec) / 1_000_000
|
||||
#endif
|
||||
let dateTime = buffer.withUnsafeBufferPointer {
|
||||
$0.withMemoryRebound(to: CChar.self) {
|
||||
String(cString: $0.baseAddress!)
|
||||
}
|
||||
}
|
||||
let timeZone = tzBuffer.withUnsafeBufferPointer {
|
||||
$0.withMemoryRebound(to: CChar.self) {
|
||||
String(cString: $0.baseAddress!)
|
||||
}
|
||||
}
|
||||
switch precision {
|
||||
case .seconds:
|
||||
return "\(dateTime)\(timeZone)"
|
||||
case .milliseconds:
|
||||
return "\(dateTime).\(Self.zeroPadded(milliseconds))\(timeZone)"
|
||||
}
|
||||
}
|
||||
|
||||
/// Pads a millisecond value to three digits without pulling in Foundation.
|
||||
internal static func zeroPadded(_ milliseconds: Int) -> String {
|
||||
if milliseconds < 10 {
|
||||
return "00\(milliseconds)"
|
||||
} else if milliseconds < 100 {
|
||||
return "0\(milliseconds)"
|
||||
} else {
|
||||
return "\(milliseconds)"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension StreamLogHandler {
|
||||
/// The precision of the timestamp that a ``StreamLogHandler`` writes at the start of each log line.
|
||||
@nonexhaustive
|
||||
public enum TimestampPrecision: Sendable, Hashable {
|
||||
/// Whole seconds, for example `2025-06-01T14:03:07+0000`.
|
||||
///
|
||||
/// This is the default, and matches the format `StreamLogHandler` has always produced.
|
||||
case seconds
|
||||
|
||||
/// Milliseconds, for example `2025-06-01T14:03:07.042+0000`.
|
||||
///
|
||||
/// > Note: On WASI the wall clock only has second resolution, so the
|
||||
/// > millisecond field is always `.000`.
|
||||
case milliseconds
|
||||
}
|
||||
}
|
||||
|
||||
/// 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
|
||||
#if compiler(>=6.5)
|
||||
let file = WASILibc.stderr
|
||||
#else
|
||||
let file = WASILibc.stderr!
|
||||
#endif
|
||||
return StdioOutputStream(
|
||||
file: file,
|
||||
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
|
||||
#if compiler(>=6.5)
|
||||
let file = WASILibc.stdout
|
||||
#else
|
||||
let file = WASILibc.stdout!
|
||||
#endif
|
||||
return StdioOutputStream(
|
||||
file: file,
|
||||
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 {}
|
||||
}
|
||||
}
|
||||
+11
-11
@@ -61,7 +61,7 @@ package final class Lock {
|
||||
#elseif os(FreeBSD) || os(OpenBSD)
|
||||
fileprivate let mutex: UnsafeMutablePointer<pthread_mutex_t?> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
fileprivate let mutex: UnsafeMutablePointer<pthread_mutex_t> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#endif
|
||||
@@ -70,7 +70,7 @@ package final class Lock {
|
||||
package init() {
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
var attr = pthread_mutexattr_t(bitPattern: 0)
|
||||
#else
|
||||
@@ -100,7 +100,7 @@ package final class Lock {
|
||||
deinit {
|
||||
#if os(Windows)
|
||||
mutex.deallocate()
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_mutex_destroy(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
mutex.deallocate()
|
||||
@@ -114,7 +114,7 @@ package final class Lock {
|
||||
package func lock() {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_mutex_lock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
@@ -127,7 +127,7 @@ package final class Lock {
|
||||
package func unlock() {
|
||||
#if os(Windows)
|
||||
ReleaseSRWLockExclusive(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_mutex_unlock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
@@ -196,10 +196,10 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
#endif
|
||||
|
||||
/// Create a new lock.
|
||||
public init() {
|
||||
init() {
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.rwlock)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_init(self.rwlock, nil)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -208,7 +208,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
deinit {
|
||||
#if os(Windows)
|
||||
self.rwlock.deallocate()
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_destroy(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
self.rwlock.deallocate()
|
||||
@@ -223,7 +223,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockShared(self.rwlock)
|
||||
self.shared = true
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_rdlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -237,7 +237,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.rwlock)
|
||||
self.shared = false
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_wrlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -255,7 +255,7 @@ internal final class ReadWriteLock: @unchecked Sendable {
|
||||
} else {
|
||||
ReleaseSRWLockExclusive(self.rwlock)
|
||||
}
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#elseif _runtime(_multithreaded)
|
||||
let err = pthread_rwlock_unlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
|
||||
@@ -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) {
|
||||
/// // [...]
|
||||
/// }
|
||||
///
|
||||
@@ -287,6 +280,10 @@ extension LogHandler {
|
||||
}
|
||||
|
||||
/// A default implementation for the SwiftLog 1.0 log message handler.
|
||||
///
|
||||
/// Forwards to ``log(event:)`` directly. Forwarding to the source-carrying deprecated
|
||||
/// method closed a cycle with its own default, so a handler implementing only
|
||||
/// ``log(event:)`` overflowed the stack when called through this entry point.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logging.Logger.Level,
|
||||
@@ -297,13 +294,15 @@ extension LogHandler {
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: Logger.currentModule(filePath: file),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
event: LogEvent(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: Logger.currentModule(filePath: file),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,555 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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. Setting attributes on a `.dictionary` or `.array` value is a
|
||||
/// programmer error: it triggers an assertion in debug builds and leaves the value unchanged in
|
||||
/// release builds. Set attributes on the leaf values instead.
|
||||
///
|
||||
/// Only handlers that inspect attributes pay the cost of the getter check.
|
||||
@inlinable
|
||||
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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,325 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
// MARK: - withLogger() free functions for task-local logger
|
||||
|
||||
/// Runs `operation` with `logger` bound to the task-local context.
|
||||
///
|
||||
/// Code called within `operation` can read the logger via ``Logger/current`` without an
|
||||
/// explicit parameter. Binding a different logger with this overload **replaces** the
|
||||
/// current task-local logger; any metadata accumulated by an outer
|
||||
/// ``withLogger(mergingMetadata:_:)-2c7dy`` or
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)-2pd9p``
|
||||
/// scope is not carried over. Use the modifying overloads to layer or replace aspects
|
||||
/// of the current logger instead.
|
||||
///
|
||||
/// This overload is the application-bootstrap binding mechanism: pass a `Logger`
|
||||
/// constructed via ``Logger/init(label:)`` at your application entry point. Because
|
||||
/// ``Logger/init(label:)`` consults `LoggingSystem.factory`, the constructed `Logger`
|
||||
/// only carries a useful handler once ``LoggingSystem/bootstrap(_:)`` has been called.
|
||||
/// For mid-call-tree backend swaps that should work without bootstrap (tests, scoped
|
||||
/// routing), use ``withLogger(logLevel:handler:metadata:_:)-2pd9p``
|
||||
/// instead — it modifies
|
||||
/// the current logger's handler in place without constructing a new one.
|
||||
///
|
||||
/// ```swift
|
||||
/// let logger = Logger(label: "app")
|
||||
/// await withLogger(logger) { logger in
|
||||
/// logger.info("Application started")
|
||||
/// await handleRequests() // reads Logger.current
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The closure to run with `logger` bound. Receives `logger` as a
|
||||
/// parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result {
|
||||
do {
|
||||
return try Logger.withTaskLocalLogger(logger) {
|
||||
try operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with `logger` bound to the task-local context.
|
||||
///
|
||||
/// Code called within `operation` can read the logger via ``Logger/current`` without an
|
||||
/// explicit parameter. Binding a different logger with this overload **replaces** the
|
||||
/// current task-local logger; any metadata accumulated by an outer
|
||||
/// ``withLogger(mergingMetadata:_:)-3eduo`` or
|
||||
/// ``withLogger(logLevel:handler:metadata:_:)-5nmw6``
|
||||
/// scope is not carried over. Use the modifying overloads to layer or replace aspects
|
||||
/// of the current logger instead.
|
||||
///
|
||||
/// This overload is the application-bootstrap binding mechanism: pass a `Logger`
|
||||
/// constructed via ``Logger/init(label:)`` at your application entry point. Because
|
||||
/// ``Logger/init(label:)`` consults `LoggingSystem.factory`, the constructed `Logger`
|
||||
/// only carries a useful handler once ``LoggingSystem/bootstrap(_:)`` has been called.
|
||||
/// For mid-call-tree backend swaps that should work without bootstrap (tests, scoped
|
||||
/// routing), use ``withLogger(logLevel:handler:metadata:_:)-5nmw6``
|
||||
/// instead — it modifies
|
||||
/// the current logger's handler in place without constructing a new one.
|
||||
///
|
||||
/// ```swift
|
||||
/// let logger = Logger(label: "app")
|
||||
/// await withLogger(logger) { logger in
|
||||
/// logger.info("Application started")
|
||||
/// await handleRequests() // reads Logger.current
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logger: The logger to bind for the duration of `operation`.
|
||||
/// - operation: The async closure to run with `logger` bound. Receives `logger` as a
|
||||
/// parameter so the body does not need to re-read ``Logger/current``.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
_ logger: Logger,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result {
|
||||
do {
|
||||
return try await Logger.withTaskLocalLogger(logger) {
|
||||
try await operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` **layered on
|
||||
/// top of** the inherited base metadata. Keys present in `metadata` override existing
|
||||
/// keys with the same name. Other aspects (handler, log level, base metadata not in
|
||||
/// `metadata`) are preserved.
|
||||
///
|
||||
/// Use this overload at request boundaries and any point where context should
|
||||
/// accumulate. Nested ``withLogger(mergingMetadata:_:)-2c7dy`` scopes
|
||||
/// layer on top of each
|
||||
/// other.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
/// logger.info("Handling request")
|
||||
/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in
|
||||
/// logger.info("Authenticated") // sees both request.id and user.id
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
for (key, value) in metadata() {
|
||||
logger[metadataKey: key] = value
|
||||
}
|
||||
do {
|
||||
return try Logger.withTaskLocalLogger(logger) {
|
||||
try operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` **layered on
|
||||
/// top of** the inherited base metadata. Keys present in `metadata` override existing
|
||||
/// keys with the same name. Other aspects (handler, log level, base metadata not in
|
||||
/// `metadata`) are preserved.
|
||||
///
|
||||
/// Use this overload at request boundaries and any point where context should
|
||||
/// accumulate. Nested ``withLogger(mergingMetadata:_:)-3eduo`` scopes
|
||||
/// layer on top of each
|
||||
/// other.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
|
||||
/// logger.info("Handling request")
|
||||
/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in
|
||||
/// logger.info("Authenticated") // sees both request.id and user.id
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
|
||||
/// Keys override existing values with the same name.
|
||||
/// - operation: The async closure to run with the merged logger bound. Receives the
|
||||
/// merged logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
for (key, value) in metadata() {
|
||||
logger[metadataKey: key] = value
|
||||
}
|
||||
do {
|
||||
return try await Logger.withTaskLocalLogger(logger) {
|
||||
try await operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are **replaced** by
|
||||
/// the provided arguments. `nil` parameters leave the corresponding aspect unchanged.
|
||||
///
|
||||
/// Unlike ``withLogger(mergingMetadata:_:)-2c7dy``, which layers
|
||||
/// metadata on top of the
|
||||
/// inherited base, this overload **replaces** the base metadata when `metadata` is
|
||||
/// non-nil. Pass `metadata: [:]` to wipe the inherited metadata entirely for the scope.
|
||||
///
|
||||
/// With no arguments, this overload re-binds ``Logger/current`` unchanged — a convenient
|
||||
/// way to extract it into a local variable for repeated use inside the closure.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { _ in
|
||||
/// // Start a background job with metadata unrelated to the request that scheduled it.
|
||||
/// withLogger(metadata: ["job.id": "\(job.id)"]) { logger in
|
||||
/// logger.info("running") // metadata: job.id only — request.id wiped
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// When no `withLogger` scope has been set up, ``Logger/current`` (and therefore this
|
||||
/// function) returns the process-wide unbound default — a `Logger(label: "")` cached
|
||||
/// from the first time the task-local is touched. Bootstrap before reading
|
||||
/// ``Logger/current`` for predictable backend selection.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When `nil`,
|
||||
/// the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for the
|
||||
/// scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to start
|
||||
/// a scope from a known state. When `nil`, the inherited base metadata is preserved.
|
||||
/// - operation: The closure to run with the modified logger bound. Receives the
|
||||
/// modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: (Logger) throws(Failure) -> Result
|
||||
) throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
if let handler {
|
||||
logger.handler = handler
|
||||
}
|
||||
if let logLevel {
|
||||
logger.logLevel = logLevel
|
||||
}
|
||||
if let metadata = metadata() {
|
||||
logger.handler.metadata = metadata
|
||||
}
|
||||
do {
|
||||
return try Logger.withTaskLocalLogger(logger) {
|
||||
try operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are **replaced** by
|
||||
/// the provided arguments. `nil` parameters leave the corresponding aspect unchanged.
|
||||
///
|
||||
/// Unlike ``withLogger(mergingMetadata:_:)-3eduo``, which layers
|
||||
/// metadata on top of the
|
||||
/// inherited base, this overload **replaces** the base metadata when `metadata` is
|
||||
/// non-nil. Pass `metadata: [:]` to wipe the inherited metadata entirely for the scope.
|
||||
///
|
||||
/// With no arguments, this overload re-binds ``Logger/current`` unchanged — a convenient
|
||||
/// way to extract it into a local variable for repeated use inside the closure.
|
||||
///
|
||||
/// ```swift
|
||||
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { _ in
|
||||
/// // Start a background job with metadata unrelated to the request that scheduled it.
|
||||
/// withLogger(metadata: ["job.id": "\(job.id)"]) { logger in
|
||||
/// logger.info("running") // metadata: job.id only — request.id wiped
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// When no `withLogger` scope has been set up, ``Logger/current`` (and therefore this
|
||||
/// function) returns the process-wide unbound default — a `Logger(label: "")` cached
|
||||
/// from the first time the task-local is touched. Bootstrap before reading
|
||||
/// ``Logger/current`` for predictable backend selection.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - logLevel: When non-nil, replaces the current log level for the scope. When `nil`,
|
||||
/// the inherited log level is preserved.
|
||||
/// - handler: When non-nil, replaces the current logger's handler for the scope.
|
||||
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
|
||||
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
|
||||
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for the
|
||||
/// scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to start
|
||||
/// a scope from a known state. When `nil`, the inherited base metadata is preserved.
|
||||
/// - operation: The async closure to run with the modified logger bound. Receives the
|
||||
/// modified logger as a parameter.
|
||||
/// - Returns: The value returned by `operation`.
|
||||
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
|
||||
@inlinable
|
||||
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
|
||||
logLevel: Logger.Level? = nil,
|
||||
handler: (any LogHandler)? = nil,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
|
||||
) async throws(Failure) -> Result {
|
||||
var logger = Logger.current
|
||||
if let handler {
|
||||
logger.handler = handler
|
||||
}
|
||||
if let logLevel {
|
||||
logger.logLevel = logLevel
|
||||
}
|
||||
if let metadata = metadata() {
|
||||
logger.handler.metadata = metadata
|
||||
}
|
||||
do {
|
||||
return try await Logger.withTaskLocalLogger(logger) {
|
||||
try await operation(logger)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Failure
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// The logging system is a global facility where you can configure the default logging backend implementation.
|
||||
///
|
||||
/// `LoggingSystem` is set up just once in a given program to set up the desired logging backend implementation.
|
||||
/// The default behavior, if you don't define otherwise, sets the ``LogHandler`` to use a ``StreamLogHandler`` that presents its output to `STDOUT`.
|
||||
///
|
||||
/// You can configure that handler to present the output to `STDERR` instead using the following code:
|
||||
///
|
||||
/// ```swift
|
||||
/// LoggingSystem.bootstrap(StreamLogHandler.standardError)
|
||||
/// ```
|
||||
///
|
||||
/// The default (``StreamLogHandler``) is intended to be a convenience.
|
||||
/// For production applications, implement the ``LogHandler`` protocol directly, or use a community-maintained backend.
|
||||
public enum LoggingSystem: Sendable {
|
||||
private static let _factory = FactoryBox(
|
||||
{ label, _ in StreamLogHandler.standardError(label: label) },
|
||||
violationErrorMesage: "logging system can only be initialized once per process."
|
||||
)
|
||||
private static let _metadataProviderFactory = MetadataProviderBox(
|
||||
nil,
|
||||
violationErrorMesage: "logging system can only be initialized once per process."
|
||||
)
|
||||
|
||||
#if DEBUG
|
||||
private static let _warnOnceBox: WarnOnceBox = WarnOnceBox()
|
||||
#endif
|
||||
|
||||
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
|
||||
///
|
||||
/// > Warning:
|
||||
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
|
||||
/// > lead to undefined behavior, most likely a crash.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
|
||||
@preconcurrency
|
||||
public static func bootstrap(_ factory: @escaping @Sendable (String) -> any LogHandler) {
|
||||
self._factory.replace(
|
||||
{ label, _ in
|
||||
factory(label)
|
||||
},
|
||||
validate: true
|
||||
)
|
||||
}
|
||||
|
||||
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
|
||||
///
|
||||
/// > Warning:
|
||||
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
|
||||
/// > lead to undefined behavior, most likely a crash.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - metadataProvider: The `MetadataProvider` used to inject runtime-generated metadata from the execution context.
|
||||
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
|
||||
@preconcurrency
|
||||
public static func bootstrap(
|
||||
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
|
||||
metadataProvider: Logger.MetadataProvider?
|
||||
) {
|
||||
self._metadataProviderFactory.replace(metadataProvider, validate: true)
|
||||
self._factory.replace(factory, validate: true)
|
||||
}
|
||||
|
||||
// for our testing we want to allow multiple bootstrapping
|
||||
internal static func bootstrapInternal(_ factory: @escaping @Sendable (String) -> any LogHandler) {
|
||||
self._metadataProviderFactory.replace(nil, validate: false)
|
||||
self._factory.replace(
|
||||
{ label, _ in
|
||||
factory(label)
|
||||
},
|
||||
validate: false
|
||||
)
|
||||
}
|
||||
|
||||
// for our testing we want to allow multiple bootstrapping
|
||||
internal static func bootstrapInternal(
|
||||
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
|
||||
metadataProvider: Logger.MetadataProvider?
|
||||
) {
|
||||
self._metadataProviderFactory.replace(metadataProvider, validate: false)
|
||||
self._factory.replace(factory, validate: false)
|
||||
}
|
||||
|
||||
internal static var factory: (String, Logger.MetadataProvider?) -> any LogHandler {
|
||||
{ label, metadataProvider in
|
||||
self._factory.underlying(label, metadataProvider)
|
||||
}
|
||||
}
|
||||
|
||||
/// `true` once a user has explicitly called ``bootstrap(_:)`` or the metadata-provider
|
||||
/// overload; `false` while the system is still using the default `StreamLogHandler`.
|
||||
internal static var isBootstrapped: Bool {
|
||||
self._factory.isInitialized
|
||||
}
|
||||
|
||||
/// System wide ``Logger/MetadataProvider`` that was configured during the logging system's `bootstrap`.
|
||||
///
|
||||
/// When creating a ``Logger`` using the plain ``Logger/init(label:)`` initializer, this metadata provider
|
||||
/// will be provided to it.
|
||||
///
|
||||
/// When using custom log handler factories, make sure to provide the bootstrapped metadata provider to them,
|
||||
/// or the metadata will not be filled in automatically using the provider on log-sites. While using a custom
|
||||
/// factory to avoid using the bootstrapped metadata provider may sometimes be useful, usually it will lead to
|
||||
/// un-expected behavior, so make sure to always propagate it to your handlers.
|
||||
public static var metadataProvider: Logger.MetadataProvider? {
|
||||
self._metadataProviderFactory.underlying
|
||||
}
|
||||
|
||||
#if DEBUG
|
||||
/// Used to warn only once about a specific ``LogHandler`` type when it does not support ``Logger/MetadataProvider``,
|
||||
/// but an attempt was made to set a metadata provider on such handler. In order to avoid flooding the system with
|
||||
/// warnings such warning is only emitted in debug mode, and even then at-most once for a handler type.
|
||||
internal static func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(
|
||||
_ type: Handler.Type
|
||||
) -> Bool {
|
||||
self._warnOnceBox.warnOnceLogHandlerNotSupportedMetadataProvider(type: type)
|
||||
}
|
||||
#endif
|
||||
|
||||
/// Protects an object such that it can only be accessed through a Reader-Writer lock.
|
||||
final class RWLockedValueBox<Value: Sendable>: @unchecked Sendable {
|
||||
private let lock = ReadWriteLock()
|
||||
private var storage: Value
|
||||
|
||||
init(initialValue: Value) {
|
||||
self.storage = initialValue
|
||||
}
|
||||
|
||||
func withReadLock<Result>(_ operation: (Value) -> Result) -> Result {
|
||||
self.lock.withReaderLock {
|
||||
operation(self.storage)
|
||||
}
|
||||
}
|
||||
|
||||
func withWriteLock<Result>(_ operation: (inout Value) -> Result) -> Result {
|
||||
self.lock.withWriterLock {
|
||||
operation(&self.storage)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Protects an object by applying the constraints that it can only be accessed through a Reader-Writer lock
|
||||
/// and can only be updated once from the initial value given.
|
||||
private struct ReplaceOnceBox<BoxedType: Sendable> {
|
||||
private struct ReplaceOnce: Sendable {
|
||||
private(set) var initialized = false
|
||||
private var _underlying: BoxedType
|
||||
private let violationErrorMessage: String
|
||||
|
||||
mutating func replaceUnderlying(_ underlying: BoxedType, validate: Bool) {
|
||||
precondition(!validate || !self.initialized, self.violationErrorMessage)
|
||||
self._underlying = underlying
|
||||
self.initialized = true
|
||||
}
|
||||
|
||||
var underlying: BoxedType {
|
||||
self._underlying
|
||||
}
|
||||
|
||||
init(underlying: BoxedType, violationErrorMessage: String) {
|
||||
self._underlying = underlying
|
||||
self.violationErrorMessage = violationErrorMessage
|
||||
}
|
||||
}
|
||||
|
||||
private let storage: RWLockedValueBox<ReplaceOnce>
|
||||
|
||||
init(_ underlying: BoxedType, violationErrorMesage: String) {
|
||||
self.storage = .init(
|
||||
initialValue: ReplaceOnce(
|
||||
underlying: underlying,
|
||||
violationErrorMessage: violationErrorMesage
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
func replace(_ newUnderlying: BoxedType, validate: Bool) {
|
||||
self.storage.withWriteLock { $0.replaceUnderlying(newUnderlying, validate: validate) }
|
||||
}
|
||||
|
||||
var underlying: BoxedType {
|
||||
self.storage.withReadLock { $0.underlying }
|
||||
}
|
||||
|
||||
var isInitialized: Bool {
|
||||
self.storage.withReadLock { $0.initialized }
|
||||
}
|
||||
}
|
||||
|
||||
private typealias FactoryBox = ReplaceOnceBox<
|
||||
@Sendable (_ label: String, _ provider: Logger.MetadataProvider?) -> any LogHandler
|
||||
>
|
||||
|
||||
private typealias MetadataProviderBox = ReplaceOnceBox<Logger.MetadataProvider?>
|
||||
}
|
||||
|
||||
// MARK: - Debug only warnings
|
||||
|
||||
#if DEBUG
|
||||
/// Contains state to manage all kinds of "warn only once" warnings which the logging system may want to issue.
|
||||
private final class WarnOnceBox: @unchecked Sendable {
|
||||
private let lock: Lock = Lock()
|
||||
private var warnOnceLogHandlerNotSupportedMetadataProviderPerType = Set<ObjectIdentifier>()
|
||||
|
||||
func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(type: Handler.Type) -> Bool {
|
||||
self.lock.withLock {
|
||||
let id = ObjectIdentifier(type)
|
||||
let (inserted, _) = warnOnceLogHandlerNotSupportedMetadataProviderPerType.insert(id)
|
||||
return inserted // warn about this handler type, it is the first time we encountered it
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
Loaded 100 of 117 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user