Compare commits

...
16 Commits
Author SHA1 Message Date
Vladimir Kukushkin 92448c359f Add (default:) string interpolation overloads (#471)
Add [Default String
Interpolation](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0477-default-interpolation-values.md)
overloads for `MetadataValue` to restore compatibility with
`\(default:)` interpolation.

### Motivation:

1.13.0 introduced a breaking change to the default string interpolation
compatibility. We do not want to revert the custom string interpolation,
but can fix compatibility with the default string interpolation as much
as possible.

### Modifications:

Add `\(default:)` overloads to `MetadataValue.StringInterpolation`,
similar to the once in `DefaultStringInterpolation`.

### Result:

Compatibility with `logger.info("Log message", metadata: ["value":
"\(value, default: "none")"])` is restored.
2026-06-09 17:01:25 +02:00
Vladimir Kukushkin 2aed77ae5e Match DefaultStringInterpolation appendInterpolation overloads (#469)
Custom `MetadataValue.StringInterpolation` broke compatibility with
`DefaultStringInterpolation`. Rearrange `appendInterpolation` overloads
to match `DefaultStringInterpolation` to maintain backward
compatibility.

### Motivation:

Custom `MetadataValue.StringInterpolation` broke compatibility with
`DefaultStringInterpolation`. Rearrange `appendInterpolation` overloads
to match `DefaultStringInterpolation` to maintain backward
compatibility.

### Modifications:

`MetadataValue.StringInterpolation` `appendInterpolation` overloads
changed.

### Result:

Code relying on matching correct `DefaultStringInterpolation`
`appendInterpolation` overload compiles.
2026-05-28 13:35:14 +01:00
Vladimir KukushkinandFranz Busch 7dc6101ae4 [SLG-0004]: metadata value attributes implementation (#453)
Proposal discussion thread:
https://forums.swift.org/t/proposal-slg-0004-metadata-value-attributes-revision-2/86488

Add an extensible per-value attribute mechanism for metadata.

### 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.

### Modifications:

- SLG-0004 proposal is updated based on the feedback. 
- Added `AttributedStringCarrier: CustomStringConvertible`-based
mechanism to `Logging`.
- Added benchmarks and benchmark thresholds for the new attributed
metadata.

### Result:

`swift-log` provides an optional extensible mechanism for attaching
attributes to metadata values.

---------

Co-authored-by: Franz Busch <privat@franz-busch.de>
2026-05-22 16:06:57 +01:00
Rick Newton-Rogers a012e0ad8a Adopt multi-package macOS benchmarks workflow (#466)
### Motivation

* The two-invocation pattern for `macos-benchmarks` and
`macos-benchmarks-MaxLogLevelWarningBenchmarks-trait` allocates one
self-hosted macOS runner per (Swift version x package), incurring
duplicate runner-recycling cost.
* The recent change on main adds a `benchmark_package_paths` input
letting a single invocation run all packages serially on each runner.

### Modifications

* Replace the two macOS benchmark jobs in `main.yml` and
`pull_request.yml` with a single consolidated job that passes both
packages via `benchmark_package_paths: '["Benchmarks/NoTraits",
"Benchmarks/MaxLogLevelWarning"]'`.
* Drop Swift 6.2 from the matrix; only Swift 6.3 is shared between the
two packages (`MaxLogLevelWarning` has no `Thresholds/Xcode swift
6.2/`).

### Result

* One macOS runner allocation per Swift version instead of one per
(version x package).
* `NoTraits` loses Swift 6.2 coverage
2026-05-21 14:21:31 +00:00
Rick Newton-Rogers 1069d31898 Skip handler dispatch for setters under MaxLogLevelNone (#465)
Skip handler dispatch for setters under `MaxLogLevelNone`

 ### Motivation

* When `MaxLogLevelNone` is enabled every
`Logger.trace`/`debug`/.../`critical` method and `Logger.log(level:)`
compiles down to an empty body, so no log statement can ever observe
what the underlying `LogHandler` sees.
* Despite this, the `subscript(metadataKey:)` and `logLevel` setters
still went through the handler. Code like `logger[metadataKey:
"user-id"] = "\(id)"` would CoW the logger storage and call into the
handler even though nothing could read the metadata back out via a log
statement.

### Modifications

* Wrap the bodies of `Logger.subscript(metadataKey:) { set }` and
`Logger.logLevel { set }` in `#if !MaxLogLevelNone`, mirroring the
existing guards on the level-specific log methods.
* Note this behaviour in `DisableLogLevelsDuringCompilation.md` so
callers know reads still go through the handler but writes do not.
* Add a new benchmark which ensures that the operations don't allocate.
* Update some missed swift-tools-version bumps.
* Loosen p90 instruction threshold to 10%. The same source produces
results that swing by up to ~8% between back-to-back runs.
### Result

* `logger[metadataKey:] = ...` and `logger.logLevel = ...` compile to
empty bodies when `MaxLogLevelNone` is set, matching the
zero-runtime-overhead guarantee the trait already provides for log
emission.
* Resolves https://github.com/apple/swift-log/issues/462
2026-05-21 13:55:40 +01:00
Vladimir Kukushkin 3061a62b6d Shared workflows changed from Xcode XX.X to Xcode swift X.X (#461)
Benchmark thresholds should now be at a different path after switching
to `MACOS_SWIFT_6_1_ENABLED` and `MACOS_SWIFT_6_2_ENABLED`.
2026-05-19 13:40:04 +02:00
Rick Newton-Rogers 184c73762f Migrate macOS CI to Swift version inputs (#457)
### Motivation

* The shared `macos_tests.yml` and `macos_benchmarks.yml` workflows
support requesting Xcodes by Swift version with symlinks on the runners
owning the mapping. This more directly expresses the library support
window.
* Older Xcodes (26.1 and below) are being removed from the runners.

### Modifications

* Replace `macos_xcode_16_4_enabled` and `macos_xcode_26_1_enabled` with
`macos_swift_6_1_enabled` and `macos_swift_6_2_enabled` in benchmark
jobs.
* Remove now-redundant explicit `xcode_*_enabled: false` and
`swift_*_enabled: true` overrides from the `macos-tests` job in
`main.yml` (these now match the workflow defaults).

### Result

* macOS CI requests toolchains by Swift version, decoupling the
workflows from specific Xcode release names.
2026-05-15 10:42:48 +01:00
Vladimir Kukushkin eca81998f5 [SLG-0004]: metadata value attributes proposal (revision 2) (#440)
> [!IMPORTANT]
> This is a revision of SLG-0004 previously discussed
[here](https://forums.swift.org/t/proposal-slg-0004-metadata-values-privacy-attribute/85249/15).

Add an extensible per-value attribute mechanism for metadata.

### 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, or additional value type information.

### Modifications:

- SLG-0004 proposal is updated based on the feedback in the first round
of discussion.

### Result:

Revised SLG-0004 proposal is ready for review.
2026-05-13 15:38:57 +02:00
Vladimir Kukushkin ac3646e5e0 Disable nightly 6.3 WASM builds (#454)
Disable nightly WASM builds because 6.3 images are no longer available.
Enable back when 6.4 builds are available.
2026-05-01 14:04:06 +01:00
Vladimir Kukushkin 5c348a629c Cleanup repository structure (#451)
Unify repos layout across the ecosystem:

1. Remove `CONTRIBUTORS.md` and mentions of it.
2. Remove `CODE_OF_CONDUCT.md` and mentions of it.
3. From `CONTRIBUTING.md` remove "Writing a Patch" and "Commit Message
Template" sections.
4. Remove `.mailmap` and mentions of it.
5. Remove `dev/git.commit.template` and mentions of it.
6. Remove `SECURITY.md`, if it is referenced somewhere, change it to
reference to the org security file
"https://github.com/apple/swift-log?tab=security-ov-file".
7. Remove copyright header from `Package.swift` and version-specific
package manifests.
8. Add SPI shields to the `README.md`.
9. Add "How to contribute your work" section in `CONTRIBUTING.md`.
10. Add "Add Automated release process" section in `CONTRIBUTING.md`.
2026-04-28 15:51:19 +00:00
Chris Leonard deae26e91a Add tests for SwiftLogNoOpLogHandler (#449)
Add tests for SwiftLogNoOpLogHandler

### Motivation:

`SwiftLogNoOpLogHandler` is a public type with no dedicated test
coverage.

### Modifications:

* Add tests for both initialisers, `logLevel`, `metadata`, the metadata
subscript, `log(event:)`, and end-to-end usage via `Logger`.

### Result:

`SwiftLogNoOpLogHandler` has test coverage on par with other handlers.
Coverage from 89% over all tests, to 90%.
2026-04-27 11:42:57 +01:00
Vladimir Kukushkin 1fe83fbfe9 Make dependabot set label (#448)
Prompt: Make dependabot set  label

Claude output:
Both changes are already in place:

1. The `labels: ["semver/none"]` is already configured (lines 7-8).
2. The schedule interval is already set to `"daily"` (line 6).

The file already has the desired configuration. The git status shows
this file as modified, meaning these changes were already made in the
current branch but haven't been committed yet.
2026-04-17 16:00:19 +01:00
dependabot[bot] 41592e45e1 Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.9 to 0.0.11 (#447)
Bumps
[swiftlang/github-workflows/.github/workflows/soundness.yml](https://github.com/swiftlang/github-workflows)
from 0.0.9 to 0.0.11.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/swiftlang/github-workflows/releases">swiftlang/github-workflows/.github/workflows/soundness.yml's
releases</a>.</em></p>
<blockquote>
<h2>0.0.11</h2>
<h2>What's Changed</h2>
<ul>
<li>Update all Swift package test defaults to 6.3 by <a
href="https://github.com/finagolfin"><code>@​finagolfin</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/253">swiftlang/github-workflows#253</a></li>
<li>Android 6.3 support by <a
href="https://github.com/marcprux"><code>@​marcprux</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/251">swiftlang/github-workflows#251</a></li>
<li>Add PR Dependency check workflow by <a
href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/233">swiftlang/github-workflows#233</a></li>
<li>update NDK version by <a
href="https://github.com/justice-adams-apple"><code>@​justice-adams-apple</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/262">swiftlang/github-workflows#262</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.10...0.0.11">https://github.com/swiftlang/github-workflows/compare/0.0.10...0.0.11</a></p>
<h2>0.0.10</h2>
<h2>What's Changed</h2>
<ul>
<li>Windows: Ensure Docker engine is running by <a
href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/259">swiftlang/github-workflows#259</a></li>
<li>Add FreeBSD build job to swift_package_test workflow by <a
href="https://github.com/jakepetroules"><code>@​jakepetroules</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/257">swiftlang/github-workflows#257</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.9...0.0.10">https://github.com/swiftlang/github-workflows/compare/0.0.9...0.0.10</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/a487d5014a30e7e0a75f39a4d65dc7655a1855ad"><code>a487d50</code></a>
update NDK version (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/262">#262</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/f45407ca96925df11076921c153f0e59d7d30e7f"><code>f45407c</code></a>
Add PR Dependency check workflow (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/233">#233</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/42768536f44a0fd3ca41624752698844cd8493c2"><code>4276853</code></a>
Android 6.3 support (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/251">#251</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/531b7917e71e8c3b405045a13bf1dd3556b0a451"><code>531b791</code></a>
Update all Swift package test defaults to 6.3 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/253">#253</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/3b5576d74703a6e4e30b49e2d2311313638c82e4"><code>3b5576d</code></a>
Add FreeBSD build job to swift_package_test workflow (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/257">#257</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/b337c7f02f4b38cbc2ce4de399ae417050ccd3e9"><code>b337c7f</code></a>
Windows: Ensure Docker engine is running (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/259">#259</a>)</li>
<li>See full diff in <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.9...0.0.11">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=swiftlang/github-workflows/.github/workflows/soundness.yml&package-manager=github_actions&previous-version=0.0.9&new-version=0.0.11)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-04-17 10:36:35 +00:00
Vladimir Kukushkin 83b6d96b19 Update dependabot to daily schedule (#446)
Switching dependabot from weekly to daily.
2026-04-17 10:01:47 +00:00
Samuel MurrayandVladimir Kukushkin 25598b609a Improve readability by extracting separate types to their own files (#444)
Improve readability by extracting separate types to their own files

### Motivation:

`Logger.swift` is >2000 LoC, which makes it hard to navigate both for
contributors and users of `swift-log`. Widely different concepts, such
as concrete `LogHandler` implementations, are mixed with core types such
as `Logger.Level`. Extracting separate types should make it easier to
find what you are looking for.
Closes #441

### Modifications:

* Extract all (not `Logger`-namespaced) types from `Logging.swift` to
separate files.
* Rename `Logging.swift` to `Logger.swift`, as this is the only
remaining top-level type.
* Change `LoggingSystem.factory` from `fileprivate` to `internal` to be
accessible from `Logger.swift`.

### Result:

Each (non-private) top-level type lives in a separate file, named after
the type.

---------

Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-04-17 10:49:49 +01:00
8ba97a9cf5 Update documentation to reflect recent changes (#445)
Update documentation to reflect recent changes

### Motivation:

The documentation was not updated in SLG-0003 or SLG-0005. Concretely,
the examples given in the documentation used the now deprecated
multiparameter methods in `LogHandler`, and the new `LogEvent`-based
method were not listed among the others. Likewise, the new logging
methods (`Logger.trace` etc.) that take an `Error` as a parameter were
not added. Lastly, `LogEvent` had no separate entry.
While the default rendered docs for these were acceptable, it decreased
the discoverability of the new methods, and the examples using
deprecated methods were misleading.

### Modifications:

* Update all code examples to use non-deprecated methods.
* List all new methods on `Logger` and `LogHandler` along the existing
ones.
* Add a minimal file for `LogEvent` to give it the same look as all
other types.
* Update code examples in `.md` files to follow swift format.

### Result:

Documentation reflects the current state and best practices of
`swift-log`.

---------

Co-authored-by: Joseph Heck <j_heck@apple.com>
Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-04-17 09:12:32 +01:00
72 changed files with 3895 additions and 1988 deletions

No files matched your search

+3 -1
View File
@@ -3,4 +3,6 @@ updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
interval: "daily"
labels:
- "semver/none"
+5 -20
View File
@@ -31,20 +31,11 @@ jobs:
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
macos-benchmarks:
name: macOS benchmarks (NoTraits)
name: macOS benchmarks
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
with:
benchmark_package_path: "Benchmarks/NoTraits"
macos_xcode_16_4_enabled: true
macos_xcode_26_1_enabled: true
macos-benchmarks-MaxLogLevelWarningBenchmarks-trait:
name: macOS benchmarks (MaxLogLevelWarning)
needs: macos-benchmarks
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
with:
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
macos_xcode_26_1_enabled: true
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
macos_swift_6_3_enabled: true
cxx-interop:
name: Cxx interop
@@ -62,14 +53,6 @@ jobs:
runner_pool: nightly
build_scheme: swift-log-Package
debug_output_enabled: true
xcode_16_3_enabled: false
xcode_16_4_enabled: false
xcode_26_0_enabled: false
xcode_26_1_enabled: false
xcode_26_2_enabled: false
swift_6_1_enabled: true
swift_6_2_enabled: true
swift_6_3_enabled: true
macos_xcode_test_enabled: false
ios_xcode_test_enabled: false
watchos_xcode_test_enabled: false
@@ -79,6 +62,8 @@ jobs:
wasm:
name: Wasm Swift SDK
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
with:
nightly_next_enabled: false
android:
name: Android Swift SDK
+6 -15
View File
@@ -10,7 +10,7 @@ on:
jobs:
soundness:
name: Soundness
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.9
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.11
with:
license_header_check_project_name: "Swift Logging API"
@@ -35,23 +35,12 @@ jobs:
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
macos-benchmarks:
name: macOS benchmarks (NoTraits)
name: macOS benchmarks
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
with:
benchmark_package_path: "Benchmarks/NoTraits"
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
macos_runner_pool: general
macos_xcode_16_4_enabled: true
macos_xcode_26_1_enabled: true
macos-benchmarks-MaxLogLevelWarningBenchmarks-trait:
name: macOS benchmarks (MaxLogLevelWarning)
# Workaround for reusing the same benchmarks.yml workflow
needs: macos-benchmarks
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
with:
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
macos_runner_pool: general
macos_xcode_26_1_enabled: true
macos_swift_6_3_enabled: true
cxx-interop:
name: Cxx interop
@@ -88,3 +77,5 @@ jobs:
wasm:
name: Wasm Swift SDK
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
with:
nightly_next_enabled: false
-2
View File
@@ -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
-6
View File
@@ -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>
+8
View File
@@ -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
}
}
+38
View File
@@ -0,0 +1,38 @@
// swift-tools-version: 6.2
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "MaxLogLevelNone",
platforms: [
.macOS(.v13)
],
products: [
.executable(name: "MaxLogLevelNone", targets: ["MaxLogLevelNone"])
],
dependencies: [
// swift-log
.package(
path: "../../",
traits: ["MaxLogLevelNone"]
),
// Parent Benchmarks
.package(name: "Benchmarks", path: "../"),
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
],
targets: [
.executableTarget(
name: "MaxLogLevelNone",
dependencies: [
.product(name: "BenchmarksFactory", package: "Benchmarks"),
.product(name: "Benchmark", package: "package-benchmark"),
.product(name: "Logging", package: "swift-log"),
],
path: "Benchmarks/MaxLogLevelNoneBenchmarks",
plugins: [
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
]
)
]
)
@@ -0,0 +1,4 @@
{
"instructions" : 658,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 658,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 658,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 970,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 970,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 5851,
"objectAllocCount" : 2
}
@@ -0,0 +1,4 @@
{
"instructions" : 7055,
"objectAllocCount" : 3
}
@@ -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 -1
View File
@@ -1,4 +1,4 @@
// swift-tools-version: 6.1
// swift-tools-version: 6.2
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
@@ -0,0 +1,4 @@
{
"instructions" : 662,
"objectAllocCount" : 0
}
@@ -24,4 +24,40 @@ public let benchmarks: @Sendable () -> Void = {
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_generic") { logger in
logger.log(level: .debug, "hello, benchmarking world")
}
makeBenchmark(loggerLevel: .error, logLevel: .error, "_1_attribute") { logger in
logger.log(
level: .error,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", sensitivity: .public)"
]
)
}
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_1_attribute") { logger in
logger.log(
level: .debug,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", sensitivity: .public)"
]
)
}
makeBenchmark(loggerLevel: .error, logLevel: .error, "_2_attributes") { logger in
logger.log(
level: .error,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", attributes: [BenchmarkSensitivity.public, BenchmarkColor.red])"
]
)
}
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_2_attributes") { logger in
logger.log(
level: .debug,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", attributes: [BenchmarkSensitivity.public, BenchmarkColor.red])"
]
)
}
}
+1 -1
View File
@@ -1,4 +1,4 @@
// swift-tools-version:6.1
// swift-tools-version:6.2
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
@@ -1,4 +0,0 @@
{
"instructions" : 1649,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 985,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 985,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 5855,
"objectAllocCount" : 2
}
@@ -0,0 +1,4 @@
{
"instructions" : 7075,
"objectAllocCount" : 3
}
+1 -1
View File
@@ -1,4 +1,4 @@
// swift-tools-version:6.1
// swift-tools-version:6.2
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
@@ -39,7 +39,7 @@ public func makeBenchmark(
thresholds: [
.instructions: BenchmarkThresholds(
relative: [
.p90: 1.0 // we only record p90
.p90: 10.0 // we only record p90
]
),
.objectAllocCount: BenchmarkThresholds(
@@ -14,6 +14,40 @@
import Logging
// MARK: - Benchmark attributes
public enum BenchmarkSensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case sensitive = 1
case `public` = 2
}
extension Logger.MetadataValue.StringInterpolation {
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T,
sensitivity: BenchmarkSensitivity
) {
self.appendInterpolation(value, attributes: { $0[BenchmarkSensitivity.self] = sensitivity })
}
}
public enum BenchmarkColor: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case red = 1
case blue = 2
}
extension Logger.MetadataValue.StringInterpolation {
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T,
color: BenchmarkColor
) {
self.appendInterpolation(value, attributes: { $0[BenchmarkColor.self] = color })
}
}
// MARK: - NoOpLogHandler
struct NoOpLogHandler: LogHandler {
let label: String
public var metadataProvider: Logger.MetadataProvider?
@@ -31,6 +65,13 @@ struct NoOpLogHandler: LogHandler {
func log(
event: LogEvent
) {
// Access metadata attributes
if let metadata = event.metadata {
for (_, value) in metadata {
let _ = value.attributes
}
}
// Do nothing
}
@@ -43,6 +84,13 @@ struct NoOpLogHandler: LogHandler {
function: String,
line: UInt
) {
// Access metadata attributes
if let metadata = explicitMetadata {
for (_, value) in metadata {
let _ = value.attributes
}
}
// Do nothing
}
-3
View File
@@ -1,3 +0,0 @@
# Code of Conduct
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
+10 -20
View File
@@ -45,28 +45,11 @@ Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 20
My system has IPv6 disabled.
```
## Writing a Patch
For non-trivial changes that affect the public API, it is good practice to have a discussion phase before writing code. Please follow the [proposal process](Sources/Logging/Docs.docc/Proposals/Proposals.md) to gather feedback and align on the approach with other contributors.
A good SwiftLog patch is:
1. Concise, and contains as few changes as needed to achieve the end result.
2. Tested, ensuring that any tests provided failed before the patch and pass after it.
3. Documented, adding API documentation as needed to cover new functions and properties.
4. Accompanied by a great commit message, using our commit message template.
### Commit Message Template
We require that your commit messages match our template. The easiest way to do that is to get git to help you by explicitly using the template. To do that, `cd` to the root of our repository and run:
git config commit.template dev/git.commit.template
### Make sure Tests work on Linux
## Make sure Tests work on Linux
SwiftLog uses Swift Testing to run tests on all supported platforms.
### Run CI checks locally
## Run CI checks locally
You can run the Github Actions workflows locally using
[act](https://github.com/nektos/act). To run all the jobs that run on a pull
@@ -117,7 +100,14 @@ For more information please refer to `swift package benchmark --help` or the [do
## How to contribute your work
Please open a pull request at https://github.com/apple/swift-log. Make sure the CI passes, and then wait for code review.
For non-trivial changes that affect the public API, it is good practice to have a discussion phase before writing code. Please follow the [proposal process](Sources/Logging/Docs.docc/Proposals/Proposals.md) to gather feedback and align on the approach with other contributors.
1. Prepare your change, keeping in mind that a good patch is:
- Concise, and contains as few changes as needed to achieve the end result.
- Tested, ensuring that any tests provided failed before the patch and pass after it.
- Documented, adding API documentation as needed to cover new functions and properties.
- Accompanied by a great commit message.
2. Open a pull request at https://github.com/apple/swift-log and wait for code review by the maintainers.
## Automated release process
-27
View File
@@ -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`
-13
View File
@@ -1,17 +1,4 @@
// swift-tools-version:6.2
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
-13
View File
@@ -1,17 +1,4 @@
// swift-tools-version:6.1
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
+6 -1
View File
@@ -1,5 +1,10 @@
# SwiftLog
[![](https://img.shields.io/badge/docc-read_documentation-blue)](https://swiftpackageindex.com/apple/swift-log/documentation)
[![](https://img.shields.io/github/v/release/apple/swift-log)](https://github.com/apple/swift-log/releases)
[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fapple%2Fswift-log%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/apple/swift-log)
[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fapple%2Fswift-log%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/apple/swift-log)
This repository contains a logging API implementation for Swift.
SwiftLog provides a unified, performant, and ergonomic logging API that can be
adopted by libraries and applications across the Swift ecosystem.
@@ -7,7 +12,7 @@ adopted by libraries and applications across the Swift ecosystem.
- 📚 **Documentation** and **tutorials** are available on the [Swift Package Index](https://swiftpackageindex.com/apple/swift-log)
- 🚀 **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md)
- 🪪 **License** is Apache 2.0, repeated in [LICENSE.txt](LICENSE.txt)
- 🔒 **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md)
- 🔒 **Security** issues should be reported via the process in [Security](https://github.com/apple/swift-log?tab=security-ov-file)
- 🔀 **Available Logging Backends**: SwiftLog is an API package - you'll want to
choose from the many
[community-maintained logging backends](#available-log-handler-backends) for production use
@@ -57,18 +57,23 @@ public struct InMemoryLogHandler: LogHandler {
self.metadata = metadata
}
public init(level: Logger.Level, message: Logger.Message, error: (any Error)?, metadata: Logger.Metadata) {
public init(
level: Logger.Level,
message: Logger.Message,
error: (any Error)?,
metadata: Logger.Metadata
) {
self.level = level
self.message = message
self.error = error
self.metadata = metadata
}
public static func == (lhs: InMemoryLogHandler.Entry, rhs: InMemoryLogHandler.Entry) -> Bool {
public static func == (lhs: Entry, rhs: Entry) -> Bool {
lhs.level == rhs.level
&& lhs.message == rhs.message
&& errorsEqual(lhs.error, rhs.error)
&& lhs.metadata == rhs.metadata
&& errorsEqual(lhs.error, rhs.error)
}
private static func errorsEqual(_ lhs: (any Error)?, _ rhs: (any Error)?) -> Bool {
@@ -126,14 +131,23 @@ public struct InMemoryLogHandler: LogHandler {
}
public func log(event: LogEvent) {
// Start with the metadata provider..
var mergedMetadata: Logger.Metadata = self.metadataProvider?.get() ?? [:]
// ..merge in self.metadata, overwriting existing keys
mergedMetadata = mergedMetadata.merging(self.metadata) { $1 }
// ..merge in metadata from this log call, overwriting existing keys
mergedMetadata = mergedMetadata.merging(event.metadata ?? [:]) { $1 }
var merged = self.metadata
self.logStore.append(level: event.level, message: event.message, error: event.error, metadata: mergedMetadata)
if let provider = self.metadataProvider {
let provided = provider.get()
merged.merge(provided, uniquingKeysWith: { _, rhs in rhs })
}
if let eventMetadata = event.metadata {
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
}
self.logStore.append(
level: event.level,
message: event.message,
error: event.error,
metadata: merged
)
}
@available(*, deprecated, renamed: "log(event:)")
@@ -3,7 +3,9 @@
SwiftLog provides compile-time traits to eliminate less severe log levels from
your binary reducing the runtime overhead.
## Motivation
## Overview
### Motivation
When deploying applications to production, you often know in advance which log
levels will never be needed. For example, a production service might only need
@@ -11,7 +13,7 @@ warning and above, while trace and debug levels are only useful during
development. By using traits, you can completely remove these unnecessary log
levels at compile time, achieving zero runtime overhead.
## Available traits
### Available traits
SwiftLog defines seven maximum log level traits, ordered from most permissive
to most restrictive:
@@ -39,7 +41,7 @@ are specified, the most restrictive one takes effect.
> Note: Traits should only be set by the applications and not libraries as
> any traits defined in a transitive dependency will affect the whole resolution tree.
## Example
### Example
To enable a trait, specify it when declaring your package dependency:
@@ -71,3 +73,12 @@ logger.error("This still works")
logger.critical("This still works")
logger.log(level: .error, "This still works")
```
When `MaxLogLevelNone` is enabled no log statement can ever fire, so
mutations that only configure the underlying ``LogHandler`` for future log
statements are also compiled out. Specifically, the body of the
``Logger/subscript(metadataKey:)`` setter and the body of the
``Logger/logLevel`` setter become empty, so calls like
`logger[metadataKey: "user-id"] = "\(id)"` and `logger.logLevel = .info`
do not reach the handler. Reads continue to work and return whatever the
handler reports.
@@ -23,11 +23,11 @@ func logHandlerValueSemantics() {
var logger1 = Logger(label: "first logger")
logger1.logLevel = .debug
logger1[metadataKey: "only-on"] = "first"
var logger2 = logger1
logger2.logLevel = .error // Must not affect logger1
logger2[metadataKey: "only-on"] = "second" // Must not affect logger1
// These expectations must pass
#expect(logger1.logLevel == .debug)
#expect(logger2.logLevel == .error)
@@ -51,37 +51,29 @@ public struct PrintLogHandler: LogHandler {
private let label: String
public var logLevel: Logger.Level = .info
public var metadata: Logger.Metadata = [:]
public init(label: String) {
self.label = label
}
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
public func log(event: LogEvent) {
let timestamp = ISO8601DateFormatter().string(from: Date())
let levelString = level.rawValue.uppercased()
let levelString = event.level.rawValue.uppercased()
// Merge handler metadata with message metadata
let combinedMetadata = Self.prepareMetadata(
base: self.metadata
explicit: metadata
base: self.metadata,
explicit: event.metadata
)
// Format metadata
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
// Create log line and print to console
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(event.message)"
print(logLine)
}
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get {
return self.metadata[key]
@@ -128,41 +120,30 @@ public struct PrintLogHandler: LogHandler {
public var logLevel: Logger.Level = .info
public var metadata: Logger.Metadata = [:]
public var metadataProvider: Logger.MetadataProvider?
public init(label: String) {
self.label = label
}
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
public func log(event: LogEvent) {
let timestamp = ISO8601DateFormatter().string(from: Date())
let levelString = level.rawValue.uppercased()
// Get provider metadata
let providerMetadata = metadataProvider?.get() ?? [:]
let levelString = event.level.rawValue.uppercased()
// Merge handler metadata with message metadata
let combinedMetadata = Self.prepareMetadata(
base: self.metadata,
provider: self.metadataProvider,
explicit: metadata
explicit: event.metadata
)
// Format metadata
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
// Create log line and print to console
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(event.message)"
print(logLine)
}
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get {
return self.metadata[key]
@@ -199,6 +180,49 @@ public struct PrintLogHandler: LogHandler {
}
```
#### Reading metadata attributes in LogHandlers
Metadata values can carry attributes alongside their string representation. Attributes are embedded inside
`MetadataValue` via the `.stringConvertible` case and are accessible through the `value.attributes` property. This
enables features like sensitivity annotations without any changes to your handler's protocol conformance.
To read attributes in your log handler:
```swift
public func log(event: LogEvent) {
// Merge handler metadata, provider metadata, and event metadata as usual
var merged = self.metadata
if let provider = self.metadataProvider {
merged.merge(provider.get(), uniquingKeysWith: { _, rhs in rhs })
}
if let eventMetadata = event.metadata {
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
}
// Read attributes from individual values:
for (key, value) in merged {
let attributes = value.attributes // Empty if the value carries no attributes
// Process based on your handler's needs
// For example, check for a custom attribute:
// if attributes[MyAttribute.self] == .flagged { ... }
}
}
```
**Key considerations:**
- **Opt-in inspection**: Attributes are invisible unless you call `value.attributes`. Handlers that do not care about
attributes work without any changes.
- **No new protocol requirements**: Reading attributes does not require implementing any new `LogHandler` properties
or subscripts. The `metadata` property and `metadataKey` subscript work exactly as before.
- **Attributes flow through metadata**: Attributed values flow naturally through metadata merging, `MetadataProvider`,
and `MultiplexLogHandler` — no special handling needed.
### Performance considerations
1. **Avoid blocking**: Don't block the calling thread for I/O operations.
@@ -0,0 +1,512 @@
# SLG-0004: Metadata value attributes
Add an extensible per-value attribute mechanism for metadata.
## Overview
- Proposal: SLG-0004
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
- Status: **Ready for Implementation**
- Issue: [apple/swift-log#204](https://github.com/apple/swift-log/issues/204)
- Implementation:
- [apple/swift-log#453](https://github.com/apple/swift-log/pull/453)
- Related links:
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
- [First iteration of the proposal](https://forums.swift.org/t/proposal-slg-0004-metadata-values-privacy-attribute/85249)
### Introduction
Introduce an extensible mechanism for attaching per-value attributes to metadata. The core `Logging` module provides
the protocol and storage. Attribute packages define concrete attributes using the
`Logger.MetadataValueAttributes.Attribute` protocol.
### Motivation
Metadata values in `swift-log` are opaque strings by the time the `LogHandler` receives them. The call site often
knows things about a value that the handler cannot infer — for example, whether the value should be redacted in
different environments.
Today, there is no way to express this. A single log statement can contain values that need different treatment, and
log levels cannot help because they are per-statement, not per-value:
```swift
logger.info("Login", metadata: [
"action": "\(action)", // safe to log
"user_email": "\(email)", // should be redacted in production, but nothing tells the handler
])
```
The workaround is handler-side key-based rules (`redact: ["email", "card-*", ...]`), but this is fragile:
- Rules break when libraries rename keys.
- Rules require coordination across all dependencies.
- The rule mapping is invisible at the call site.
### Proposed solution
Attributes are embedded directly in `MetadataValue` via the existing `.stringConvertible` case. A custom
`MetadataValue.StringInterpolation` type produces attributed values when any interpolation segment specifies
attributes. Libraries define attribute types conforming to `Logger.MetadataValueAttributes.Attribute` and provide
ergonomic string interpolation overloads. Handlers read the attributes via `value.attributes` and act on them:
```swift
import Logging
public enum Sensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case sensitive = 1
case `public` = 2
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, sensitivity: Sensitivity
) {
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
}
}
logger.info("Request", metadata: [
"method": "\(req.method)",
"user_id": "\(req.userId, sensitivity: .sensitive)",
])
```
Handlers that support specific attributes read them from `value.attributes` and act accordingly. Handlers that do not
understand attributes see plain `MetadataValue` instances — attributes are invisible unless explicitly inspected. The
existing `metadata:` parameter is the only parameter needed; no new log method overloads are added.
Attributed values can also be created programmatically with the `.attributed` factory, which behaves like an additional
enum case without breaking existing exhaustive switches:
```swift
let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
```
Intermediate handlers can read **and modify** attributes as metadata flows through a handler chain. The `attributes`
property supports both getting and setting, enabling composable pipelines where each handler in the chain can enrich,
transform, or strip attributes before forwarding:
```swift
// An enriching handler that tags all metadata with a processing timestamp attribute
func log(event: LogEvent) {
var mutatedEvent = event
if var eventMetadata = event.metadata {
for (key, _) in eventMetadata {
var attrs = eventMetadata[key]!.attributes
attrs[ProcessingStage.self] = .enriched
eventMetadata[key]?.attributes = attrs
}
mutatedEvent.metadata = eventMetadata
}
self.inner.log(event: mutatedEvent)
}
```
Attributes are **classifications, not enforcement**. An attribute does not guarantee any particular handler behavior —
the handler may not support it. Applications needing guaranteed behavior must enforce it at a different abstraction.
The attribute mechanism is extensible: packages define their own attribute types using
`Logger.MetadataValueAttributes.Attribute`. A
chained `LogHandler` can read the attributes it cares about, act on them, and forward the rest to the next handler in
the chain — enabling composable handler pipelines (e.g., redaction handler -> metrics-extraction handler -> output
handler). Common attributes should be defined in separate packages so that the core `Logging` module remains free of
domain-specific attributes while providing shared vocabulary across libraries. To improve discoverability, `swift-log`
can reference attribute packages that are common across the whole ecosystem.
### Detailed design
#### `Attribute` protocol
```swift
extension Logger.MetadataValueAttributes {
/// A protocol for defining custom metadata attributes.
///
/// Conform to this protocol to define a custom attribute that can be stored in
/// ``MetadataValueAttributes``. Each conforming type acts as both the key (identified
/// by its metatype) and the value.
///
/// This protocol is designed for **small, fixed-vocabulary attributes**.
/// Each attribute value is stored as an `Int64` raw value, so attributes occupy minimal
/// space (one inline slot without heap allocation for the common single-attribute case).
///
/// ## Examples
///
/// ```swift
/// public enum Priority: Int64, Sendable, Logger.MetadataValueAttributes.Attribute {
/// case low = 1
/// case high = 2
/// }
/// ```
///
/// ```swift
/// public struct Priority: Sendable, Hashable, Logger.MetadataValueAttributes.Attribute {
/// public let rawValue: Int64
/// public init(rawValue: Int64) {
/// self.rawValue = rawValue
/// }
/// public static let low = Priority(rawValue: 1)
/// public static let high = Priority(rawValue: 2)
/// }
/// ```
public protocol Attribute: Sendable,
RawRepresentable where RawValue == Int64 {}
}
```
Each conforming type serves as both the key and the value for an attribute. The metatype (`Key.Type`) identifies
the attribute at runtime — no coordination between packages is needed.
#### `MetadataValueAttributes`
```swift
extension Logger {
/// Attributes that can be associated with metadata values.
public struct MetadataValueAttributes: Sendable, Equatable, ExpressibleByArrayLiteral {
/// Nested ``Attribute`` protocol (see above).
public protocol Attribute: Sendable, RawRepresentable where RawValue == Int64 {}
/// Create empty metadata value attributes.
public init()
/// Create metadata value attributes from an array literal of attribute values.
///
/// ```swift
/// let attrs: MetadataValueAttributes = [Sensitivity.sensitive, ValueType.int64]
/// ```
public init(arrayLiteral elements: any Attribute...)
/// Get or set a custom attribute by its type.
///
/// - Parameter attribute: The metatype of the attribute to access.
/// - Returns: The attribute value, or `nil` if not set.
public subscript<Attr: Attribute>(attribute: Attr.Type) -> Attr? { get set }
}
}
```
The common case (0–1 attributes) avoids heap allocation. `Equatable` compares entries as an unordered set (O(n²),
n typically 0–2).
#### `MetadataValue.attributes` computed property
```swift
extension Logger.MetadataValue {
/// The attributes associated with this metadata value, if any.
///
/// **Getting:** When the value is a ``stringConvertible(_:)`` wrapping an attributed carrier,
/// returns that carrier's attributes. For all other cases returns empty attributes.
///
/// **Setting:** Replaces the value with `.stringConvertible(AttributedStringCarrier(...))`
/// carrying the given attributes. For `.string` and `.stringConvertible` cases the string
/// representation is preserved. For `.dictionary` and `.array` cases the setter is a no-op.
public var attributes: Logger.MetadataValueAttributes { get set }
}
```
This is the handler-side read/write API. Internally, the `Logging` module stores attributes in an internal
`AttributedStringCarrier` class wrapped by `.stringConvertible`. The getter check is a concrete type comparison — no
protocol conformance lookup. Users attach attributes via string interpolation and read them via this property. The
setter allows handlers to modify or add attributes as they process metadata values through the handler chain.
#### `MetadataValue.attributed` factory method
```swift
extension Logger.MetadataValue {
/// Creates an attributed metadata value from a string-convertible value and attributes.
public static func attributed(
_ value: some CustomStringConvertible & Sendable,
attributes: Logger.MetadataValueAttributes
) -> Self
}
```
This convenience factory behaves like an additional enum case, producing a
`.stringConvertible(AttributedStringCarrier(...))` value without requiring string interpolation:
```swift
let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
```
#### String interpolation
`MetadataValue` replaces its empty `ExpressibleByStringInterpolation` conformance with a custom `StringInterpolation`
type. When no attributes are specified, the result is `.string(...)` — identical to the previous behavior. When any
interpolation segment specifies attributes, the result is `.stringConvertible(...)` wrapping the internal carrier:
```swift
extension Logger.MetadataValue: ExpressibleByStringInterpolation {
/// Custom string interpolation that optionally captures metadata attributes.
///
/// When no attributes are specified, produces `.string(...)` — identical to the
/// default `DefaultStringInterpolation` behavior. When any interpolation segment
/// specifies attributes (via the `attributes:` parameter), the result is
/// `.stringConvertible(AttributedStringCarrier(...))` carrying both the string
/// and the accumulated attributes.
///
/// Attribute packages (like `LoggingAttributes`) can add overloads with
/// domain-specific parameters (e.g. `sensitivity:`) that call through to
/// `appendInterpolation(_:attributes:)`.
public struct StringInterpolation: StringInterpolationProtocol, Sendable {
public init(literalCapacity: Int, interpolationCount: Int)
public mutating func appendLiteral(_ literal: String)
/// Interpolation with a custom attributes closure.
///
/// When called, the result will be `.stringConvertible(AttributedStringCarrier(...))`
/// instead of `.string(...)`.
///
/// ```swift
/// "\(userId, attributes: { $0[MyAttribute.self] = .flagged })"
/// ```
public mutating func appendInterpolation<T>(
_ value: T,
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
) where T: CustomStringConvertible & Sendable
/// Plain interpolation without attributes.
public mutating func appendInterpolation<T>(
_ value: T
) where T: CustomStringConvertible & Sendable
/// Fallback interpolation for types that are not `CustomStringConvertible`.
public mutating func appendInterpolation<T>(
_ value: T
) where T: Sendable
/// Unconstrained fallback for non-`Sendable` types.
///
/// The value is immediately converted to `String` via `String(describing:)` and never
/// stored, so no `Sendable` safety issue arises. This overload exists so that interpolating
/// a non-`Sendable` type into a `MetadataValue` continues to compile, matching the behavior
/// of `DefaultStringInterpolation`.
public mutating func appendInterpolation<T>(
_ value: T
)
}
/// Creates a metadata value from string interpolation.
///
/// If any interpolation segment specified attributes, the result is
/// `.stringConvertible(AttributedStringCarrier(...))`. Otherwise, `.string(...)`.
public init(stringInterpolation: StringInterpolation)
}
```
Attribute packages add ergonomic overloads that wrap the closure-based method — for example:
```swift
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, sensitivity: Sensitivity
) {
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
}
}
```
This enables the clean call-site syntax: `"\(userId, sensitivity: .sensitive)"`.
When a single `MetadataValue` contains multiple interpolated segments with different attributes, the merging behavior
is defined by each attribute's `appendInterpolation` implementation.
#### No changes to `Logger`, `LogHandler`, `LogEvent`, or `MetadataProvider`
Unlike earlier iterations of this proposal, the piggyback approach requires **no new API** on `Logger`, `LogHandler`,
`LogEvent`, or `MetadataProvider`:
- **`Logger`**: No new `attributedMetadata:` log method overloads. Attributes flow through the existing `metadata:`
parameter.
- **`LogHandler`**: No new protocol requirements. No `attributedMetadata` property, no `attributedMetadataKey`
subscript. Existing handlers work unchanged.
- **`LogEvent`**: No dual storage. `metadata` remains a simple `Logger.Metadata?` stored property. Values inside the
dictionary may carry attributes, but `LogEvent` is unaware of this.
- **`MetadataProvider`**: No `.attributed()` factory or `getAttributedMetadata()` method. Providers return
`Logger.Metadata` where values may carry attributes via string interpolation.
### API stability
- **Existing `Logger` users.** No changes to existing API. The same `metadata:` parameter carries attributed values.
- **Existing `LogHandler` implementations.** No protocol changes. Handlers that only call `.description` on metadata
values see the string as before — attributes are invisible. Handlers that want to inspect attributes read
`value.attributes`.
### Future directions
- **Attribute-aware equality.** The current `MetadataValue` equality for `.stringConvertible` values compares only
`.description`, ignoring attributes. Two values with the same text but different attributes compare as equal. A
future proposal could refine equality to include attributes when both sides carry them, but this
requires careful consideration of backward compatibility since existing code may rely on description-only equality.
- **Metadata values sensitivity attribute.** A separate ecosystem package could add the sensitivity attribute,
allowing compatible `LogHandler` to redact values in certain situations.
- **Typed metadata values.** A separate ecosystem package could add typed variants to `MetadataValue` (`.int64`,
`.double`, `.bool`), reducing the need for attributes that compensate for stringly-typed metadata.
### Alternatives considered
#### Wrapper type with parallel API ("attributed metadata value" approach)
Introduce an `AttributedMetadataValue` struct wrapping `MetadataValue` + `MetadataValueAttributes`, a separate
`AttributedMetadata` typealias, new `attributedMetadata:` overloads on all Logger methods, dual storage in
`LogEvent`, and new `LogHandler` protocol requirements. This was the design in the first iteration of this proposal.
It provides strong type separation but creates a parallel API surface: 7 new convenience methods, new protocol
requirements with default implementations, dual `MetadataStorage` enum in `LogEvent`, and `mapValues` bridging
between plain and attributed representations. The piggyback approach achieves the same functionality by embedding
attributes inside `MetadataValue` via the existing `.stringConvertible` case, avoiding the parallel universe
entirely.
#### Sidecar dictionary on `LogEvent`
Store attributes in a separate `[String: MetadataValueAttributes]` dictionary on `LogEvent`, keyed by the same
metadata keys. This keeps `MetadataValue` unchanged but introduces sync issues — attributes can drift out of sync
with metadata keys when handlers merge or transform metadata. The piggyback approach avoids this by co-locating
attributes with the value they describe.
#### New enum case on `MetadataValue`
Add a dedicated `.attributed(String, MetadataValueAttributes)` case to the `MetadataValue` enum. This would make
attributes statically visible in the type — no runtime downcast needed, and `switch` statements would handle
attributed values explicitly. However, `MetadataValue` is a public enum that is exhaustively matched by every
`LogHandler` in the ecosystem. Adding a case is source-breaking: every existing handler's `switch` over
`MetadataValue` would fail to compile until updated. The piggyback approach avoids this by reusing the existing
`.stringConvertible` case, which handlers already handle.
#### Concrete stored property instead of extensible mechanism
Add concrete stored properties (e.g., `var sensitivity: Sensitivity?`) on `MetadataValueAttributes`. Simpler, but
closed — chained handlers cannot define their own attributes. The extensible mechanism keeps the core `Logging` module
free of domain-specific attributes.
#### Bitmask storage
Pack attribute values into an inline `UInt64` using declared bit offsets. O(1) access, but requires authors to
coordinate bit layout and risks collisions between independent packages.
#### Pure dynamic array storage
Use a dynamic array for all attributes with no inline slot. Simpler, but requires heap allocation even for the first
attribute.
#### No per-value attributes
Rely on handler-side configuration (key-name-based rules). Simpler, but fragile — rules break when keys are renamed,
require coordination across all dependencies, and are invisible at the call site.
### Example attributes
The following examples illustrate how ecosystem packages could define attributes using the
`Logger.MetadataValueAttributes.Attribute` protocol. These are not part of this proposal.
#### Sensitivity
A sensitivity attribute for marking metadata values that contain private or personally identifiable information:
```swift
public enum Sensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case sensitive = 1
case `public` = 2
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, sensitivity: Sensitivity
) {
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
}
}
logger.info("Request", metadata: [
"method": "\(req.method)",
"user_id": "\(req.userId, sensitivity: .sensitive)",
])
```
A handler reads the attribute:
```swift
for (key, value) in mergedMetadata {
if value.attributes[Sensitivity.self] == .sensitive {
// redact this value
}
}
```
#### Value type hint
A type hint for structured logging backends that benefit from native types:
```swift
public enum ValueType: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case string = 1
case int64 = 2
case double = 3
case bool = 4
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, valueType: ValueType
) {
self.appendInterpolation(value, attributes: { $0[ValueType.self] = valueType })
}
}
logger.info("Metrics", metadata: [
"latency_ms": "\(latency, valueType: .double)",
"retry_count": "\(retries, valueType: .int64)",
])
```
#### Metric extraction
A metric attribute for a chained `LogHandler` that dual-writes to swift-metrics:
```swift
public enum MetricKind: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case counter = 1
case gauge = 2
case histogram = 3
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, metricKind: MetricKind
) {
self.appendInterpolation(value, attributes: { $0[MetricKind.self] = metricKind })
}
}
logger.info("Request completed", metadata: [
"duration_ms": "\(duration, metricKind: .histogram)",
"error_count": "\(errors, metricKind: .counter)",
])
```
#### Attribute-enriching intermediate handler
An intermediate `LogHandler` that reads and modifies attributes before forwarding to the next handler in the chain.
This pattern enables composable pipelines — for example, a handler that adds a default sensitivity to all metadata
values that do not already carry one:
```swift
struct DefaultSensitivityHandler: LogHandler {
private var inner: any LogHandler
// ... logLevel, metadata, metadataProvider forwarded to inner ...
func log(event: LogEvent) {
var mutatedEvent = event
if var eventMetadata = event.metadata {
for (key, _) in eventMetadata {
if eventMetadata[key]?.attributes[Sensitivity.self] == nil {
eventMetadata[key]?.attributes = [Sensitivity.sensitive]
}
}
mutatedEvent.metadata = eventMetadata
}
self.inner.log(event: mutatedEvent)
}
}
```
With this handler in the chain, any metadata value without an explicit sensitivity annotation is treated as sensitive
by default — a "deny by default" policy that individual call sites can override with `.public`.
@@ -1,467 +0,0 @@
# SLG-0004: Metadata values privacy attribute
Introduce an attributed metadata system that allows attaching attributes to metadata values, with privacy level as the first attribute enabling developers to mark metadata as `.private` or `.public`.
## Overview
- Proposal: SLG-0004
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
- Status: **Deferred**
- Issue: https://github.com/apple/swift-log/issues/204
- Implementation:
- [apple/swift-log#418](https://github.com/apple/swift-log/pull/418)
- Related links:
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
- [Review discussion](https://forums.swift.org/t/proposal-slg-0004-metadata-values-privacy-attribute/85249/16)
### Introduction
This proposal introduces an **attributed metadata system** that allows attaching attributes to metadata values. Privacy level is the first concrete attribute, enabling developers to mark metadata values as `.private` or `.public` so `LogHandler` implementations can redact sensitive values before logging.
### Motivation
SwiftLog lacks a mechanism to attach attributes to metadata values. This prevents marking metadata as sensitive and limits future extensibility for other metadata attributes.
Applications need privacy controls for:
- Compliance with privacy regulations.
- Backend integration with privacy-aware logging systems.
- Systematic control over what data appears in logs.
Beyond privacy, an attributed metadata system provides a foundation for future extensions such as retention policies, data classification, or other metadata attributes.
### Proposed solution
Introduce new `AttributedMetadata` data type, enabling users to mark metadata values with `.private` and `.public` privacy label:
```swift
// Add privacy level to metadata values obtained through a metadata provider
let serviceIp = "127.0.0.1"
var logger = Logger(label: "my-app", metadataProvider: .init {[
"service.ip": "\(serviceIp, privacy: .private)",
]})
// Add privacy level to metadata values attached to a `Loghandler` instance
let requestId = UUID()
logger[attributedMetadataKey: "request.id"] = "\(requestId, privacy: .private)"
// Mark sensitive values as private and non-sensitive as public at logging call site
let userId = UUID()
let action = "login"
logger.info("User action", attributedMetadata: [
"user.id": "\(userId, privacy: .private)",
"action": "\(action)" // default is .public for ease of adoption
])
```
This allows `Logger` users to mark certain metadata values as "I only trust LogHandlers, who know how to handle sensitive data, to see this value".
### Detailed design
#### Attributed Metadata
To support privacy labels and enable future extensibility, we introduce a generalized **attributed metadata** system. This provides a foundation for attaching arbitrary attributes to metadata values, with privacy labels being the first concrete use case:
```swift
// Plain metadata (existing)
let metadataValue: MetadataValue = .string("value")
logger.info("Message", metadata: ["key": metadataValue])
// Attributed metadata (new) — a value with attributes
logger.info("Message", attributedMetadata: [
"key": AttributedMetadataValue(value: metadataValue, attributes: ...)
])
```
The attributed metadata system instroduces new public API:
1. **`AttributedMetadataValue`**: Wraps a standard `MetadataValue` with associated attributes.
2. **`MetadataValueAttributes`**: Container for attributes.
3. **`AttributedMetadata`**: Dictionary type mapping `String` keys to attributed values.
4. **Parallel logging API**: New log methods accepting `attributedMetadata` parameter.
This design separates the transport mechanism (attributed metadata) from specific attribute semantics (privacy labels), allowing future extensions without breaking existing attributed metadata code.
#### Privacy levels
With attributed metadata as the foundation, privacy labels are implemented as the first concrete attribute:
```swift
extension Logger {
/// A metadata value with associated privacy attributes.
///
/// `AttributedMetadataValue` wraps a standard `MetadataValue` with privacy attributes,
/// allowing you to mark metadata as private or public for privacy-aware logging.
///
/// ## Creating Attributed Metadata
///
/// Use string interpolation with privacy parameter:
///
/// ```swift
/// // Preferred: String interpolation with privacy level specified
/// let userId = "12345"
/// let action = "login"
/// logger.info("User action", attributedMetadata: [
/// "user.id": "\(userId, privacy: .private)",
/// "action": "\(action, privacy: .public)" // explicit .public for non-sensitive data
/// ])
///
/// // Direct creation
/// let attributed = Logger.AttributedMetadataValue(
/// .string("12345"),
/// privacy: .private
/// )
/// ```
///
/// ## Important Limitations
///
/// - **No nested privacy**: When marking a dictionary or array as private, all contained
/// values are treated with the same privacy level. Fine-grained privacy within nested
/// structures is not currently supported.
///
/// - **Metadata only**: Privacy levels apply only to metadata values, not to log messages.
/// Avoid including sensitive data in log message string interpolation.
public struct AttributedMetadataValue: CustomStringConvertible, Sendable {
/// The redaction marker used for private values.
internal static let redactionMarker = "<private>"
public let value: MetadataValue
public let attributes: MetadataValueAttributes
/// String representation redacts private values to the redaction marker.
public var description: String {
attributes.privacy == .public ? value.description : Self.redactionMarker
}
public init(_ value: MetadataValue, attributes: MetadataValueAttributes)
public init(_ value: MetadataValue, privacy: PrivacyLevel)
}
extension AttributedMetadataValue {
/// Attributes that can be associated with metadata values.
public struct MetadataValueAttributes: CustomStringConvertible, Hashable, Sendable {
/// Privacy level for metadata values.
///
/// Privacy levels allow you to mark metadata values as either private (sensitive data that should be
/// protected) or public (safe to log in any context).
///
/// ## Usage
///
/// Use string interpolation with the privacy parameter to create attributed metadata values:
///
/// ```swift
/// let userId = "12345"
/// let action = "login"
/// logger.info("User action", attributedMetadata: [
/// "user.id": "\(userId, privacy: .private)",
/// "action": "\(action, privacy: .public)",
/// "ip": "\(ipAddress, privacy: .private)"
/// ])
/// ```
@frozen
public enum PrivacyLevel: Sendable, CaseIterable, Equatable, Hashable, CustomStringConvertible {
/// Private data that should be redacted in non-secure contexts.
case `private`
/// Public data safe for general logging.
case `public`
}
/// The privacy level of this metadata value.
public var privacy: PrivacyLevel
/// Create metadata value attributes with the specified privacy level.
///
/// - Parameter privacy: The privacy level for this metadata. Defaults to `.public`.
public init(privacy: PrivacyLevel = .public)
}
/// The underlying metadata value without privacy attributes.
public var value: MetadataValue
/// The privacy attributes associated with this metadata value.
public var attributes: MetadataValueAttributes
/// Create an attributed metadata value with the specified attributes.
///
/// - Parameters:
/// - value: The metadata value to wrap.
/// - attributes: The attributes for this value.
public init(_ value: MetadataValue, attributes: MetadataValueAttributes)
/// Convenience initializer for creating attributed metadata with a privacy level.
///
/// - Parameters:
/// - value: The metadata value to wrap.
/// - privacy: The privacy level for this value.
public init(_ value: MetadataValue, privacy: PrivacyLevel)
}
/// Metadata dictionary with privacy attributes.
///
/// A dictionary mapping string keys to ``AttributedMetadataValue`` instances, used with
/// the `attributedMetadata` parameter of logging methods.
///
/// ## Example
///
/// ```swift
/// let userId = "12345"
/// let requestId = "req-789"
/// let metadata: Logger.AttributedMetadata = [
/// "user.id": "\(userId, privacy: .private)",
/// "request.id": "\(requestId, privacy: .public)",
/// "action": "purchase" // String literal defaults to .public
/// ]
/// logger.info("User action", attributedMetadata: metadata)
/// ```
public typealias AttributedMetadata = [String: AttributedMetadataValue]
}
```
#### String interpolation for attributed metadata
```swift
extension Logger.AttributedMetadataValue: ExpressibleByStringLiteral, ExpressibleByStringInterpolation {
/// Custom string interpolation that captures privacy levels from interpolated values.
///
/// This enables syntax like:
/// ```swift
/// logger.info("User action", attributedMetadata: [
/// "user.id": "\(userId, privacy: .private)",
/// "action": "\(action, privacy: .public)"
/// ])
/// ```
public struct StringInterpolation: StringInterpolationProtocol {
public init(literalCapacity: Int, interpolationCount: Int)
public mutating func appendLiteral(_ literal: String)
/// Interpolation with explicit privacy parameter.
public mutating func appendInterpolation<T>(_ value: T, privacy: Logger.PrivacyLevel = .public)
where T: CustomStringConvertible
}
/// Creates an attributed metadata value from a string literal (defaults to .public).
public init(stringLiteral value: String)
/// Creates an attributed metadata value from string interpolation.
public init(stringInterpolation: StringInterpolation)
}
```
#### New Logger methods
```swift
extension Logger {
// Attributed metadata storage
var attributedMetadata: Logger.AttributedMetadata { get set }
subscript(attributedMetadataKey: String) -> Logger.AttributedMetadataValue? { get set }
// Log family of methods
public func log(level: Level, _ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
public func trace(_ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
public func debug(_ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
public func info(_ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
public func notice(_ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
public func warning(_ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
public func error(_ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
public func critical(_ message: @autoclosure () -> Message,
attributedMetadata: @autoclosure () -> AttributedMetadata?,
source: @autoclosure () -> String? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line)
}
```
#### AttributedMetadata support in LogHandler protocol
```swift
protocol LogHandler {
func log(level: Logger.Level, message: Logger.Message,
attributedMetadata: Logger.AttributedMetadata?, source: String,
file: String, function: String, line: UInt)
var attributedMetadata: Logger.AttributedMetadata { get set }
subscript(attributedMetadataKey: String) -> Logger.AttributedMetadataValue? { get set }
}
// Default implementations provided for backward compatibility
extension LogHandler {
// Default attributed metadata log method - redacts private values using helper
public func log(level: Logger.Level, message: Logger.Message,
attributedMetadata: Logger.AttributedMetadata?,
source: String, file: String, function: String, line: UInt) {
let processedMetadata = attributedMetadata.flatMap(Self.attributedToPlain)
self.log(level: level, message: message, metadata: processedMetadata,
source: source, file: file, function: function, line: line)
}
// Default attributed metadata storage - uses helpers for conversion
public var attributedMetadata: Logger.AttributedMetadata {
get { self.metadata.mapValues(Self.plainToAttributed) }
set { self.metadata = newValue.mapValues(Self.attributedToPlain) }
}
public subscript(attributedMetadataKey key: String) -> Logger.AttributedMetadataValue? {
get {
guard let plainValue = self[metadataKey: key] else { return nil }
return Self.plainToAttributed(plainValue)
}
set {
if let attributedValue = newValue {
self[metadataKey: key] = Self.attributedToPlain(attributedValue)
} else {
self[metadataKey: key] = nil
}
}
}
}
```
#### AttributedMetadata support in MetadataProvider
```swift
extension Logger.MetadataProvider {
/// Creates a new metadata provider that returns attributed metadata.
///
/// Attributed metadata providers allow you to specify privacy levels and other
/// attributes for each metadata value. When accessed through the plain ``get()``
/// method (for backward compatibility), private values are redacted to `"<private>"`.
///
/// ### Example
///
/// ```swift
/// let provider = Logger.MetadataProvider {
/// [
/// "request-id": "\(RequestContext.current.id, privacy: .public)",
/// "user-id": "\(RequestContext.current.userId, privacy: .private)"
/// ]
/// }
/// ```
///
/// - Parameter provideAttributed: A closure that extracts attributed metadata from the current execution context.
/// - Returns: A metadata provider that returns attributed metadata.
@_disfavoredOverload
public static func init(_ provideAttributed: @escaping @Sendable () -> AttributedMetadata) -> MetadataProvider
/// Returns attributed metadata if this is an attributed provider.
///
/// Handlers supporting attributed metadata should call this first,
/// falling back to `get()` if it returns nil.
public func getAttributed() -> AttributedMetadata?
}
```
### API stability
- All existing APIs unchanged.
- Plain and attributed metadata APIs coexist.
- No deprecation planned.
- Adoption is optional and incremental on both application and Log Handler sides.
- Default implementation ensures existing handlers work; logging private metadata is an application concern requiring a compatible `LogHandler`.
### Future directions
- Add more attributes (e.g., value data type, etc) and potential future unification of plain and attributed metadata APIs.
- Introduce "custom attributes", allowing applications to define application-specific attributes to work with application-specific log handlers.
### Alternatives considered
1. **Key-based redaction:** Configure which keys should be treated as private rather than marking each value:
```swift
logger.privateKeys = ["user.id", "password", "email"]
logger.info("User action", metadata: [
"user.id": "12345", // Automatically private
"action": "login" // Automatically public
])
```
Advantages:
- Simpler API (no new types).
- Centralized configuration.
- Safer at scale (new sensitive fields update all logs automatically).
- Easier migration.
**Not chosen because:**
- **Privacy belongs to data, not identifiers:** The same private data might be logged under different keys ("email", "user.email", "contact"), and the same key might contain different data with different privacy requirements in different contexts. Key-based redaction creates a synchronization problem—developers must maintain a separate list of "private keys" that stays in sync with actual logging code across the codebase, with no compile-time or review-time verification.
- **Code review visibility:** With value-based privacy, reviewers see privacy decisions at the call site: `"email": user.email.private()` makes it immediately clear that data is sensitive. With key-based redaction, reviewers must cross-reference a separate configuration file, making security review significantly harder.
- **No synchronization needed:** Value-based privacy is self-contained—privacy travels with the data at the point of use. No separate configuration to maintain, no risk of configuration drift, no runtime surprises when a key is missing from the private keys list.
- **Pattern complexity:** Supporting patterns/regex adds complexity and potential performance concerns.
The current design prioritizes **explicitness and data-centric privacy** over **configuration-based simplicity**. Privacy decisions are made where data is logged, making them visible during code review and keeping privacy attributes coupled to the data they protect.
2. **Convenience methods (`.private()` and `.public()`):** Add extension methods to `String` and `MetadataValue` for creating attributed metadata:
```swift
extension String {
public func `private`() -> Logger.AttributedMetadataValue
public func `public`() -> Logger.AttributedMetadataValue
}
logger.info("User action", attributedMetadata: [
"user.id": "12345".private(),
"action": "login".public()
])
```
**Not chosen because:**
- **Consistency with existing patterns:** `Logger.Message` and `Logger.MetadataValue` already use string interpolation extensively.
- **Natural syntax:** `"\(value, privacy: .private)"` reads clearly and fits Swift's interpolation conventions.
- **Less API surface:** No need for multiple extension methods across different types.
Metadata values already support string interpolation in SwiftLog. Rather than inventing additional API surface area with new methods, we leverage the existing string interpolation infrastructure with a custom `StringInterpolation` type. This provides:
3. **Default privacy level to `.private`:** Make attributed metadata values default to `.private` privacy level when no explicit privacy parameter is provided:
```swift
logger.info("User action", attributedMetadata: [
"user.id": "\(userId, privacy: .private)", // Explicit private (redundant with default)
"action": "\(action, privacy: .public)" // Must explicitly mark as public
])
```
Advantages:
- Security-by-default: requires explicit opt-out for logging non-sensitive data.
- Safer for accidental inclusion of sensitive data.
**Not chosen because:**
Privacy should be an explicit opt-in action from the user. The current design (defaulting to `.public`) prioritizes **ease of adoption** over **security-by-default**:
- Easier adoption - less boilerplate for common non-sensitive metadata.
- Matches the mental model that "most data is safe to log".
- Lower friction for migration from plain metadata.
- Forces developers to think about privacy only for sensitive data, rather than requiring `.public` annotations everywhere.
4. **Pass all metadata to non-privacy-aware handlers:** Security risk; current design filters private data by default.
5. **Message-level privacy:** Less granular than metadata-level privacy and requires message handling changes.
6. **Privacy level handling configuration** to be an attribute of the `Logger` instead of LogHandler configuration. This would centralize the configuration across various `LogHandler` implementations. However, existing `LogHandler` already have configurations and they might want to customize the behavior even further.
7. **Handler metadata merging:** LogHandlers are responsible for merging their own `metadata` property, `metadataProvider` output, and the explicit `attributedMetadata` parameter. This is consistent with how plain metadata works - handlers control merging. Plain handler metadata and provider values should be treated as public (`.public` privacy level). Attributed metadata from the log call takes precedence.
8. **Add a third `.auto`/`.default` privacy attribute value:** Libraries and applications can mark a metadata value as `privacy: .default` and rely on the `LogHandler` to configure what the default is. While this might've been a solution to overcome default `.public` values for all the attributed metadata, in reality it is confusing from the semantic point of view. If someone wants to mark something as `.default`, because this _might_ be sensitive, then it should be marked as `.private` or not logged at all. If something does not need to be marked as `.private`, then it is `.public`. A custom `LogHandler` with an allow list of metadata keys/messages/modules can be used as an escape hatch in case the application does not trust its dependencies.
@@ -0,0 +1,19 @@
# ``Logging/LogEvent``
## Topics
### Creating a log event
- ``init(level:message:metadata:source:file:function:line:)``
- ``init(level:message:error:metadata:source:file:function:line:)``
### Inspecting a log event
- ``level``
- ``message``
- ``error``
- ``metadata``
- ``source``
- ``file``
- ``function``
- ``line``
@@ -4,6 +4,8 @@
### Sending log messages
- ``log(event:)-7x67``
- ``log(event:)-17f2r``
- ``log(level:message:metadata:source:file:function:line:)-8kgt7``
- ``log(level:message:metadata:source:file:function:line:)-69pez``
- ``log(level:message:metadata:file:function:line:)-89rya``
@@ -4,7 +4,7 @@
### Creating a metadata provider
- ``init(_:)``
- ``init(_:)-(()->Logger.Metadata)``
### Invoking the provider
@@ -14,35 +14,49 @@
- ``trace(_:metadata:file:function:line:)``
- ``trace(_:metadata:source:file:function:line:)``
- ``trace(_:error:metadata:source:file:function:line:)``
### Sending debug log messages
- ``debug(_:metadata:file:function:line:)``
- ``debug(_:metadata:source:file:function:line:)``
- ``debug(_:error:metadata:source:file:function:line:)``
### Sending info log messages
- ``info(_:metadata:file:function:line:)``
- ``info(_:metadata:source:file:function:line:)``
- ``info(_:error:metadata:source:file:function:line:)``
### Sending notice log messages
- ``notice(_:metadata:file:function:line:)``
- ``notice(_:metadata:source:file:function:line:)``
- ``notice(_:error:metadata:source:file:function:line:)``
### Sending warning log messages
- ``warning(_:metadata:file:function:line:)``
- ``warning(_:metadata:source:file:function:line:)``
- ``warning(_:error:metadata:source:file:function:line:)``
### Sending error log messages
- ``error(_:metadata:file:function:line:)``
- ``error(_:metadata:source:file:function:line:)``
- ``error(_:error:metadata:source:file:function:line:)``
### Sending critical log messages
- ``critical(_:metadata:file:function:line:)``
- ``critical(_:metadata:source:file:function:line:)``
- ``critical(_:error:metadata:source:file:function:line:)``
### Sending general log messages
- ``log(level:_:metadata:file:function:line:)``
- ``log(level:_:metadata:source:file:function:line:)``
- ``log(level:_:error:metadata:source:file:function:line:)``
- ``Level``
- ``Message``
- ``Metadata``
@@ -52,6 +66,10 @@
- ``subscript(metadataKey:)``
- ``MetadataValue``
### Metadata attribute types
- ``MetadataValueAttributes``
### Inspecting a logger
- ``label``
@@ -9,6 +9,7 @@
### Sending log messages
- ``log(event:)``
- ``log(level:message:metadata:source:file:function:line:)``
### Updating metadata
@@ -11,6 +11,7 @@
### Sending log messages
- ``log(event:)``
- ``log(level:message:metadata:source:file:function:line:)``
### Updating metadata
@@ -1,5 +1,7 @@
# ``Logging/SwiftLogNoOpLogHandler``
A log handler that silently discards all log messages.
## Topics
### Creating a Swift Log no-op log handler
@@ -9,7 +11,9 @@
### Sending log messages
- ``log(event:)``
- ``log(level:message:metadata:source:file:function:line:)``
- ``log(level:message:metadata:file:function:line:)``
### Updating metadata
+2 -1
View File
@@ -17,7 +17,7 @@ This separation allows libraries to adopt the API while applications choose any
compatible logging backend implementation without requiring changes from
libraries.
## Getting Started
### Getting Started
Use this package if you're writing a cross-platform application (for example, Linux and
macOS) or library, and want to target this logging API.
@@ -84,6 +84,7 @@ backend.
### Log Handlers
- ``LogHandler``
- ``LogEvent``
- ``MultiplexLogHandler``
- ``StreamLogHandler``
- ``SwiftLogNoOpLogHandler``
@@ -0,0 +1,227 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// A pseudo log handler that sends messages to multiple other log handlers.
///
/// ### Effective Logger.Level
///
/// When first initialized, the multiplex log handlers' log level is automatically set to the minimum of all the
/// provided log handlers.
/// This ensures that each of the handlers are able to log at their appropriate level
/// any log events they might be interested in.
///
/// Example:
/// If log handler `A` is logging at `.debug` level, and log handler `B` is logging at `.info` level, the log level of the constructed
/// `MultiplexLogHandler([A, B])` is set to `.debug`. This means that this handler will operate on debug messages,
/// while only logged by the underlying `A` log handler (since `B`'s log level is `.info`
/// and thus it would not actually log that log message).
///
/// If the log level is _set_ on a `Logger` backed by an `MultiplexLogHandler` the log level applies to *all*
/// underlying log handlers, allowing a logger to still select at what level it wants to log regardless of if the underlying
/// handler is a multiplex or a normal one. If for some reason one might want to not allow changing a log level of a specific
/// handler passed into the multiplex log handler, this is possible by wrapping it in a handler which ignores any log level changes.
///
/// ### Effective Logger.Metadata
///
/// Since a `MultiplexLogHandler` is a combination of multiple log handlers, the handling of metadata can be non-obvious.
/// For example, the underlying log handlers may have metadata of their own set before they are used to initialize the multiplex log handler.
///
/// The multiplex log handler acts purely as proxy and does not make any changes to underlying handler metadata other than
/// proxying writes that users made on a `Logger` instance backed by this handler.
///
/// Setting metadata is always proxied through to _all_ underlying handlers, meaning that if a modification like
/// `logger[metadataKey: "x"] = "y"` is made, all the underlying log handlers used to create the multiplex handler
/// observe this change.
///
/// Reading metadata from the multiplex log handler MAY need to pick one of conflicting values if the underlying log handlers
/// were previously initiated with metadata before passing them into the multiplex handler. The multiplex handler uses
/// the order in which the handlers were passed in during its initialization as a priority indicator - the first handler's
/// values are more important than the next handlers values, etc.
///
/// Example:
/// If the multiplex log handler was initiated with two handlers like this: `MultiplexLogHandler([handler1, handler2])`.
/// The handlers each have some already set metadata: `handler1` has metadata values for keys `one` and `all`, and `handler2`
/// has values for keys `two` and `all`.
///
/// A query through the multiplex log handler the key `one` naturally returns `handler1`'s value, and a query for `two`
/// naturally returns `handler2`'s value.
/// Querying for the key `all` will return `handler1`'s value, as that handler has a high priority,
/// as indicated by its earlier position in the initialization, than the second handler.
/// The same rule applies when querying for the `metadata` property of the multiplex log handler; it constructs `Metadata` uniquing values.
public struct MultiplexLogHandler: LogHandler {
private var handlers: [any LogHandler]
private var effectiveLogLevel: Logger.Level
/// This metadata provider runs after all metadata providers of the multiplexed handlers.
private var _metadataProvider: Logger.MetadataProvider?
/// Create a multiplex log handler.
///
/// - parameters:
/// - handlers: An array of `LogHandler`s, each of which will receive the log messages sent to this `Logger`.
/// The array must not be empty.
public init(_ handlers: [any LogHandler]) {
assert(!handlers.isEmpty, "MultiplexLogHandler.handlers MUST NOT be empty")
self.handlers = handlers
self.effectiveLogLevel = handlers.map { $0.logLevel }.min() ?? .trace
}
/// Create a multiplex log handler with the metadata provider you provide.
/// - Parameters:
/// - handlers: An array of `LogHandler`s, each of which will receive every log message sent to this `Logger`.
/// The array must not be empty.
/// - metadataProvider: The metadata provider that adds metadata to log messages for this handler.
public init(_ handlers: [any LogHandler], metadataProvider: Logger.MetadataProvider?) {
assert(!handlers.isEmpty, "MultiplexLogHandler.handlers MUST NOT be empty")
self.handlers = handlers
self.effectiveLogLevel = handlers.map { $0.logLevel }.min() ?? .trace
self._metadataProvider = metadataProvider
}
/// Get or set the log level configured for this `Logger`.
///
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
/// > It is acceptable for logging backends to have some form of global log level override
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
/// > certain cases have no effect.
public var logLevel: Logger.Level {
get {
self.effectiveLogLevel
}
set {
self.mutatingForEachHandler { $0.logLevel = newValue }
self.effectiveLogLevel = newValue
}
}
/// The metadata provider.
public var metadataProvider: Logger.MetadataProvider? {
get {
if self.handlers.count == 1 {
if let innerHandler = self.handlers.first?.metadataProvider {
if let multiplexHandlerProvider = self._metadataProvider {
return .multiplex([innerHandler, multiplexHandlerProvider])
} else {
return innerHandler
}
} else if let multiplexHandlerProvider = self._metadataProvider {
return multiplexHandlerProvider
} else {
return nil
}
} else {
var providers: [Logger.MetadataProvider] = []
let additionalMetadataProviderCount = (self._metadataProvider != nil ? 1 : 0)
providers.reserveCapacity(self.handlers.count + additionalMetadataProviderCount)
for handler in self.handlers {
if let provider = handler.metadataProvider {
providers.append(provider)
}
}
if let multiplexHandlerProvider = self._metadataProvider {
providers.append(multiplexHandlerProvider)
}
guard !providers.isEmpty else {
return nil
}
return .multiplex(providers)
}
}
set {
self.mutatingForEachHandler { $0.metadataProvider = newValue }
}
}
/// Log a message using the log level and source that you provide.
///
/// - parameters:
/// - event: The log event containing the level, message, metadata, and source location.
public func log(event: LogEvent) {
for handler in self.handlers where handler.logLevel <= event.level {
handler.log(event: event)
}
}
@available(*, deprecated, renamed: "log(event:)")
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
self.log(
event: LogEvent(
level: level,
message: message,
metadata: metadata,
source: source,
file: file,
function: function,
line: line
)
)
}
/// Get or set the entire metadata storage as a dictionary.
public var metadata: Logger.Metadata {
get {
var effective: Logger.Metadata = [:]
// as a rough estimate we assume that the underlying handlers have a similar metadata count,
// and we use the first one's current count to estimate how big of a dictionary we need to allocate:
// !-safe, we always have at least one handler
effective.reserveCapacity(self.handlers.first!.metadata.count)
for handler in self.handlers {
effective.merge(handler.metadata, uniquingKeysWith: { _, handlerMetadata in handlerMetadata })
if let provider = handler.metadataProvider {
effective.merge(provider.get(), uniquingKeysWith: { _, provided in provided })
}
}
if let provider = self._metadataProvider {
effective.merge(provider.get(), uniquingKeysWith: { _, provided in provided })
}
return effective
}
set {
self.mutatingForEachHandler { $0.metadata = newValue }
}
}
/// Add, change, or remove a logging metadata item.
///
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
public subscript(metadataKey metadataKey: Logger.Metadata.Key) -> Logger.Metadata.Value? {
get {
for handler in self.handlers {
if let value = handler[metadataKey: metadataKey] {
return value
}
}
return nil
}
set {
self.mutatingForEachHandler { $0[metadataKey: metadataKey] = newValue }
}
}
private mutating func mutatingForEachHandler(_ mutator: (inout any LogHandler) -> Void) {
for index in self.handlers.indices {
mutator(&self.handlers[index])
}
}
}
@@ -0,0 +1,429 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
#if canImport(Darwin)
import Darwin
#elseif os(Windows)
import CRT
#elseif canImport(Glibc)
@preconcurrency import Glibc
#elseif canImport(Android)
@preconcurrency import Android
#elseif canImport(Musl)
import Musl
#elseif canImport(WASILibc)
import WASILibc
#else
#error("Unsupported runtime")
#endif
/// Stream log handler presents log messages to STDERR or STDOUT.
///
/// This is a simple implementation of `LogHandler` that directs
/// `Logger` output to either `stderr` or `stdout` via the factory methods.
///
/// Metadata is merged in the following order:
/// 1. Metadata set on the log handler itself is used as the base metadata.
/// 2. The handler's ``metadataProvider`` is invoked, overriding any existing keys.
/// 3. The per-log-statement metadata is merged, overriding any previously set keys.
public struct StreamLogHandler: LogHandler {
internal typealias _SendableTextOutputStream = TextOutputStream & Sendable
/// Creates a stream log handler that directs its output to STDOUT.
public static func standardOutput(label: String) -> StreamLogHandler {
StreamLogHandler(
label: label,
stream: StdioOutputStream.stdout,
metadataProvider: LoggingSystem.metadataProvider
)
}
/// Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide.
public static func standardOutput(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler {
StreamLogHandler(label: label, stream: StdioOutputStream.stdout, metadataProvider: metadataProvider)
}
/// Creates a stream log handler that directs its output to STDERR.
public static func standardError(label: String) -> StreamLogHandler {
StreamLogHandler(
label: label,
stream: StdioOutputStream.stderr,
metadataProvider: LoggingSystem.metadataProvider
)
}
/// Creates a stream log handler that directs its output to STDERR using the metadata provider you provide.
public static func standardError(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler {
StreamLogHandler(label: label, stream: StdioOutputStream.stderr, metadataProvider: metadataProvider)
}
private let stream: any _SendableTextOutputStream
private let label: String
/// Get the log level configured for this `Logger`.
///
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
/// > It is acceptable for logging backends to have some form of global log level override
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
/// > certain cases have no effect.
public var logLevel: Logger.Level = .info
/// The metadata provider.
public var metadataProvider: Logger.MetadataProvider?
private var prettyMetadata: String?
/// Get or set the entire metadata storage as a dictionary.
public var metadata = Logger.Metadata() {
didSet {
self.prettyMetadata = self.prettify(self.metadata)
}
}
/// Add, change, or remove a logging metadata item.
///
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
get {
self.metadata[metadataKey]
}
set {
self.metadata[metadataKey] = newValue
}
}
// internal for testing only
internal init(label: String, stream: any _SendableTextOutputStream) {
self.init(label: label, stream: stream, metadataProvider: LoggingSystem.metadataProvider)
}
// internal for testing only
internal init(label: String, stream: any _SendableTextOutputStream, metadataProvider: Logger.MetadataProvider?) {
self.label = label
self.stream = stream
self.metadataProvider = metadataProvider
}
/// Log a message using the log level and source that you provide.
///
/// - parameters:
/// - event: The log event containing the level, message, metadata, and source location.
public func log(event: LogEvent) {
let effectiveMetadata = StreamLogHandler.prepareMetadata(
base: self.metadata,
provider: self.metadataProvider,
explicit: event.metadata,
error: event.error,
)
let prettyMetadata: String?
if let effectiveMetadata = effectiveMetadata {
prettyMetadata = self.prettify(effectiveMetadata)
} else {
prettyMetadata = self.prettyMetadata
}
var stream = self.stream
stream.write(
"\(self.timestamp()) \(event.level)\(self.label.isEmpty ? "" : " ")\(self.label):\(prettyMetadata.map { " \($0)" } ?? "") [\(event.source)] \(event.message)\n"
)
}
@available(*, deprecated, renamed: "log(event:)")
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
self.log(
event: LogEvent(
level: level,
message: message,
metadata: metadata,
source: source,
file: file,
function: function,
line: line
)
)
}
internal static func prepareMetadata(
base: Logger.Metadata,
provider: Logger.MetadataProvider?,
explicit: Logger.Metadata?,
error: (any Error)?,
) -> Logger.Metadata? {
var metadata = base
let provided = provider?.get() ?? [:]
guard !provided.isEmpty || !((explicit ?? [:]).isEmpty) || error != nil else {
// all per-log-statement values are empty
return nil
}
if !provided.isEmpty {
metadata.merge(provided, uniquingKeysWith: { _, provided in provided })
}
if let explicit = explicit, !explicit.isEmpty {
metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
}
if let error {
metadata["error.message"] = "\(error)"
metadata["error.type"] = "\(String(reflecting: type(of: error)))"
}
return metadata
}
private func prettify(_ metadata: Logger.Metadata) -> String? {
if metadata.isEmpty {
return nil
} else {
return metadata.lazy.sorted(by: { $0.key < $1.key }).map { "\($0)=\($1)" }.joined(separator: " ")
}
}
private func timestamp() -> String {
var buffer = [Int8](repeating: 0, count: 255)
#if os(Windows)
var timestamp = __time64_t()
_ = _time64(&timestamp)
var localTime = tm()
_ = _localtime64_s(&localTime, &timestamp)
_ = strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S%z", &localTime)
#else
var timestamp = time(nil)
guard let localTime = localtime(&timestamp) else {
return "<unknown>"
}
strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S%z", localTime)
#endif
return buffer.withUnsafeBufferPointer {
$0.withMemoryRebound(to: CChar.self) {
String(cString: $0.baseAddress!)
}
}
}
}
/// A wrapper to facilitate `print`-ing to stderr and stdio that
/// ensures access to the underlying `FILE` is locked to prevent
/// cross-thread interleaving of output.
internal struct StdioOutputStream: TextOutputStream, @unchecked Sendable {
internal let flushMode: FlushMode
private let _writeBytes: (UnsafeBufferPointer<UInt8>) -> Void
private let _flush: () -> Void
// Using a generic initializer lets Swift infer the concrete file-pointer type
// at each call site from the values passed. This avoids a CFilePointer typealias
// that cannot vary by Android API level (API 23 exposes FILE as
// UnsafeMutablePointer<FILE>; API 24+ makes it OpaquePointer).
internal init<F>(
file: F,
flushMode: FlushMode,
lock: ((F) -> Void)?,
unlock: ((F) -> Void)?,
write: @escaping (UnsafeRawPointer, Int, Int, F) -> Int,
flush: @escaping (F) -> Int32
) {
self.flushMode = flushMode
self._writeBytes = { bytes in
lock?(file)
defer { unlock?(file) }
if let base = bytes.baseAddress, bytes.count > 0 {
_ = write(base, 1, bytes.count, file)
}
}
self._flush = { _ = flush(file) }
}
internal func write(_ string: String) {
self.contiguousUTF8(string).withContiguousStorageIfAvailable { utf8Bytes in
self._writeBytes(utf8Bytes)
if case .always = self.flushMode {
self.flush()
}
}!
}
/// Flush the underlying stream.
internal func flush() {
self._flush()
}
internal func contiguousUTF8(_ string: String) -> String.UTF8View {
var contiguousString = string
contiguousString.makeContiguousUTF8()
return contiguousString.utf8
}
internal static let stderr: StdioOutputStream = {
#if canImport(Darwin)
return StdioOutputStream(
file: Darwin.stderr,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif os(Windows)
return StdioOutputStream(
file: CRT.stderr,
flushMode: .always,
lock: _lock_file,
unlock: _unlock_file,
write: fwrite,
flush: fflush
)
#elseif canImport(Glibc)
#if os(FreeBSD) || os(OpenBSD)
return StdioOutputStream(
file: Glibc.stderr,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#else
return StdioOutputStream(
file: Glibc.stderr!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#endif
#elseif canImport(Android)
return StdioOutputStream(
file: Android.stderr,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(Musl)
return StdioOutputStream(
file: Musl.stderr!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(WASILibc)
// no file locking on WASI
return StdioOutputStream(
file: WASILibc.stderr!,
flushMode: .always,
lock: nil,
unlock: nil,
write: fwrite,
flush: fflush
)
#else
#error("Unsupported runtime")
#endif
}()
internal static let stdout: StdioOutputStream = {
#if canImport(Darwin)
return StdioOutputStream(
file: Darwin.stdout,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif os(Windows)
return StdioOutputStream(
file: CRT.stdout,
flushMode: .always,
lock: _lock_file,
unlock: _unlock_file,
write: fwrite,
flush: fflush
)
#elseif canImport(Glibc)
#if os(FreeBSD) || os(OpenBSD)
return StdioOutputStream(
file: Glibc.stdout,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#else
return StdioOutputStream(
file: Glibc.stdout!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#endif
#elseif canImport(Android)
return StdioOutputStream(
file: Android.stdout,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(Musl)
return StdioOutputStream(
file: Musl.stdout!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(WASILibc)
// no file locking on WASI
return StdioOutputStream(
file: WASILibc.stdout!,
flushMode: .always,
lock: nil,
unlock: nil,
write: fwrite,
flush: fflush
)
#else
#error("Unsupported runtime")
#endif
}()
/// Defines the flushing strategy for the underlying stream.
internal enum FlushMode {
case undefined
case always
}
}
@@ -0,0 +1,80 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// A no-operation log handler, used when no logging is required
public struct SwiftLogNoOpLogHandler: LogHandler {
/// Creates a no-op log handler.
public init() {}
/// Creates a no-op log handler.
public init(_: String) {}
/// A proxy that discards every log event it receives.
///
/// - parameters:
/// - event: The log event to discard.
@inlinable public func log(event: LogEvent) {}
@available(*, deprecated, renamed: "log(event:)")
@inlinable public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {}
@available(*, deprecated, renamed: "log(event:)")
@inlinable public func log(
level: Logging.Logger.Level,
message: Logging.Logger.Message,
metadata: Logging.Logger.Metadata?,
file: String,
function: String,
line: UInt
) {}
/// Add, change, or remove a logging metadata item.
///
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
@inlinable public subscript(metadataKey _: String) -> Logger.Metadata.Value? {
get {
nil
}
set {}
}
/// Get or set the entire metadata storage as a dictionary.
@inlinable public var metadata: Logger.Metadata {
get {
[:]
}
set {}
}
/// Get or set the log level configured for this `Logger`.
///
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
/// > It is acceptable for logging backends to have some form of global log level override
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
/// > certain cases have no effect.
@inlinable public var logLevel: Logger.Level {
get {
.critical
}
set {}
}
}
+4 -7
View File
@@ -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
+1 -8
View File
@@ -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) {
/// // [...]
/// }
///
+553
View File
@@ -0,0 +1,553 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
// MARK: - MetadataValueAttributes storage
extension Logger {
/// Attributes that can be associated with metadata values.
public struct MetadataValueAttributes: Sendable {
/// A protocol for defining custom metadata attributes.
///
/// Conform to this protocol to define a custom attribute that can be stored in
/// ``MetadataValueAttributes``. Each conforming type acts as both the key (identified
/// by its metatype) and the value.
///
/// This protocol is designed for **small, fixed-vocabulary attributes**.
/// Each attribute value is stored as an `Int64` raw value, so attributes occupy minimal
/// space (one inline slot without heap allocation for the common single-attribute case).
///
/// ## Examples
///
/// ```swift
/// public enum Priority: Int64, Sendable, Logger.MetadataValueAttributes.Attribute {
/// case low = 1
/// case high = 2
/// }
/// ```
///
/// ```swift
/// public struct Priority: Sendable, Hashable, Logger.MetadataValueAttributes.Attribute {
/// public let rawValue: Int64
/// public init(rawValue: Int64) {
/// self.rawValue = rawValue
/// }
/// public static let low = Priority(rawValue: 1)
/// public static let high = Priority(rawValue: 2)
/// }
/// ```
public protocol Attribute: Sendable, RawRepresentable where RawValue == Int64 {}
/// An entry in the metadata attributes storage.
@usableFromInline
internal struct Entry: Sendable, Equatable {
@usableFromInline
internal var key: ObjectIdentifier
@usableFromInline
internal var value: Int64
@inlinable
internal init(key: ObjectIdentifier, value: Int64) {
self.key = key
self.value = value
}
}
@usableFromInline
internal var _inline: Entry?
@usableFromInline
internal var _overflow: [Entry]?
/// Create empty metadata value attributes.
@inlinable
public init() {}
/// Get or set a custom attribute by its type.
///
/// - Parameter attribute: The metatype of the attribute to access.
/// - Returns: The attribute value, or `nil` if not set.
@inlinable
public subscript<Attr: Attribute>(attribute: Attr.Type) -> Attr? {
get {
let id = ObjectIdentifier(Attr.self)
if let inline = self._inline, inline.key == id { return Attr(rawValue: inline.value) }
if let overflow = self._overflow {
for entry in overflow {
if entry.key == id { return Attr(rawValue: entry.value) }
}
}
return nil
}
set {
let id = ObjectIdentifier(Attr.self)
if let v = newValue {
self._upsert(key: id, value: v.rawValue)
} else {
self._remove(key: id)
}
}
}
@inlinable
internal mutating func _upsert(key id: ObjectIdentifier, value: Int64) {
let entry = Entry(key: id, value: value)
if let inline = self._inline, inline.key == id {
self._inline = entry
return
}
if let idx = self._overflow?.firstIndex(where: { $0.key == id }) {
self._overflow?[idx] = entry
return
}
if self._inline == nil {
self._inline = entry
} else {
if self._overflow == nil {
self._overflow = [entry]
} else {
self._overflow?.append(entry)
}
}
}
@inlinable
internal mutating func _remove(key id: ObjectIdentifier) {
if let inline = self._inline, inline.key == id {
if var overflow = self._overflow, !overflow.isEmpty {
self._inline = overflow.removeLast()
self._overflow = overflow.isEmpty ? nil : overflow
} else {
self._inline = nil
}
return
}
if let idx = self._overflow?.firstIndex(where: { $0.key == id }) {
self._overflow?.remove(at: idx)
if self._overflow?.isEmpty == true {
self._overflow = nil
}
}
}
@inlinable
internal mutating func _merge(from other: Self) {
if let inline = other._inline {
self._upsert(key: inline.key, value: inline.value)
}
if let overflow = other._overflow {
for entry in overflow {
self._upsert(key: entry.key, value: entry.value)
}
}
}
/// Compare all entries as an unordered set.
///
/// The inline slot and overflow array may hold the same logical entries in different
/// positions depending on insertion order. This method checks set equality by
/// verifying that every entry on one side exists on the other. O(n²) but n is
/// typically 1–2.
@inlinable
internal func _isEqual(to other: Self) -> Bool {
let lhsOverflowCount = self._overflow?.count ?? 0
let rhsOverflowCount = other._overflow?.count ?? 0
let lhsCount = (self._inline != nil ? 1 : 0) + lhsOverflowCount
let rhsCount = (other._inline != nil ? 1 : 0) + rhsOverflowCount
guard lhsCount == rhsCount else { return false }
guard lhsCount > 0 else { return true }
// Check that every lhs entry exists in rhs.
// With matching counts, this is sufficient for set equality.
if let inline = self._inline {
if !other._contains(inline) { return false }
}
if let overflow = self._overflow {
for entry in overflow {
if !other._contains(entry) { return false }
}
}
return true
}
@inlinable
internal func _contains(_ entry: Entry) -> Bool {
if self._inline == entry { return true }
if let overflow = self._overflow {
for e in overflow {
if e == entry { return true }
}
}
return false
}
}
}
extension Logger.MetadataValueAttributes: Equatable {
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs._isEqual(to: rhs)
}
}
extension Logger.MetadataValueAttributes: ExpressibleByArrayLiteral {
/// Creates metadata value attributes from an array literal of attribute values.
///
/// Each element is any ``Attribute`` conforming value. The key is
/// inferred from the concrete type of the value.
///
/// ```swift
/// let attrs: Logger.MetadataValueAttributes = [Sensitivity.sensitive, ValueType.int64]
/// ```
/// Each element goes through existential boxing to extract `type(of:)` and `.rawValue`.
/// This is acceptable for a literal initializer but should not be used in hot paths;
/// prefer the type-safe subscript (`attrs[SomeAttribute.self] = value`) for performance-sensitive code.
@inlinable
public init(arrayLiteral elements: any Logger.MetadataValueAttributes.Attribute...) {
self.init()
for element in elements {
self._upsert(key: ObjectIdentifier(type(of: element)), value: element.rawValue)
}
}
}
// MARK: - AttributedStringCarrier
extension Logger {
/// Internal carrier that wraps a string with metadata attributes.
///
/// Produced by `MetadataValue.StringInterpolation` when any interpolation
/// segment specifies attributes, or by ``MetadataValue/attributed(_:attributes:)``.
/// This is the only type that carries attributes; the `.attributes` property on
/// `MetadataValue` checks for it with a concrete type comparison rather than a
/// protocol conformance lookup.
@usableFromInline
internal struct AttributedStringCarrier: CustomStringConvertible, Sendable {
@usableFromInline
internal let string: String
@usableFromInline
internal let metadataAttributes: Logger.MetadataValueAttributes
@usableFromInline
internal init(string: String, metadataAttributes: Logger.MetadataValueAttributes) {
self.string = string
self.metadataAttributes = metadataAttributes
}
@inlinable
internal var description: String { self.string }
}
}
// MARK: - MetadataValue attributes API
extension Logger.MetadataValue {
/// The attributes associated with this metadata value, if any.
///
/// **Getting:** When the value is a ``stringConvertible(_:)`` wrapping an
/// `AttributedStringCarrier`, returns that carrier's attributes.
/// For all other cases returns empty attributes.
///
/// **Setting:** Replaces the value with `.stringConvertible(AttributedStringCarrier(...))`
/// carrying the given attributes. For `.string` and `.stringConvertible` cases the string
/// representation is preserved. For `.dictionary` and `.array` cases the setter is a no-op.
///
/// Only handlers that inspect attributes pay the cost of the getter check.
@inlinable
public var attributes: Logger.MetadataValueAttributes {
get {
if case .stringConvertible(let box) = self,
let carrier = box as? Logger.AttributedStringCarrier
{
return carrier.metadataAttributes
}
return .init()
}
set {
switch self {
case .string(let s):
self = .stringConvertible(
Logger.AttributedStringCarrier(string: s, metadataAttributes: newValue)
)
case .stringConvertible(let box):
self = .stringConvertible(
Logger.AttributedStringCarrier(string: box.description, metadataAttributes: newValue)
)
case .dictionary, .array:
assertionFailure("Cannot set attributes on .dictionary or .array metadata values")
return
}
}
}
/// Creates an attributed metadata value from a string-convertible value and attributes.
///
/// This is a convenience factory that behaves like an additional enum case, producing
/// a `.stringConvertible(AttributedStringCarrier(...))` value without string interpolation:
///
/// ```swift
/// let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
/// ```
@inlinable
public static func attributed(
_ value: some CustomStringConvertible & Sendable,
attributes: Logger.MetadataValueAttributes
) -> Self {
.stringConvertible(
Logger.AttributedStringCarrier(
string: String(describing: value),
metadataAttributes: attributes
)
)
}
}
// MARK: - Attributed string interpolation
// Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for
// https://bugs.swift.org/browse/SR-9687
extension Logger.MetadataValue: ExpressibleByStringInterpolation {
/// Custom string interpolation that optionally captures metadata attributes.
///
/// When no attributes are specified, produces `.string(...)` — identical to the
/// default `DefaultStringInterpolation` behavior. When any interpolation segment
/// specifies attributes (via the `attributes:` parameter), the result is
/// `.stringConvertible(AttributedStringCarrier(...))` carrying both the string
/// and the accumulated attributes.
///
/// Attribute packages (like `LoggingAttributes`) can add overloads with
/// domain-specific parameters (e.g. `sensitivity:`) that call through to
/// `appendInterpolation(_:attributes:)`.
public struct StringInterpolation: StringInterpolationProtocol, Sendable {
@usableFromInline
internal var output: String = ""
@usableFromInline
internal var attributes: Logger.MetadataValueAttributes = .init()
@usableFromInline
internal var hasAttributes: Bool = false
@inlinable
public init(literalCapacity: Int, interpolationCount: Int) {
self.output.reserveCapacity(literalCapacity + interpolationCount * 2)
}
@inlinable
public mutating func appendLiteral(_ literal: String) {
self.output.append(literal)
}
@inlinable
internal mutating func _mergeAttributes(_ attributes: Logger.MetadataValueAttributes) {
if self.hasAttributes {
self.attributes._merge(from: attributes)
} else {
self.attributes = attributes
}
self.hasAttributes = true
}
// MARK: Plain interpolation
// The four overloads below mirror `DefaultStringInterpolation`'s shape.
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
_ value: T
) {
value.write(to: &self.output)
}
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable>(
_ value: T
) {
value.write(to: &self.output)
}
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible>(
_ value: T
) {
self.output.append(value.description)
}
@inlinable
public mutating func appendInterpolation<T>(
_ value: T
) {
self.output.append(String(describing: value))
}
// MARK: Optional interpolation with a default
// The four overloads below mirror `DefaultStringInterpolation`'s `default:`
// shape so that `"\(optional, default: "none")"` keeps working when the
// literal is inferred as a `Logger.MetadataValue`.
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
_ value: T?,
default defaultValue: @autoclosure () -> some StringProtocol
) {
if let value {
self.appendInterpolation(value)
} else {
self.output.append(String(defaultValue()))
}
}
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable>(
_ value: T?,
default defaultValue: @autoclosure () -> some StringProtocol
) {
if let value {
self.appendInterpolation(value)
} else {
self.output.append(String(defaultValue()))
}
}
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible>(
_ value: T?,
default defaultValue: @autoclosure () -> some StringProtocol
) {
if let value {
self.appendInterpolation(value)
} else {
self.output.append(String(defaultValue()))
}
}
@inlinable
public mutating func appendInterpolation<T>(
_ value: T?,
default defaultValue: @autoclosure () -> some StringProtocol
) {
if let value {
self.appendInterpolation(value)
} else {
self.output.append(String(defaultValue()))
}
}
// MARK: Interpolation with a custom attributes closure
//
// ```swift
// "\(userId, attributes: { $0[MyAttribute.self] = .flagged })"
// ```
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
_ value: T,
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
) {
value.write(to: &self.output)
attributes(&self.attributes)
self.hasAttributes = true
}
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable>(
_ value: T,
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
) {
value.write(to: &self.output)
attributes(&self.attributes)
self.hasAttributes = true
}
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible>(
_ value: T,
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
) {
self.output.append(value.description)
attributes(&self.attributes)
self.hasAttributes = true
}
@inlinable
public mutating func appendInterpolation<T>(
_ value: T,
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
) {
self.output.append(String(describing: value))
attributes(&self.attributes)
self.hasAttributes = true
}
// MARK: Interpolation with pre-built attributes
//
// ```swift
// "\(userId, attributes: [Sensitivity.sensitive])"
// ```
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable & CustomStringConvertible>(
_ value: T,
attributes: Logger.MetadataValueAttributes
) {
value.write(to: &self.output)
self._mergeAttributes(attributes)
}
@inlinable
public mutating func appendInterpolation<T: TextOutputStreamable>(
_ value: T,
attributes: Logger.MetadataValueAttributes
) {
value.write(to: &self.output)
self._mergeAttributes(attributes)
}
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible>(
_ value: T,
attributes: Logger.MetadataValueAttributes
) {
self.output.append(value.description)
self._mergeAttributes(attributes)
}
@inlinable
public mutating func appendInterpolation<T>(
_ value: T,
attributes: Logger.MetadataValueAttributes
) {
self.output.append(String(describing: value))
self._mergeAttributes(attributes)
}
}
/// Creates a metadata value from string interpolation.
///
/// If any interpolation segment specified attributes, the result is
/// `.stringConvertible(AttributedStringCarrier(...))`. Otherwise, `.string(...)`.
@inlinable
public init(stringInterpolation: StringInterpolation) {
if stringInterpolation.hasAttributes {
self = .stringConvertible(
Logger.AttributedStringCarrier(
string: stringInterpolation.output,
metadataAttributes: stringInterpolation.attributes
)
)
} else {
self = .string(stringInterpolation.output)
}
}
}
@@ -12,22 +12,6 @@
//
//===----------------------------------------------------------------------===//
#if canImport(Darwin)
import Darwin
#elseif os(Windows)
import CRT
#elseif canImport(Glibc)
@preconcurrency import Glibc
#elseif canImport(Android)
@preconcurrency import Android
#elseif canImport(Musl)
import Musl
#elseif canImport(WASILibc)
import WASILibc
#else
#error("Unsupported runtime")
#endif
/// A Logger emits log messages using methods that correspond to a log level.
///
/// `Logger` is a value type with respect to the ``Logger/Level`` and the ``Metadata`` (as well as the immutable `label`
@@ -267,6 +251,7 @@ extension Logger {
/// - parameters:
/// - level: The severity level of the `message`.
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` related to the event.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
@@ -329,9 +314,23 @@ extension Logger {
function: String = #function,
line: UInt = #line
) {
self.log(level: level, message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
self.log(
level: level,
message(),
error: nil,
metadata: metadata(),
source: nil,
file: file,
function: function,
line: line
)
}
/// Log a message using the log level and attributed metadata that you provide.
///
/// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library
/// logs the message, otherwise nothing will happen.
///
/// Add, change, or remove a logging metadata item.
///
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
@@ -341,7 +340,9 @@ extension Logger {
self.handler[metadataKey: metadataKey]
}
set {
#if !MaxLogLevelNone
self.handler[metadataKey: metadataKey] = newValue
#endif
}
}
@@ -357,7 +358,9 @@ extension Logger {
self.handler.logLevel
}
set {
#if !MaxLogLevelNone
self.handler.logLevel = newValue
#endif
}
}
}
@@ -1078,192 +1081,6 @@ extension Logger {
}
}
/// The logging system is a global facility where you can configure the default logging backend implementation.
///
/// `LoggingSystem` is set up just once in a given program to set up the desired logging backend implementation.
/// The default behavior, if you don't define otherwise, sets the ``LogHandler`` to use a ``StreamLogHandler`` that presents its output to `STDOUT`.
///
/// You can configure that handler to present the output to `STDERR` instead using the following code:
///
/// ```swift
/// LoggingSystem.bootstrap(StreamLogHandler.standardError)
/// ```
///
/// The default (``StreamLogHandler``) is intended to be a convenience.
/// For production applications, implement the ``LogHandler`` protocol directly, or use a community-maintained backend.
public enum LoggingSystem: Sendable {
private static let _factory = FactoryBox(
{ label, _ in StreamLogHandler.standardError(label: label) },
violationErrorMesage: "logging system can only be initialized once per process."
)
private static let _metadataProviderFactory = MetadataProviderBox(
nil,
violationErrorMesage: "logging system can only be initialized once per process."
)
#if DEBUG
private static let _warnOnceBox: WarnOnceBox = WarnOnceBox()
#endif
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
///
/// > Warning:
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
/// > lead to undefined behavior, most likely a crash.
///
/// - parameters:
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
@preconcurrency
public static func bootstrap(_ factory: @escaping @Sendable (String) -> any LogHandler) {
self._factory.replace(
{ label, _ in
factory(label)
},
validate: true
)
}
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
///
/// > Warning:
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
/// > lead to undefined behavior, most likely a crash.
///
/// - parameters:
/// - metadataProvider: The `MetadataProvider` used to inject runtime-generated metadata from the execution context.
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
@preconcurrency
public static func bootstrap(
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
metadataProvider: Logger.MetadataProvider?
) {
self._metadataProviderFactory.replace(metadataProvider, validate: true)
self._factory.replace(factory, validate: true)
}
// for our testing we want to allow multiple bootstrapping
internal static func bootstrapInternal(_ factory: @escaping @Sendable (String) -> any LogHandler) {
self._metadataProviderFactory.replace(nil, validate: false)
self._factory.replace(
{ label, _ in
factory(label)
},
validate: false
)
}
// for our testing we want to allow multiple bootstrapping
internal static func bootstrapInternal(
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
metadataProvider: Logger.MetadataProvider?
) {
self._metadataProviderFactory.replace(metadataProvider, validate: false)
self._factory.replace(factory, validate: false)
}
fileprivate static var factory: (String, Logger.MetadataProvider?) -> any LogHandler {
{ label, metadataProvider in
self._factory.underlying(label, metadataProvider)
}
}
/// System wide ``Logger/MetadataProvider`` that was configured during the logging system's `bootstrap`.
///
/// When creating a ``Logger`` using the plain ``Logger/init(label:)`` initializer, this metadata provider
/// will be provided to it.
///
/// When using custom log handler factories, make sure to provide the bootstrapped metadata provider to them,
/// or the metadata will not be filled in automatically using the provider on log-sites. While using a custom
/// factory to avoid using the bootstrapped metadata provider may sometimes be useful, usually it will lead to
/// un-expected behavior, so make sure to always propagate it to your handlers.
public static var metadataProvider: Logger.MetadataProvider? {
self._metadataProviderFactory.underlying
}
#if DEBUG
/// Used to warn only once about a specific ``LogHandler`` type when it does not support ``Logger/MetadataProvider``,
/// but an attempt was made to set a metadata provider on such handler. In order to avoid flooding the system with
/// warnings such warning is only emitted in debug mode, and even then at-most once for a handler type.
internal static func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(
_ type: Handler.Type
) -> Bool {
self._warnOnceBox.warnOnceLogHandlerNotSupportedMetadataProvider(type: type)
}
#endif
/// Protects an object such that it can only be accessed through a Reader-Writer lock.
final class RWLockedValueBox<Value: Sendable>: @unchecked Sendable {
private let lock = ReadWriteLock()
private var storage: Value
init(initialValue: Value) {
self.storage = initialValue
}
func withReadLock<Result>(_ operation: (Value) -> Result) -> Result {
self.lock.withReaderLock {
operation(self.storage)
}
}
func withWriteLock<Result>(_ operation: (inout Value) -> Result) -> Result {
self.lock.withWriterLock {
operation(&self.storage)
}
}
}
/// Protects an object by applying the constraints that it can only be accessed through a Reader-Writer lock
/// and can only be updated once from the initial value given.
private struct ReplaceOnceBox<BoxedType: Sendable> {
private struct ReplaceOnce: Sendable {
private var initialized = false
private var _underlying: BoxedType
private let violationErrorMessage: String
mutating func replaceUnderlying(_ underlying: BoxedType, validate: Bool) {
precondition(!validate || !self.initialized, self.violationErrorMessage)
self._underlying = underlying
self.initialized = true
}
var underlying: BoxedType {
self._underlying
}
init(underlying: BoxedType, violationErrorMessage: String) {
self._underlying = underlying
self.violationErrorMessage = violationErrorMessage
}
}
private let storage: RWLockedValueBox<ReplaceOnce>
init(_ underlying: BoxedType, violationErrorMesage: String) {
self.storage = .init(
initialValue: ReplaceOnce(
underlying: underlying,
violationErrorMessage: violationErrorMesage
)
)
}
func replace(_ newUnderlying: BoxedType, validate: Bool) {
self.storage.withWriteLock { $0.replaceUnderlying(newUnderlying, validate: validate) }
}
var underlying: BoxedType {
self.storage.withReadLock { $0.underlying }
}
}
private typealias FactoryBox = ReplaceOnceBox<
@Sendable (_ label: String, _ provider: Logger.MetadataProvider?) -> any LogHandler
>
private typealias MetadataProviderBox = ReplaceOnceBox<Logger.MetadataProvider?>
}
extension Logger {
/// The type of the metadata storage.
///
@@ -1359,6 +1176,9 @@ extension Logger {
/// `.array([.string("foo"), .string("bar \(buz)")])`, instead use the more natural `["foo", "bar \(buz)"]`.
case array([Metadata.Value])
}
}
extension Logger {
/// The log level.
///
@@ -1551,687 +1371,6 @@ extension Logger {
}
}
/// A pseudo log handler that sends messages to multiple other log handlers.
///
/// ### Effective Logger.Level
///
/// When first initialized, the multiplex log handlers' log level is automatically set to the minimum of all the
/// provided log handlers.
/// This ensures that each of the handlers are able to log at their appropriate level
/// any log events they might be interested in.
///
/// Example:
/// If log handler `A` is logging at `.debug` level, and log handler `B` is logging at `.info` level, the log level of the constructed
/// `MultiplexLogHandler([A, B])` is set to `.debug`. This means that this handler will operate on debug messages,
/// while only logged by the underlying `A` log handler (since `B`'s log level is `.info`
/// and thus it would not actually log that log message).
///
/// If the log level is _set_ on a `Logger` backed by an `MultiplexLogHandler` the log level applies to *all*
/// underlying log handlers, allowing a logger to still select at what level it wants to log regardless of if the underlying
/// handler is a multiplex or a normal one. If for some reason one might want to not allow changing a log level of a specific
/// handler passed into the multiplex log handler, this is possible by wrapping it in a handler which ignores any log level changes.
///
/// ### Effective Logger.Metadata
///
/// Since a `MultiplexLogHandler` is a combination of multiple log handlers, the handling of metadata can be non-obvious.
/// For example, the underlying log handlers may have metadata of their own set before they are used to initialize the multiplex log handler.
///
/// The multiplex log handler acts purely as proxy and does not make any changes to underlying handler metadata other than
/// proxying writes that users made on a `Logger` instance backed by this handler.
///
/// Setting metadata is always proxied through to _all_ underlying handlers, meaning that if a modification like
/// `logger[metadataKey: "x"] = "y"` is made, all the underlying log handlers used to create the multiplex handler
/// observe this change.
///
/// Reading metadata from the multiplex log handler MAY need to pick one of conflicting values if the underlying log handlers
/// were previously initiated with metadata before passing them into the multiplex handler. The multiplex handler uses
/// the order in which the handlers were passed in during its initialization as a priority indicator - the first handler's
/// values are more important than the next handlers values, etc.
///
/// Example:
/// If the multiplex log handler was initiated with two handlers like this: `MultiplexLogHandler([handler1, handler2])`.
/// The handlers each have some already set metadata: `handler1` has metadata values for keys `one` and `all`, and `handler2`
/// has values for keys `two` and `all`.
///
/// A query through the multiplex log handler the key `one` naturally returns `handler1`'s value, and a query for `two`
/// naturally returns `handler2`'s value.
/// Querying for the key `all` will return `handler1`'s value, as that handler has a high priority,
/// as indicated by its earlier position in the initialization, than the second handler.
/// The same rule applies when querying for the `metadata` property of the multiplex log handler; it constructs `Metadata` uniquing values.
public struct MultiplexLogHandler: LogHandler {
private var handlers: [any LogHandler]
private var effectiveLogLevel: Logger.Level
/// This metadata provider runs after all metadata providers of the multiplexed handlers.
private var _metadataProvider: Logger.MetadataProvider?
/// Create a multiplex log handler.
///
/// - parameters:
/// - handlers: An array of `LogHandler`s, each of which will receive the log messages sent to this `Logger`.
/// The array must not be empty.
public init(_ handlers: [any LogHandler]) {
assert(!handlers.isEmpty, "MultiplexLogHandler.handlers MUST NOT be empty")
self.handlers = handlers
self.effectiveLogLevel = handlers.map { $0.logLevel }.min() ?? .trace
}
/// Create a multiplex log handler with the metadata provider you provide.
/// - Parameters:
/// - handlers: An array of `LogHandler`s, each of which will receive every log message sent to this `Logger`.
/// The array must not be empty.
/// - metadataProvider: The metadata provider that adds metadata to log messages for this handler.
public init(_ handlers: [any LogHandler], metadataProvider: Logger.MetadataProvider?) {
assert(!handlers.isEmpty, "MultiplexLogHandler.handlers MUST NOT be empty")
self.handlers = handlers
self.effectiveLogLevel = handlers.map { $0.logLevel }.min() ?? .trace
self._metadataProvider = metadataProvider
}
/// Get or set the log level configured for this `Logger`.
///
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
/// > It is acceptable for logging backends to have some form of global log level override
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
/// > certain cases have no effect.
public var logLevel: Logger.Level {
get {
self.effectiveLogLevel
}
set {
self.mutatingForEachHandler { $0.logLevel = newValue }
self.effectiveLogLevel = newValue
}
}
/// The metadata provider.
public var metadataProvider: Logger.MetadataProvider? {
get {
if self.handlers.count == 1 {
if let innerHandler = self.handlers.first?.metadataProvider {
if let multiplexHandlerProvider = self._metadataProvider {
return .multiplex([innerHandler, multiplexHandlerProvider])
} else {
return innerHandler
}
} else if let multiplexHandlerProvider = self._metadataProvider {
return multiplexHandlerProvider
} else {
return nil
}
} else {
var providers: [Logger.MetadataProvider] = []
let additionalMetadataProviderCount = (self._metadataProvider != nil ? 1 : 0)
providers.reserveCapacity(self.handlers.count + additionalMetadataProviderCount)
for handler in self.handlers {
if let provider = handler.metadataProvider {
providers.append(provider)
}
}
if let multiplexHandlerProvider = self._metadataProvider {
providers.append(multiplexHandlerProvider)
}
guard !providers.isEmpty else {
return nil
}
return .multiplex(providers)
}
}
set {
self.mutatingForEachHandler { $0.metadataProvider = newValue }
}
}
/// Log a message using the log level and source that you provide.
///
/// - parameters:
/// - event: The log event containing the level, message, metadata, and source location.
public func log(event: LogEvent) {
for handler in self.handlers where handler.logLevel <= event.level {
handler.log(event: event)
}
}
@available(*, deprecated, renamed: "log(event:)")
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
self.log(
event: LogEvent(
level: level,
message: message,
metadata: metadata,
source: source,
file: file,
function: function,
line: line
)
)
}
/// Get or set the entire metadata storage as a dictionary.
public var metadata: Logger.Metadata {
get {
var effective: Logger.Metadata = [:]
// as a rough estimate we assume that the underlying handlers have a similar metadata count,
// and we use the first one's current count to estimate how big of a dictionary we need to allocate:
// !-safe, we always have at least one handler
effective.reserveCapacity(self.handlers.first!.metadata.count)
for handler in self.handlers {
effective.merge(handler.metadata, uniquingKeysWith: { _, handlerMetadata in handlerMetadata })
if let provider = handler.metadataProvider {
effective.merge(provider.get(), uniquingKeysWith: { _, provided in provided })
}
}
if let provider = self._metadataProvider {
effective.merge(provider.get(), uniquingKeysWith: { _, provided in provided })
}
return effective
}
set {
self.mutatingForEachHandler { $0.metadata = newValue }
}
}
/// Add, change, or remove a logging metadata item.
///
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
public subscript(metadataKey metadataKey: Logger.Metadata.Key) -> Logger.Metadata.Value? {
get {
for handler in self.handlers {
if let value = handler[metadataKey: metadataKey] {
return value
}
}
return nil
}
set {
self.mutatingForEachHandler { $0[metadataKey: metadataKey] = newValue }
}
}
private mutating func mutatingForEachHandler(_ mutator: (inout any LogHandler) -> Void) {
for index in self.handlers.indices {
mutator(&self.handlers[index])
}
}
}
/// A wrapper to facilitate `print`-ing to stderr and stdio that
/// ensures access to the underlying `FILE` is locked to prevent
/// cross-thread interleaving of output.
internal struct StdioOutputStream: TextOutputStream, @unchecked Sendable {
internal let flushMode: FlushMode
private let _writeBytes: (UnsafeBufferPointer<UInt8>) -> Void
private let _flush: () -> Void
// Using a generic initializer lets Swift infer the concrete file-pointer type
// at each call site from the values passed. This avoids a CFilePointer typealias
// that cannot vary by Android API level (API 23 exposes FILE as
// UnsafeMutablePointer<FILE>; API 24+ makes it OpaquePointer).
internal init<F>(
file: F,
flushMode: FlushMode,
lock: ((F) -> Void)?,
unlock: ((F) -> Void)?,
write: @escaping (UnsafeRawPointer, Int, Int, F) -> Int,
flush: @escaping (F) -> Int32
) {
self.flushMode = flushMode
self._writeBytes = { bytes in
lock?(file)
defer { unlock?(file) }
if let base = bytes.baseAddress, bytes.count > 0 {
_ = write(base, 1, bytes.count, file)
}
}
self._flush = { _ = flush(file) }
}
internal func write(_ string: String) {
self.contiguousUTF8(string).withContiguousStorageIfAvailable { utf8Bytes in
self._writeBytes(utf8Bytes)
if case .always = self.flushMode {
self.flush()
}
}!
}
/// Flush the underlying stream.
internal func flush() {
self._flush()
}
internal func contiguousUTF8(_ string: String) -> String.UTF8View {
var contiguousString = string
contiguousString.makeContiguousUTF8()
return contiguousString.utf8
}
internal static let stderr: StdioOutputStream = {
#if canImport(Darwin)
return StdioOutputStream(
file: Darwin.stderr,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif os(Windows)
return StdioOutputStream(
file: CRT.stderr,
flushMode: .always,
lock: _lock_file,
unlock: _unlock_file,
write: fwrite,
flush: fflush
)
#elseif canImport(Glibc)
#if os(FreeBSD) || os(OpenBSD)
return StdioOutputStream(
file: Glibc.stderr,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#else
return StdioOutputStream(
file: Glibc.stderr!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#endif
#elseif canImport(Android)
return StdioOutputStream(
file: Android.stderr,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(Musl)
return StdioOutputStream(
file: Musl.stderr!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(WASILibc)
// no file locking on WASI
return StdioOutputStream(
file: WASILibc.stderr!,
flushMode: .always,
lock: nil,
unlock: nil,
write: fwrite,
flush: fflush
)
#else
#error("Unsupported runtime")
#endif
}()
internal static let stdout: StdioOutputStream = {
#if canImport(Darwin)
return StdioOutputStream(
file: Darwin.stdout,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif os(Windows)
return StdioOutputStream(
file: CRT.stdout,
flushMode: .always,
lock: _lock_file,
unlock: _unlock_file,
write: fwrite,
flush: fflush
)
#elseif canImport(Glibc)
#if os(FreeBSD) || os(OpenBSD)
return StdioOutputStream(
file: Glibc.stdout,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#else
return StdioOutputStream(
file: Glibc.stdout!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#endif
#elseif canImport(Android)
return StdioOutputStream(
file: Android.stdout,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(Musl)
return StdioOutputStream(
file: Musl.stdout!,
flushMode: .always,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#elseif canImport(WASILibc)
// no file locking on WASI
return StdioOutputStream(
file: WASILibc.stdout!,
flushMode: .always,
lock: nil,
unlock: nil,
write: fwrite,
flush: fflush
)
#else
#error("Unsupported runtime")
#endif
}()
/// Defines the flushing strategy for the underlying stream.
internal enum FlushMode {
case undefined
case always
}
}
/// Stream log handler presents log messages to STDERR or STDOUT.
///
/// This is a simple implementation of `LogHandler` that directs
/// `Logger` output to either `stderr` or `stdout` via the factory methods.
///
/// Metadata is merged in the following order:
/// 1. Metadata set on the log handler itself is used as the base metadata.
/// 2. The handler's ``metadataProvider`` is invoked, overriding any existing keys.
/// 3. The per-log-statement metadata is merged, overriding any previously set keys.
public struct StreamLogHandler: LogHandler {
internal typealias _SendableTextOutputStream = TextOutputStream & Sendable
/// Creates a stream log handler that directs its output to STDOUT.
public static func standardOutput(label: String) -> StreamLogHandler {
StreamLogHandler(
label: label,
stream: StdioOutputStream.stdout,
metadataProvider: LoggingSystem.metadataProvider
)
}
/// Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide.
public static func standardOutput(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler {
StreamLogHandler(label: label, stream: StdioOutputStream.stdout, metadataProvider: metadataProvider)
}
/// Creates a stream log handler that directs its output to STDERR.
public static func standardError(label: String) -> StreamLogHandler {
StreamLogHandler(
label: label,
stream: StdioOutputStream.stderr,
metadataProvider: LoggingSystem.metadataProvider
)
}
/// Creates a stream log handler that directs its output to STDERR using the metadata provider you provide.
public static func standardError(label: String, metadataProvider: Logger.MetadataProvider?) -> StreamLogHandler {
StreamLogHandler(label: label, stream: StdioOutputStream.stderr, metadataProvider: metadataProvider)
}
private let stream: any _SendableTextOutputStream
private let label: String
/// Get the log level configured for this `Logger`.
///
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
/// > It is acceptable for logging backends to have some form of global log level override
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
/// > certain cases have no effect.
public var logLevel: Logger.Level = .info
/// The metadata provider.
public var metadataProvider: Logger.MetadataProvider?
private var prettyMetadata: String?
/// Get or set the entire metadata storage as a dictionary.
public var metadata = Logger.Metadata() {
didSet {
self.prettyMetadata = self.prettify(self.metadata)
}
}
/// Add, change, or remove a logging metadata item.
///
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
public subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
get {
self.metadata[metadataKey]
}
set {
self.metadata[metadataKey] = newValue
}
}
// internal for testing only
internal init(label: String, stream: any _SendableTextOutputStream) {
self.init(label: label, stream: stream, metadataProvider: LoggingSystem.metadataProvider)
}
// internal for testing only
internal init(label: String, stream: any _SendableTextOutputStream, metadataProvider: Logger.MetadataProvider?) {
self.label = label
self.stream = stream
self.metadataProvider = metadataProvider
}
/// Log a message using the log level and source that you provide.
///
/// - parameters:
/// - event: The log event containing the level, message, metadata, and source location.
public func log(event: LogEvent) {
let effectiveMetadata = StreamLogHandler.prepareMetadata(
base: self.metadata,
provider: self.metadataProvider,
explicit: event.metadata,
error: event.error,
)
let prettyMetadata: String?
if let effectiveMetadata = effectiveMetadata {
prettyMetadata = self.prettify(effectiveMetadata)
} else {
prettyMetadata = self.prettyMetadata
}
var stream = self.stream
stream.write(
"\(self.timestamp()) \(event.level)\(self.label.isEmpty ? "" : " ")\(self.label):\(prettyMetadata.map { " \($0)" } ?? "") [\(event.source)] \(event.message)\n"
)
}
@available(*, deprecated, renamed: "log(event:)")
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
self.log(
event: LogEvent(
level: level,
message: message,
metadata: metadata,
source: source,
file: file,
function: function,
line: line
)
)
}
internal static func prepareMetadata(
base: Logger.Metadata,
provider: Logger.MetadataProvider?,
explicit: Logger.Metadata?,
error: (any Error)?,
) -> Logger.Metadata? {
var metadata = base
let provided = provider?.get() ?? [:]
guard !provided.isEmpty || !((explicit ?? [:]).isEmpty) || error != nil else {
// all per-log-statement values are empty
return nil
}
if !provided.isEmpty {
metadata.merge(provided, uniquingKeysWith: { _, provided in provided })
}
if let explicit = explicit, !explicit.isEmpty {
metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
}
if let error {
metadata["error.message"] = "\(error)"
metadata["error.type"] = "\(String(reflecting: type(of: error)))"
}
return metadata
}
private func prettify(_ metadata: Logger.Metadata) -> String? {
if metadata.isEmpty {
return nil
} else {
return metadata.lazy.sorted(by: { $0.key < $1.key }).map { "\($0)=\($1)" }.joined(separator: " ")
}
}
private func timestamp() -> String {
var buffer = [Int8](repeating: 0, count: 255)
#if os(Windows)
var timestamp = __time64_t()
_ = _time64(&timestamp)
var localTime = tm()
_ = _localtime64_s(&localTime, &timestamp)
_ = strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S%z", &localTime)
#else
var timestamp = time(nil)
guard let localTime = localtime(&timestamp) else {
return "<unknown>"
}
strftime(&buffer, buffer.count, "%Y-%m-%dT%H:%M:%S%z", localTime)
#endif
return buffer.withUnsafeBufferPointer {
$0.withMemoryRebound(to: CChar.self) {
String(cString: $0.baseAddress!)
}
}
}
}
/// A no-operation log handler, used when no logging is required
public struct SwiftLogNoOpLogHandler: LogHandler {
/// Creates a no-op log handler.
public init() {}
/// Creates a no-op log handler.
public init(_: String) {}
/// A proxy that discards every log event it receives.
///
/// - parameters:
/// - event: The log event to discard.
@inlinable public func log(event: LogEvent) {}
@available(*, deprecated, renamed: "log(event:)")
@inlinable public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {}
@available(*, deprecated, renamed: "log(event:)")
@inlinable public func log(
level: Logging.Logger.Level,
message: Logging.Logger.Message,
metadata: Logging.Logger.Metadata?,
file: String,
function: String,
line: UInt
) {}
/// Add, change, or remove a logging metadata item.
///
/// > Note: Changing the logging metadata only affects the instance of the `Logger` where you change it.
@inlinable public subscript(metadataKey _: String) -> Logger.Metadata.Value? {
get {
nil
}
set {}
}
/// Get or set the entire metadata storage as a dictionary.
@inlinable public var metadata: Logger.Metadata {
get {
[:]
}
set {}
}
/// Get or set the log level configured for this `Logger`.
///
/// > Note: Changing the log level threshold for a logger only affects the instance of the `Logger` where you change it.
/// > It is acceptable for logging backends to have some form of global log level override
/// > that affects multiple or even all loggers. This means a change in `logLevel` to one `Logger` might in
/// > certain cases have no effect.
@inlinable public var logLevel: Logger.Level {
get {
.critical
}
set {}
}
}
extension Logger {
@inlinable
internal static func currentModule(filePath: String = #file) -> String {
@@ -2287,10 +1426,6 @@ extension Logger.MetadataValue: CustomStringConvertible {
}
}
// Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for
// https://bugs.swift.org/browse/SR-9687
extension Logger.MetadataValue: ExpressibleByStringInterpolation {}
// Extension has to be done on explicit type rather than Logger.Metadata.Value as workaround for
// https://bugs.swift.org/browse/SR-9686
extension Logger.MetadataValue: ExpressibleByDictionaryLiteral {
@@ -2319,27 +1454,10 @@ extension Logger.MetadataValue: ExpressibleByArrayLiteral {
}
}
// MARK: - Debug only warnings
#if DEBUG
/// Contains state to manage all kinds of "warn only once" warnings which the logging system may want to issue.
private final class WarnOnceBox: @unchecked Sendable {
private let lock: Lock = Lock()
private var warnOnceLogHandlerNotSupportedMetadataProviderPerType = Set<ObjectIdentifier>()
func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(type: Handler.Type) -> Bool {
self.lock.withLock {
let id = ObjectIdentifier(type)
let (inserted, _) = warnOnceLogHandlerNotSupportedMetadataProviderPerType.insert(id)
return inserted // warn about this handler type, it is the first time we encountered it
}
}
}
#endif
// MARK: - Sendable support helpers
extension Logger.MetadataValue: Sendable {}
extension Logger: Sendable {}
extension Logger.Level: Sendable {}
extension Logger.Message: Sendable {}
+217
View File
@@ -0,0 +1,217 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// The logging system is a global facility where you can configure the default logging backend implementation.
///
/// `LoggingSystem` is set up just once in a given program to set up the desired logging backend implementation.
/// The default behavior, if you don't define otherwise, sets the ``LogHandler`` to use a ``StreamLogHandler`` that presents its output to `STDOUT`.
///
/// You can configure that handler to present the output to `STDERR` instead using the following code:
///
/// ```swift
/// LoggingSystem.bootstrap(StreamLogHandler.standardError)
/// ```
///
/// The default (``StreamLogHandler``) is intended to be a convenience.
/// For production applications, implement the ``LogHandler`` protocol directly, or use a community-maintained backend.
public enum LoggingSystem: Sendable {
private static let _factory = FactoryBox(
{ label, _ in StreamLogHandler.standardError(label: label) },
violationErrorMesage: "logging system can only be initialized once per process."
)
private static let _metadataProviderFactory = MetadataProviderBox(
nil,
violationErrorMesage: "logging system can only be initialized once per process."
)
#if DEBUG
private static let _warnOnceBox: WarnOnceBox = WarnOnceBox()
#endif
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
///
/// > Warning:
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
/// > lead to undefined behavior, most likely a crash.
///
/// - parameters:
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
@preconcurrency
public static func bootstrap(_ factory: @escaping @Sendable (String) -> any LogHandler) {
self._factory.replace(
{ label, _ in
factory(label)
},
validate: true
)
}
/// A one-time configuration function that globally selects the implementation for your desired logging backend.
///
/// > Warning:
/// > `bootstrap` can be called at maximum once in any given program, calling it more than once will
/// > lead to undefined behavior, most likely a crash.
///
/// - parameters:
/// - metadataProvider: The `MetadataProvider` used to inject runtime-generated metadata from the execution context.
/// - factory: A closure that provides a ``Logger`` label identifier and produces an instance of the ``LogHandler``.
@preconcurrency
public static func bootstrap(
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
metadataProvider: Logger.MetadataProvider?
) {
self._metadataProviderFactory.replace(metadataProvider, validate: true)
self._factory.replace(factory, validate: true)
}
// for our testing we want to allow multiple bootstrapping
internal static func bootstrapInternal(_ factory: @escaping @Sendable (String) -> any LogHandler) {
self._metadataProviderFactory.replace(nil, validate: false)
self._factory.replace(
{ label, _ in
factory(label)
},
validate: false
)
}
// for our testing we want to allow multiple bootstrapping
internal static func bootstrapInternal(
_ factory: @escaping @Sendable (String, Logger.MetadataProvider?) -> any LogHandler,
metadataProvider: Logger.MetadataProvider?
) {
self._metadataProviderFactory.replace(metadataProvider, validate: false)
self._factory.replace(factory, validate: false)
}
internal static var factory: (String, Logger.MetadataProvider?) -> any LogHandler {
{ label, metadataProvider in
self._factory.underlying(label, metadataProvider)
}
}
/// System wide ``Logger/MetadataProvider`` that was configured during the logging system's `bootstrap`.
///
/// When creating a ``Logger`` using the plain ``Logger/init(label:)`` initializer, this metadata provider
/// will be provided to it.
///
/// When using custom log handler factories, make sure to provide the bootstrapped metadata provider to them,
/// or the metadata will not be filled in automatically using the provider on log-sites. While using a custom
/// factory to avoid using the bootstrapped metadata provider may sometimes be useful, usually it will lead to
/// un-expected behavior, so make sure to always propagate it to your handlers.
public static var metadataProvider: Logger.MetadataProvider? {
self._metadataProviderFactory.underlying
}
#if DEBUG
/// Used to warn only once about a specific ``LogHandler`` type when it does not support ``Logger/MetadataProvider``,
/// but an attempt was made to set a metadata provider on such handler. In order to avoid flooding the system with
/// warnings such warning is only emitted in debug mode, and even then at-most once for a handler type.
internal static func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(
_ type: Handler.Type
) -> Bool {
self._warnOnceBox.warnOnceLogHandlerNotSupportedMetadataProvider(type: type)
}
#endif
/// Protects an object such that it can only be accessed through a Reader-Writer lock.
final class RWLockedValueBox<Value: Sendable>: @unchecked Sendable {
private let lock = ReadWriteLock()
private var storage: Value
init(initialValue: Value) {
self.storage = initialValue
}
func withReadLock<Result>(_ operation: (Value) -> Result) -> Result {
self.lock.withReaderLock {
operation(self.storage)
}
}
func withWriteLock<Result>(_ operation: (inout Value) -> Result) -> Result {
self.lock.withWriterLock {
operation(&self.storage)
}
}
}
/// Protects an object by applying the constraints that it can only be accessed through a Reader-Writer lock
/// and can only be updated once from the initial value given.
private struct ReplaceOnceBox<BoxedType: Sendable> {
private struct ReplaceOnce: Sendable {
private var initialized = false
private var _underlying: BoxedType
private let violationErrorMessage: String
mutating func replaceUnderlying(_ underlying: BoxedType, validate: Bool) {
precondition(!validate || !self.initialized, self.violationErrorMessage)
self._underlying = underlying
self.initialized = true
}
var underlying: BoxedType {
self._underlying
}
init(underlying: BoxedType, violationErrorMessage: String) {
self._underlying = underlying
self.violationErrorMessage = violationErrorMessage
}
}
private let storage: RWLockedValueBox<ReplaceOnce>
init(_ underlying: BoxedType, violationErrorMesage: String) {
self.storage = .init(
initialValue: ReplaceOnce(
underlying: underlying,
violationErrorMessage: violationErrorMesage
)
)
}
func replace(_ newUnderlying: BoxedType, validate: Bool) {
self.storage.withWriteLock { $0.replaceUnderlying(newUnderlying, validate: validate) }
}
var underlying: BoxedType {
self.storage.withReadLock { $0.underlying }
}
}
private typealias FactoryBox = ReplaceOnceBox<
@Sendable (_ label: String, _ provider: Logger.MetadataProvider?) -> any LogHandler
>
private typealias MetadataProviderBox = ReplaceOnceBox<Logger.MetadataProvider?>
}
// MARK: - Debug only warnings
#if DEBUG
/// Contains state to manage all kinds of "warn only once" warnings which the logging system may want to issue.
private final class WarnOnceBox: @unchecked Sendable {
private let lock: Lock = Lock()
private var warnOnceLogHandlerNotSupportedMetadataProviderPerType = Set<ObjectIdentifier>()
func warnOnceLogHandlerNotSupportedMetadataProvider<Handler: LogHandler>(type: Handler.Type) -> Bool {
self.lock.withLock {
let id = ObjectIdentifier(type)
let (inserted, _) = warnOnceLogHandlerNotSupportedMetadataProviderPerType.insert(id)
return inserted // warn about this handler type, it is the first time we encountered it
}
}
}
#endif
+20 -7
View File
@@ -53,12 +53,24 @@ extension Logger {
/// }
/// ```
///
/// ### Metadata with Attributes
///
/// Metadata providers can return values that carry attributes via string interpolation:
///
/// ```swift
/// let provider = Logger.MetadataProvider {
/// [
/// "trace-id": "\(Baggage.current?.traceID, sensitivity: .public)",
/// "user-id": "\(RequestContext.current.userId, sensitivity: .sensitive)"
/// ]
/// }
/// ```
///
/// We recommend referring to [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing)
/// for metadata providers which make use of its tracing and metadata propagation infrastructure. It is however
/// possible to make use of metadata providers independently of tracing and instruments provided by that library,
/// if necessary.
public struct MetadataProvider: _SwiftLogSendable {
/// Provide ``Logger.Metadata`` from the current context.
@usableFromInline
internal let _provideMetadata: @Sendable () -> Metadata
@@ -70,6 +82,8 @@ extension Logger {
}
/// Invokes the metadata provider and returns the generated contextual metadata.
///
/// - Returns: Metadata dictionary, where values may carry attributes.
public func get() -> Metadata {
self._provideMetadata()
}
@@ -88,13 +102,12 @@ extension Logger.MetadataProvider {
/// - Returns: A pseudo-`MetadataProvider` merging metadata from the given `MetadataProvider`s.
public static func multiplex(_ providers: [Logger.MetadataProvider]) -> Logger.MetadataProvider? {
assert(!providers.isEmpty, "providers MUST NOT be empty")
return Logger.MetadataProvider {
providers.reduce(into: [:]) { metadata, provider in
let providedMetadata = provider.get()
guard !providedMetadata.isEmpty else {
return
}
metadata.merge(providedMetadata, uniquingKeysWith: { _, rhs in rhs })
providers.reduce(into: Logger.Metadata()) { merged, provider in
let provided = provider.get()
guard !provided.isEmpty else { return }
merged.merge(provided, uniquingKeysWith: { _, rhs in rhs })
}
}
}
@@ -22,15 +22,10 @@ struct InMemoryLogHandlerTests {
let (logHandler, logger) = self.makeTestLogger()
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
#expect(
logHandler.entries == [
InMemoryLogHandler.Entry(
level: .info,
message: "hello",
metadata: ["key1": "value1", "key2": ["a", "b", "c"]]
)
]
)
#expect(logHandler.entries.count == 1)
#expect(logHandler.entries[0].level == .info)
#expect(logHandler.entries[0].message == "hello")
#expect(logHandler.entries[0].metadata == ["key1": "value1", "key2": ["a", "b", "c"]])
}
@Test
@@ -39,16 +34,10 @@ struct InMemoryLogHandlerTests {
logger[metadataKey: "test"] = "value"
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
#expect(
logHandler.entries == [
InMemoryLogHandler.Entry(
level: .info,
message: "hello",
metadata: ["key1": "value1", "key2": ["a", "b", "c"], "test": "value"]
)
]
)
// Metadata also sticks onto the logger
#expect(logHandler.entries.count == 1)
#expect(logHandler.entries[0].level == .info)
#expect(logHandler.entries[0].message == "hello")
#expect(logHandler.entries[0].metadata == ["key1": "value1", "key2": ["a", "b", "c"], "test": "value"])
#expect(logger[metadataKey: "test"] == "value")
}
@@ -62,11 +51,54 @@ struct InMemoryLogHandlerTests {
logger[metadataKey: "c"] = "2"
logger.info("hello", metadata: ["c": "3"])
#expect(
logHandler.entries == [
InMemoryLogHandler.Entry(level: .info, message: "hello", metadata: ["a": "1", "b": "2", "c": "3"])
#expect(logHandler.entries.count == 1)
#expect(logHandler.entries[0].level == .info)
#expect(logHandler.entries[0].message == "hello")
#expect(logHandler.entries[0].metadata == ["a": "1", "b": "1", "c": "3"])
}
@Test
func clear() {
let (logHandler, logger) = self.makeTestLogger()
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
logHandler.clear()
logger.info("hello2")
#expect(logHandler.entries.count == 1)
#expect(logHandler.entries[0].level == .info)
#expect(logHandler.entries[0].message == "hello2")
#expect(logHandler.entries[0].metadata == [:])
}
@Test
func metadataWithAttributesIsPreservedInEntry() {
var (logHandler, logger) = self.makeTestLogger()
logger.logLevel = .trace
logger[metadataKey: "global"] = "value"
logger.log(
level: .info,
"test",
metadata: [
"key": "\("value", attributes: { _ in })"
]
)
#expect(logHandler.entries.count == 1)
#expect(logHandler.entries[0].metadata["key"]?.description == "value")
#expect(logHandler.entries[0].metadata["global"]?.description == "value")
}
private func makeTestLogger(metadataProvider: Logger.MetadataProvider? = nil) -> (InMemoryLogHandler, Logger) {
var logHandler = InMemoryLogHandler()
logHandler.metadataProvider = metadataProvider
let logger = Logger(
label: "MyApp",
factory: { _ in
logHandler
}
)
return (logHandler, logger)
}
@Test
@@ -81,7 +113,7 @@ struct InMemoryLogHandlerTests {
level: .info,
message: "hello",
error: TestError.first,
metadata: [:],
metadata: [:]
)
)
@@ -91,7 +123,7 @@ struct InMemoryLogHandlerTests {
level: .info,
message: "hello",
error: nil,
metadata: [:],
metadata: [:]
)
)
@@ -116,33 +148,6 @@ struct InMemoryLogHandlerTests {
)
}
@Test
func clear() {
let (logHandler, logger) = self.makeTestLogger()
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
logHandler.clear()
logger.info("hello2")
// Only hello2 is here
#expect(
logHandler.entries == [
InMemoryLogHandler.Entry(level: .info, message: "hello2", metadata: [:])
]
)
}
private func makeTestLogger(metadataProvider: Logger.MetadataProvider? = nil) -> (InMemoryLogHandler, Logger) {
var logHandler = InMemoryLogHandler()
logHandler.metadataProvider = metadataProvider
let logger = Logger(
label: "MyApp",
factory: { _ in
logHandler
}
)
return (logHandler, logger)
}
enum TestError: Error {
case first
case second
+59
View File
@@ -98,6 +98,65 @@ struct LogEventTest {
#expect(event.metadata == nil)
}
// MARK: - Attributes on metadata values
@Test func metadataValueCarriesAttributesThroughStringInterpolation() {
enum TestAttr: Int64, Logger.MetadataValueAttributes.Attribute {
case flagged = 1
}
let value: Logger.MetadataValue = "\("secret", attributes: { $0[TestAttr.self] = .flagged })"
#expect(value.attributes[TestAttr.self] == .flagged)
#expect(value.description == "secret")
}
@Test func metadataValueWithoutAttributesProducesString() {
let value: Logger.MetadataValue = "\("plain")"
#expect(value.attributes == Logger.MetadataValueAttributes())
if case .string(let s) = value {
#expect(s == "plain")
} else {
Issue.record("Expected .string case for non-attributed interpolation")
}
}
@Test func metadataValueAttributesAreEmptyForPlainValues() {
let values: [Logger.MetadataValue] = [
.string("test"),
.stringConvertible(42),
.array(["a", "b"]),
.dictionary(["k": "v"]),
]
for value in values {
#expect(value.attributes == Logger.MetadataValueAttributes())
}
}
@Test func metadataValuesWithAttributesFlowThroughLogEvent() {
enum TestAttr: Int64, Logger.MetadataValueAttributes.Attribute {
case flagged = 1
}
let event = LogEvent(
level: .info,
message: "test",
error: nil,
metadata: [
"secret": "\("value", attributes: { $0[TestAttr.self] = .flagged })",
"plain": "no-attrs",
],
source: nil,
file: "M/F.swift",
function: "f()",
line: 1
)
#expect(event.metadata?["secret"]?.attributes[TestAttr.self] == .flagged)
#expect(event.metadata?["secret"]?.description == "value")
#expect(event.metadata?["plain"]?.attributes[TestAttr.self] == nil)
}
@Test func loggerDerivedSourceMatchesModuleName() {
let recorder = Recorder()
let handler = LogEventHandler(recorder: recorder)
+72 -335
View File
@@ -17,15 +17,10 @@ import Testing
@testable import Logging
#if canImport(Darwin)
import Darwin
#elseif os(Windows)
import WinSDK
#elseif canImport(Android)
import Android
#else
import Glibc
#endif
private enum TestAttr: Int64, Logger.MetadataValueAttributes.Attribute {
case x = 1
case y = 2
}
extension LogHandler {
fileprivate func with(logLevel: Logger.Level) -> any LogHandler {
@@ -862,6 +857,73 @@ struct LoggingTest {
logger1.error("hey")
}
@Test func multiplexLogHandlerMetadataWithAttributes_settingAndReading() {
let logging1 = TestLogging()
let logging2 = TestLogging()
let logger1 = logging1.make(label: "1")
let logger2 = logging2.make(label: "2")
var multiplexLogger = Logger(
label: "test",
factory: { _ in
MultiplexLogHandler([logger1, logger2])
}
)
// Set metadata with attributes via string interpolation
multiplexLogger[metadataKey: "key1"] = "\("value1", attributes: { $0[TestAttr.self] = .x })"
// The value survives the round-trip
let retrieved = multiplexLogger[metadataKey: "key1"]
#expect(retrieved != nil)
#expect(retrieved?.description == "value1")
// Attributes are preserved inside .stringConvertible
#expect(retrieved?.attributes[TestAttr.self] == .x)
}
@Test func multiplexLogHandlerMetadataWithAttributes_forwardsEventWithAttributes() {
let logging1 = TestLogging()
let logging2 = TestLogging()
var logger = Logger(
label: "test",
factory: {
MultiplexLogHandler([logging1.make(label: $0), logging2.make(label: $0)])
}
)
logger.logLevel = .debug
// Log with metadata containing attributed values
logger.info("hello", metadata: ["request-id": "\("abc123")"])
// Both handlers should receive the message
logging1.history.assertExist(level: .info, message: "hello")
logging2.history.assertExist(level: .info, message: "hello")
}
@Test func metadataWithAttributes_flowsThroughHandler() {
let logging = TestLogging()
var logger = Logger(
label: "test",
factory: { logging.make(label: $0) }
)
logger.logLevel = .debug
// Log with metadata values that carry attributes
logger.info(
"attributed event",
metadata: [
"user-id": "\("12345", attributes: { $0[TestAttr.self] = .x })"
]
)
// The handler should receive the message via LogEvent
logging.history.assertExist(level: .info, message: "attributed event")
}
/// Protects an object such that it can only be accessed while holding a lock.
private final class LockedValueBox<Value: Sendable>: @unchecked Sendable {
private let lock = Lock()
@@ -1007,327 +1069,6 @@ struct LoggingTest {
#expect(Logger.Level(level.rawValue.uppercased()) == level)
}
final class InterceptStream: TextOutputStream {
var interceptedText: String?
var strings = [String]()
func write(_ string: String) {
// This is a test implementation, a real implementation would include locking
self.strings.append(string)
self.interceptedText = (self.interceptedText ?? "") + string
}
}
@Test func streamLogHandlerWritesToAStream() {
let interceptStream = InterceptStream()
let log = Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)")
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines)
.hasSuffix(testString)
#expect(messageSucceeded ?? false)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormat() {
let interceptStream = InterceptStream()
let label = "testLabel"
let source = "testSource"
let log = Logger(
label: label,
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", source: source)
let pattern =
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label):\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded =
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
of: pattern,
options: .regularExpression
) != nil
#expect(messageSucceeded)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormatWithEmptyLabel() {
let interceptStream = InterceptStream()
let source = "testSource"
let log = Logger(
label: "",
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", source: source)
let pattern =
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical):\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded =
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
of: pattern,
options: .regularExpression
) != nil
#expect(messageSucceeded)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormatWithMetaData() {
let interceptStream = InterceptStream()
let label = "testLabel"
let source = "testSource"
let log = Logger(
label: label,
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", metadata: ["test": "test"], source: source)
let pattern =
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label):\\stest=test\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded =
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
of: pattern,
options: .regularExpression
) != nil
#expect(messageSucceeded)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormatWithOrderedMetadata() {
let interceptStream = InterceptStream()
let log = Logger(
label: "testLabel",
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", metadata: ["a": "a0", "b": "b0"])
log.critical("\(testString)", metadata: ["b": "b1", "a": "a1"])
#expect(interceptStream.strings.count == 2)
guard interceptStream.strings.count == 2 else {
Issue.record("Intercepted \(interceptStream.strings.count) logs, expected 2")
return
}
#expect(interceptStream.strings[0].contains("a=a0 b=b0"), "LINES: \(interceptStream.strings[0])")
#expect(interceptStream.strings[1].contains("a=a1 b=b1"), "LINES: \(interceptStream.strings[1])")
}
@Test func streamLogHandlerWritesIncludeMetadataProviderMetadata() {
let interceptStream = InterceptStream()
let log = Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: interceptStream, metadataProvider: .exampleProvider)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)")
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines)
.hasSuffix(testString)
#expect(messageSucceeded ?? false)
#expect(interceptStream.strings.count == 1)
let message = interceptStream.strings.first!
#expect(message.contains("example=example-value"), "message must contain metadata, was: \(message)")
}
@Test func stdioOutputStreamWrite() {
self.withWriteReadFDsAndReadBuffer(flushMode: .always) { logStream, readFD, readBuffer in
let log = Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: logStream)
}
)
let testString = "hello\u{0} world"
log.critical("\(testString)")
#if os(Windows)
let size = _read(readFD, readBuffer, 256)
#else
let size = read(readFD, readBuffer, 256)
#endif
let output = String(
decoding: UnsafeRawBufferPointer(start: UnsafeRawPointer(readBuffer), count: numericCast(size)),
as: UTF8.self
)
let messageSucceeded = output.trimmingCharacters(in: .whitespacesAndNewlines).hasSuffix(testString)
#expect(messageSucceeded)
}
}
@Test func stdioOutputStreamFlush() {
// flush on every statement
self.withWriteReadFDsAndReadBuffer(flushMode: .always) { logStream, readFD, readBuffer in
Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: logStream)
}
).critical("test")
#if os(Windows)
let size = _read(readFD, readBuffer, 256)
#else
let size = read(readFD, readBuffer, 256)
#endif
#expect(size > -1, "expected flush")
logStream.flush()
#if os(Windows)
let size2 = _read(readFD, readBuffer, 256)
#else
let size2 = read(readFD, readBuffer, 256)
#endif
#expect(size2 == -1, "expected no flush")
}
// default flushing
self.withWriteReadFDsAndReadBuffer(flushMode: .undefined) { logStream, readFD, readBuffer in
Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: logStream)
}
).critical("test")
#if os(Windows)
let size = _read(readFD, readBuffer, 256)
#else
let size = read(readFD, readBuffer, 256)
#endif
#expect(size == -1, "expected no flush")
logStream.flush()
#if os(Windows)
let size2 = _read(readFD, readBuffer, 256)
#else
let size2 = read(readFD, readBuffer, 256)
#endif
#expect(size2 > -1, "expected flush")
}
}
func withWriteReadFDsAndReadBuffer(
flushMode: StdioOutputStream.FlushMode,
_ body: (StdioOutputStream, CInt, UnsafeMutablePointer<Int8>) -> Void
) {
var fds: [Int32] = [-1, -1]
#if os(Windows)
fds.withUnsafeMutableBufferPointer {
let err = _pipe($0.baseAddress, 256, _O_BINARY)
#expect(err == 0, "_pipe failed \(err)")
}
guard let writeFD = _fdopen(fds[1], "w") else {
Issue.record("Failed to open file")
return
}
#else
fds.withUnsafeMutableBufferPointer { ptr in
let err = pipe(ptr.baseAddress!)
#expect(err == 0, "pipe failed \(err)")
}
guard let writeFD = fdopen(fds[1], "w") else {
Issue.record("Failed to open file")
return
}
#endif
let writeBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
defer {
writeBuffer.deinitialize(count: 256)
writeBuffer.deallocate()
}
var err = setvbuf(writeFD, writeBuffer, _IOFBF, 256)
#expect(err == 0, "setvbuf failed \(err)")
// Create the stream here while writeFD's concrete type is in scope.
// Type inference in the generic StdioOutputStream init picks the right
// C functions for whatever FILE representation this platform/API level uses.
#if os(Windows)
let stream = StdioOutputStream(
file: writeFD,
flushMode: flushMode,
lock: _lock_file,
unlock: _unlock_file,
write: fwrite,
flush: fflush
)
#else
let stream = StdioOutputStream(
file: writeFD,
flushMode: flushMode,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#endif
let readFD = fds[0]
#if os(Windows)
let hPipe: HANDLE = HANDLE(bitPattern: _get_osfhandle(readFD))!
#expect(hPipe != INVALID_HANDLE_VALUE)
var dwMode: DWORD = DWORD(PIPE_NOWAIT)
let bSucceeded = SetNamedPipeHandleState(hPipe, &dwMode, nil, nil)
#expect(bSucceeded)
#else
err = fcntl(readFD, F_SETFL, fcntl(readFD, F_GETFL) | O_NONBLOCK)
#expect(err == 0, "fcntl failed \(err)")
#endif
let readBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
defer {
readBuffer.deinitialize(count: 256)
readBuffer.deallocate()
}
// the actual test
body(stream, readFD, readBuffer)
for fd in fds {
#if os(Windows)
_close(fd)
#else
close(fd)
#endif
}
}
@Test func overloadingError() {
struct Dummy: Error, LocalizedError {
var errorDescription: String? {
@@ -1426,12 +1167,8 @@ extension Logger.MetadataProvider {
}
}
// Sendable
// MARK: - Sendable
// used to test logging metadata which requires Sendable conformance
// @unchecked Sendable since manages it own state
extension LoggingTest.LazyMetadataBox: @unchecked Sendable {}
// used to test logging stream which requires Sendable conformance
// @unchecked Sendable since manages it own state
extension LoggingTest.InterceptStream: @unchecked Sendable {}
@@ -0,0 +1,443 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Logging
import Testing
// MARK: - Test Attribute Keys
enum AttrA: Int64, Logger.MetadataValueAttributes.Attribute {
case a1 = 1
case a2 = 2
}
enum AttrB: Int64, Logger.MetadataValueAttributes.Attribute {
case b1 = 1
case b2 = 2
}
enum AttrC: Int64, Logger.MetadataValueAttributes.Attribute {
case c1 = 1
case c2 = 2
}
enum AttrD: Int64, Logger.MetadataValueAttributes.Attribute {
case d1 = 1
case d2 = 2
}
enum AttrE: Int64, Logger.MetadataValueAttributes.Attribute {
case e1 = 1
case e2 = 2
}
// MARK: - Tests
@Suite("MetadataValueAttributes Tests")
struct MetadataAttributesTests {
@Test("Empty attributes")
func testEmpty() {
let attrs = Logger.MetadataValueAttributes()
#expect(attrs[AttrA.self] == nil)
#expect(attrs[AttrB.self] == nil)
}
@Test("Set and get single attribute (inline)")
func testSingleInline() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
#expect(attrs[AttrA.self] == .a1)
}
@Test("Set and get multiple attributes")
func testMultipleAttributes() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
attrs[AttrB.self] = .b2
attrs[AttrC.self] = .c1
#expect(attrs[AttrA.self] == .a1)
#expect(attrs[AttrB.self] == .b2)
#expect(attrs[AttrC.self] == .c1)
}
@Test("Update existing attribute")
func testUpdate() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
#expect(attrs[AttrA.self] == .a1)
attrs[AttrA.self] = .a2
#expect(attrs[AttrA.self] == .a2)
}
@Test("Remove inline attribute")
func testRemoveInline() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
attrs[AttrA.self] = nil
#expect(attrs[AttrA.self] == nil)
}
@Test("Remove overflow attribute")
func testRemoveOverflow() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
attrs[AttrB.self] = .b1
attrs[AttrC.self] = .c1
attrs[AttrB.self] = nil
#expect(attrs[AttrA.self] == .a1)
#expect(attrs[AttrB.self] == nil)
#expect(attrs[AttrC.self] == .c1)
}
@Test("Remove inline promotes from overflow")
func testRemoveInlinePromotesOverflow() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
attrs[AttrB.self] = .b1 // overflow
// Remove inline — overflow entry should be promoted
attrs[AttrA.self] = nil
#expect(attrs[AttrA.self] == nil)
#expect(attrs[AttrB.self] == .b1)
}
@Test("Five attributes")
func testFiveAttributes() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
attrs[AttrB.self] = .b1
attrs[AttrC.self] = .c1
attrs[AttrD.self] = .d1
attrs[AttrE.self] = .e1
#expect(attrs[AttrA.self] == .a1)
#expect(attrs[AttrB.self] == .b1)
#expect(attrs[AttrC.self] == .c1)
#expect(attrs[AttrD.self] == .d1)
#expect(attrs[AttrE.self] == .e1)
}
@Test("Update overflow attribute")
func testUpdateOverflow() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = .a1
attrs[AttrB.self] = .b1
attrs[AttrB.self] = .b2
#expect(attrs[AttrB.self] == .b2)
#expect(attrs[AttrA.self] == .a1)
}
@Test("Equality with same content")
func testEquality() {
var attrs1 = Logger.MetadataValueAttributes()
attrs1[AttrA.self] = .a1
attrs1[AttrB.self] = .b1
var attrs2 = Logger.MetadataValueAttributes()
attrs2[AttrA.self] = .a1
attrs2[AttrB.self] = .b1
#expect(attrs1 == attrs2)
attrs2[AttrB.self] = .b2
#expect(attrs1 != attrs2)
}
@Test("Equality is order-independent")
func testOrderIndependentEquality() {
var attrs1 = Logger.MetadataValueAttributes()
attrs1[AttrA.self] = .a1
attrs1[AttrB.self] = .b1
attrs1[AttrC.self] = .c1
var attrs2 = Logger.MetadataValueAttributes()
attrs2[AttrC.self] = .c1
attrs2[AttrA.self] = .a1
attrs2[AttrB.self] = .b1
#expect(attrs1 == attrs2)
}
@Test("Setting nil on non-existent attribute is no-op")
func testSetNilNonExistent() {
var attrs = Logger.MetadataValueAttributes()
attrs[AttrA.self] = nil
#expect(attrs[AttrA.self] == nil)
attrs[AttrB.self] = .b1
attrs[AttrA.self] = nil
#expect(attrs[AttrA.self] == nil)
#expect(attrs[AttrB.self] == .b1)
}
// MARK: - MetadataValue.attributed factory
@Test("Create attributed value with .attributed factory")
func testAttributedFactory() {
let value: Logger.MetadataValue = .attributed("hello", attributes: [AttrA.a1])
#expect(value.description == "hello")
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Attributed factory with multiple attributes")
func testAttributedFactoryMultipleAttributes() {
let value: Logger.MetadataValue = .attributed("test", attributes: [AttrA.a1, AttrB.b2])
#expect(value.description == "test")
#expect(value.attributes[AttrA.self] == .a1)
#expect(value.attributes[AttrB.self] == .b2)
}
@Test("Attributed factory with empty attributes")
func testAttributedFactoryEmptyAttributes() {
let value: Logger.MetadataValue = .attributed("plain", attributes: .init())
#expect(value.description == "plain")
#expect(value.attributes[AttrA.self] == nil)
}
@Test("Attributed factory produces same result as string interpolation")
func testAttributedFactoryMatchesStringInterpolation() {
let factory: Logger.MetadataValue = .attributed("42", attributes: [AttrA.a1])
let interpolated: Logger.MetadataValue = "\(42, attributes: [AttrA.a1])"
#expect(factory.description == interpolated.description)
#expect(factory.attributes == interpolated.attributes)
}
// MARK: - Array literal construction
@Test("Array literal with single attribute")
func testArrayLiteralSingle() {
let attrs: Logger.MetadataValueAttributes = [AttrA.a1]
#expect(attrs[AttrA.self] == .a1)
}
@Test("Array literal with multiple attributes")
func testArrayLiteralMultiple() {
let attrs: Logger.MetadataValueAttributes = [AttrA.a1, AttrB.b2, AttrC.c1]
#expect(attrs[AttrA.self] == .a1)
#expect(attrs[AttrB.self] == .b2)
#expect(attrs[AttrC.self] == .c1)
}
@Test("Array literal with duplicate key uses last value")
func testArrayLiteralDuplicateKey() {
let attrs: Logger.MetadataValueAttributes = [AttrA.a1, AttrA.a2]
#expect(attrs[AttrA.self] == .a2)
}
// MARK: - MetadataValue.attributes setter
@Test("Set attributes on .string value")
func testSetAttributesOnString() {
var value: Logger.MetadataValue = "hello"
#expect(value.attributes[AttrA.self] == nil)
value.attributes = [AttrA.a1]
#expect(value.description == "hello")
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Set attributes replaces existing attributes")
func testSetAttributesReplacesExisting() {
var value: Logger.MetadataValue = .attributed("test", attributes: [AttrA.a1])
#expect(value.attributes[AttrA.self] == .a1)
let newAttrs: Logger.MetadataValueAttributes = [AttrB.b2]
value.attributes = newAttrs
#expect(value.description == "test")
#expect(value.attributes[AttrA.self] == nil)
#expect(value.attributes[AttrB.self] == .b2)
}
// MARK: - Intermediate handler modifies attributes
@Test("Intermediate handler adds attributes before forwarding")
func testIntermediateHandlerAddsAttributes() {
let recorder = AttributeRecorder()
let inner = AttributeRecordingHandler(recorder: recorder)
let enriching = AttributeEnrichingHandler(wrapping: inner)
var logger = Logger(label: "test") { _ in enriching }
logger.logLevel = .trace
logger.info(
"event",
metadata: [
"tagged": .attributed(42, attributes: [AttrA.a1]),
"plain": "no-attrs",
]
)
#expect(recorder.messages.count == 1)
let metadata = recorder.messages[0]
// The enriching handler should have added AttrB to all values
#expect(metadata["tagged"]?.attributes[AttrA.self] == .a1)
#expect(metadata["tagged"]?.attributes[AttrB.self] == .b1)
#expect(metadata["plain"]?.attributes[AttrB.self] == .b1)
}
@Test("Intermediate handler replaces attributes before forwarding")
func testIntermediateHandlerReplacesAttributes() {
let recorder = AttributeRecorder()
let inner = AttributeRecordingHandler(recorder: recorder)
let stripping = AttributeStrippingHandler(wrapping: inner)
var logger = Logger(label: "test") { _ in stripping }
logger.logLevel = .trace
logger.info(
"event",
metadata: [
"tagged": .attributed(42, attributes: [AttrA.a1])
]
)
#expect(recorder.messages.count == 1)
let metadata = recorder.messages[0]
// The stripping handler should have removed all attributes
#expect(metadata["tagged"]?.attributes[AttrA.self] == nil)
#expect(metadata["tagged"]?.description == "42")
}
}
// MARK: - Test Helpers for intermediate handler tests
private final class AttributeRecorder: @unchecked Sendable {
private let lock = Lock()
private var _messages: [Logger.Metadata] = []
func record(metadata: Logger.Metadata) {
self.lock.withLock { self._messages.append(metadata) }
}
var messages: [Logger.Metadata] {
self.lock.withLock { self._messages }
}
}
private struct AttributeRecordingHandler: LogHandler {
var logLevel: Logger.Level = .trace
var metadata = Logger.Metadata()
var metadataProvider: Logger.MetadataProvider?
private let recorder: AttributeRecorder
init(recorder: AttributeRecorder) {
self.recorder = recorder
}
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get { self.metadata[key] }
set { self.metadata[key] = newValue }
}
func log(event: LogEvent) {
var merged = self.metadata
if let eventMetadata = event.metadata {
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
}
self.recorder.record(metadata: merged)
}
}
/// Intermediate handler that enriches all metadata values with AttrB before forwarding.
private struct AttributeEnrichingHandler: LogHandler {
var logLevel: Logger.Level {
get { self.inner.logLevel }
set { self.inner.logLevel = newValue }
}
var metadata: Logger.Metadata {
get { self.inner.metadata }
set { self.inner.metadata = newValue }
}
var metadataProvider: Logger.MetadataProvider? {
get { self.inner.metadataProvider }
set { self.inner.metadataProvider = newValue }
}
private var inner: any LogHandler
init(wrapping inner: any LogHandler) {
self.inner = inner
}
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get { self.inner[metadataKey: key] }
set { self.inner[metadataKey: key] = newValue }
}
func log(event: LogEvent) {
var mutatedEvent = event
if var eventMetadata = event.metadata {
for (key, value) in eventMetadata {
var attrs = value.attributes
attrs[AttrB.self] = .b1
eventMetadata[key]?.attributes = attrs
}
mutatedEvent.metadata = eventMetadata
}
self.inner.log(event: mutatedEvent)
}
}
/// Intermediate handler that strips all attributes before forwarding.
private struct AttributeStrippingHandler: LogHandler {
var logLevel: Logger.Level {
get { self.inner.logLevel }
set { self.inner.logLevel = newValue }
}
var metadata: Logger.Metadata {
get { self.inner.metadata }
set { self.inner.metadata = newValue }
}
var metadataProvider: Logger.MetadataProvider? {
get { self.inner.metadataProvider }
set { self.inner.metadataProvider = newValue }
}
private var inner: any LogHandler
init(wrapping inner: any LogHandler) {
self.inner = inner
}
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get { self.inner[metadataKey: key] }
set { self.inner[metadataKey: key] = newValue }
}
func log(event: LogEvent) {
var mutatedEvent = event
if var eventMetadata = event.metadata {
for (key, _) in eventMetadata {
eventMetadata[key]?.attributes = .init()
}
mutatedEvent.metadata = eventMetadata
}
self.inner.log(event: mutatedEvent)
}
}
@@ -0,0 +1,349 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Foundation
import Logging
import Testing
// MARK: - Helper types covering each overload
/// `TextOutputStreamable & CustomStringConvertible` — exercises the most-specific overload.
private struct StreamingAndDescribing: TextOutputStreamable, CustomStringConvertible {
let value: Int
var description: String { "SD(\(self.value))" }
func write<Target: TextOutputStream>(to target: inout Target) {
target.write(self.description)
}
}
/// `TextOutputStreamable` only — exercises the TOS-only overload. (Rare in practice.)
private struct StreamingOnly: TextOutputStreamable {
let value: Int
func write<Target: TextOutputStream>(to target: inout Target) {
target.write("SO(\(self.value))")
}
}
/// `CustomStringConvertible` only — exercises the CSC-only overload.
private struct DescribingOnly: CustomStringConvertible {
let value: Int
var description: String { "DO(\(self.value))" }
}
/// Neither TOS nor CSC — exercises the unconstrained fallback.
private struct PlainStruct {
let value: Int
}
/// Non-`Sendable` reference type — exercises the unconstrained overload and verifies
/// that the constraint relaxation in `appendInterpolation` accepts non-`Sendable` arguments.
private final class NonSendableBox {
var value: Int
init(_ value: Int) { self.value = value }
}
@Suite("MetadataValue String Interpolation")
struct MetadataValueInterpolationTests {
// MARK: - Plain interpolation by overload overload
@Test("String interpolates via TOS & CSC overload")
func plainString() {
let value: Logger.MetadataValue = "hello \("world")"
#expect(value.description == "hello world")
}
@Test("Int interpolates via TOS & CSC overload")
func plainInt() {
let value: Logger.MetadataValue = "n=\(42)"
#expect(value.description == "n=42")
}
@Test("Double interpolates via TOS & CSC overload")
func plainDouble() {
let value: Logger.MetadataValue = "x=\(1.5)"
#expect(value.description == "x=1.5")
}
@Test("Substring interpolates via TOS & CSC overload")
func plainSubstring() {
let s = "hello world"
let value: Logger.MetadataValue = "\(s.dropFirst(6))"
#expect(value.description == "world")
}
@Test("Custom TOS & CSC type uses the most-specific overload")
func plainStreamingAndDescribing() {
let value: Logger.MetadataValue = "\(StreamingAndDescribing(value: 7))"
#expect(value.description == "SD(7)")
}
@Test("TOS-only type interpolates via the TOS overload")
func plainStreamingOnly() {
let value: Logger.MetadataValue = "\(StreamingOnly(value: 9))"
#expect(value.description == "SO(9)")
}
@Test("CSC-only type interpolates via .description")
func plainDescribingOnly() {
let value: Logger.MetadataValue = "\(DescribingOnly(value: 3))"
#expect(value.description == "DO(3)")
}
@Test("Array (CSC, not TOS) interpolates via .description")
func plainArray() {
let value: Logger.MetadataValue = "\([1, 2, 3])"
#expect(value.description == "[1, 2, 3]")
}
@Test("Foundation.Data (CSC) interpolates via .description")
func plainData() {
let data = Data([0x41, 0x42])
let value: Logger.MetadataValue = "\(data)"
#expect(value.description == data.description)
}
@Test("Plain struct (no CSC, no TOS) falls through to String(describing:)")
func plainPlainStruct() {
let value: Logger.MetadataValue = "\(PlainStruct(value: 5))"
#expect(value.description == String(describing: PlainStruct(value: 5)))
}
@Test("Non-Sendable class falls through to String(describing:) and compiles")
func plainNonSendable() {
let box = NonSendableBox(11)
let value: Logger.MetadataValue = "\(box)"
#expect(value.description == String(describing: box))
}
// MARK: - Optional interpolation with a default
@Test("nil optional uses the default string")
func defaultNil() {
let value: Int? = nil
let result: Logger.MetadataValue = "\(value, default: "none")"
#expect(result.description == "none")
}
@Test("non-nil optional interpolates the wrapped value")
func defaultSome() {
let value: Int? = 42
let result: Logger.MetadataValue = "\(value, default: "none")"
#expect(result.description == "42")
}
@Test("nil optional of a TOS-only type uses the default")
func defaultNilStreamingOnly() {
let value: StreamingOnly? = nil
let result: Logger.MetadataValue = "\(value, default: "missing")"
#expect(result.description == "missing")
}
@Test("non-nil optional of a CSC-only type interpolates via .description")
func defaultSomeDescribingOnly() {
let value: DescribingOnly? = DescribingOnly(value: 3)
let result: Logger.MetadataValue = "\(value, default: "missing")"
#expect(result.description == "DO(3)")
}
@Test("nil optional of a non-CSC, non-TOS type uses the default")
func defaultNilUnconstrained() {
let value: PlainStruct? = nil
let result: Logger.MetadataValue = "\(value, default: "absent")"
#expect(result.description == "absent")
}
@Test("default accepts a Substring (some StringProtocol)")
func defaultSubstring() {
let value: Int? = nil
let fallback = "n/a value".dropFirst(4)
let result: Logger.MetadataValue = "\(value, default: fallback)"
#expect(result.description == "value")
}
@Test("default segment mixed with plain segments")
func defaultMultiSegment() {
let name: String? = nil
let result: Logger.MetadataValue = "user=\(name, default: "anon") id=\(42)"
#expect(result.description == "user=anon id=42")
}
@Test("default interpolation yields .string case")
func defaultYieldsStringCase() {
let value: Int? = nil
let result: Logger.MetadataValue = "\(value, default: "none")"
if case .string(let s) = result {
#expect(s == "none")
} else {
Issue.record("Expected .string case, got \(result)")
}
}
// MARK: - Overloaded return types
@Test("Overloaded function returning String/Data/[UInt8] disambiguates to String")
func overloadedReturnTypeAmbiguity() {
func someFunc() -> String { "from-string" }
func someFunc() -> Data { Data([0x00]) }
func someFunc() -> [UInt8] { [0xFF] }
// Without the TOS & CSC overload this would fail with "ambiguous use of 'someFunc()'".
// String wins because it's TOS & CSC; Data and [UInt8] are CSC-only.
let value: Logger.MetadataValue = "\(someFunc())"
#expect(value.description == "from-string")
}
// MARK: - Closure-attribute interpolation
@Test("Closure attributes attach to a TOS & CSC value")
func closureAttrsTOSAndCSC() {
let value: Logger.MetadataValue = "\(42, attributes: { $0[AttrA.self] = .a1 })"
#expect(value.description == "42")
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Closure attributes attach to a CSC-only value")
func closureAttrsCSC() {
let value: Logger.MetadataValue = "\(DescribingOnly(value: 1), attributes: { $0[AttrA.self] = .a1 })"
#expect(value.description == "DO(1)")
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Closure attributes attach to a TOS-only value")
func closureAttrsTOS() {
let value: Logger.MetadataValue = "\(StreamingOnly(value: 2), attributes: { $0[AttrA.self] = .a1 })"
#expect(value.description == "SO(2)")
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Closure attributes attach to a non-CSC, non-TOS value")
func closureAttrsUnconstrained() {
let s = PlainStruct(value: 4)
let value: Logger.MetadataValue = "\(s, attributes: { $0[AttrA.self] = .a1 })"
#expect(value.description == String(describing: s))
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Closure attributes accept a non-Sendable value")
func closureAttrsNonSendable() {
let box = NonSendableBox(13)
let value: Logger.MetadataValue = "\(box, attributes: { $0[AttrA.self] = .a1 })"
#expect(value.description == String(describing: box))
#expect(value.attributes[AttrA.self] == .a1)
}
// MARK: - Pre-built attribute interpolation
@Test("Pre-built attributes attach to a TOS & CSC value")
func valueAttrsTOSAndCSC() {
let value: Logger.MetadataValue = "\(42, attributes: [AttrA.a1, AttrB.b2])"
#expect(value.description == "42")
#expect(value.attributes[AttrA.self] == .a1)
#expect(value.attributes[AttrB.self] == .b2)
}
@Test("Pre-built attributes attach to a CSC-only value")
func valueAttrsCSC() {
let value: Logger.MetadataValue = "\(DescribingOnly(value: 8), attributes: [AttrA.a1])"
#expect(value.description == "DO(8)")
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Pre-built attributes attach to a non-CSC value")
func valueAttrsUnconstrained() {
let s = PlainStruct(value: 6)
let value: Logger.MetadataValue = "\(s, attributes: [AttrA.a1])"
#expect(value.description == String(describing: s))
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Pre-built attributes accept a non-Sendable value")
func valueAttrsNonSendable() {
let box = NonSendableBox(17)
let value: Logger.MetadataValue = "\(box, attributes: [AttrA.a1])"
#expect(value.description == String(describing: box))
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Empty attributes still produce an attributed result")
func valueAttrsEmpty() {
let value: Logger.MetadataValue = "\(42, attributes: Logger.MetadataValueAttributes())"
#expect(value.description == "42")
// No attribute keys are set, but the carrier exists.
#expect(value.attributes[AttrA.self] == nil)
}
// MARK: - Multi-segment interpolation
@Test("Plain + plain segments concatenate without attributes")
func multiPlain() {
let value: Logger.MetadataValue = "user=\("alice") id=\(42)"
#expect(value.description == "user=alice id=42")
#expect(value.attributes[AttrA.self] == nil)
}
@Test("Plain + attributed segments produce attributed result")
func multiPlainAndAttributed() {
let value: Logger.MetadataValue = "user=\("alice") action=\("login", attributes: [AttrA.a1])"
#expect(value.description == "user=alice action=login")
#expect(value.attributes[AttrA.self] == .a1)
}
@Test("Two attributed segments merge their attributes")
func multiAttributedMerge() {
let value: Logger.MetadataValue = "\("a", attributes: [AttrA.a1])-\("b", attributes: [AttrB.b2])"
#expect(value.description == "a-b")
#expect(value.attributes[AttrA.self] == .a1)
#expect(value.attributes[AttrB.self] == .b2)
}
@Test("Closure-attributes and value-attributes segments merge")
func multiAttributedMixed() {
let value: Logger.MetadataValue =
"\("x", attributes: { $0[AttrA.self] = .a1 })-\("y", attributes: [AttrB.b2])"
#expect(value.description == "x-y")
#expect(value.attributes[AttrA.self] == .a1)
#expect(value.attributes[AttrB.self] == .b2)
}
@Test("Conflicting attribute keys: later segment wins")
func multiAttributedConflict() {
let value: Logger.MetadataValue =
"\("a", attributes: [AttrA.a1])-\("b", attributes: [AttrA.a2])"
#expect(value.description == "a-b")
#expect(value.attributes[AttrA.self] == .a2)
}
// MARK: - Result-case discrimination
@Test("Plain interpolation yields .string case")
func plainYieldsStringCase() {
let value: Logger.MetadataValue = "\(42)"
if case .string(let s) = value {
#expect(s == "42")
} else {
Issue.record("Expected .string case, got \(value)")
}
}
@Test("Attributed interpolation yields .stringConvertible case")
func attributedYieldsStringConvertibleCase() {
let value: Logger.MetadataValue = "\(42, attributes: [AttrA.a1])"
if case .stringConvertible = value {
// ok
} else {
Issue.record("Expected .stringConvertible case, got \(value)")
}
}
}
@@ -0,0 +1,357 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Foundation
import Testing
@testable import Logging
#if canImport(Darwin)
import Darwin
#elseif os(Windows)
import WinSDK
#elseif canImport(Android)
import Android
#else
import Glibc
#endif
struct StreamLogHandlerTest {
final class InterceptStream: TextOutputStream {
var interceptedText: String?
var strings = [String]()
func write(_ string: String) {
// This is a test implementation, a real implementation would include locking
self.strings.append(string)
self.interceptedText = (self.interceptedText ?? "") + string
}
}
@Test func streamLogHandlerWritesToAStream() {
let interceptStream = InterceptStream()
let log = Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)")
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines)
.hasSuffix(testString)
#expect(messageSucceeded ?? false)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormat() {
let interceptStream = InterceptStream()
let label = "testLabel"
let source = "testSource"
let log = Logger(
label: label,
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", source: source)
let pattern =
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label):\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded =
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
of: pattern,
options: .regularExpression
) != nil
#expect(messageSucceeded)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormatWithEmptyLabel() {
let interceptStream = InterceptStream()
let source = "testSource"
let log = Logger(
label: "",
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", source: source)
let pattern =
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical):\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded =
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
of: pattern,
options: .regularExpression
) != nil
#expect(messageSucceeded)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormatWithMetaData() {
let interceptStream = InterceptStream()
let label = "testLabel"
let source = "testSource"
let log = Logger(
label: label,
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", metadata: ["test": "test"], source: source)
let pattern =
"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label):\\stest=test\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded =
interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(
of: pattern,
options: .regularExpression
) != nil
#expect(messageSucceeded)
#expect(interceptStream.strings.count == 1)
}
@Test func streamLogHandlerOutputFormatWithOrderedMetadata() {
let interceptStream = InterceptStream()
let log = Logger(
label: "testLabel",
factory: {
StreamLogHandler(label: $0, stream: interceptStream)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)", metadata: ["a": "a0", "b": "b0"])
log.critical("\(testString)", metadata: ["b": "b1", "a": "a1"])
#expect(interceptStream.strings.count == 2)
guard interceptStream.strings.count == 2 else {
Issue.record("Intercepted \(interceptStream.strings.count) logs, expected 2")
return
}
#expect(interceptStream.strings[0].contains("a=a0 b=b0"), "LINES: \(interceptStream.strings[0])")
#expect(interceptStream.strings[1].contains("a=a1 b=b1"), "LINES: \(interceptStream.strings[1])")
}
@Test func streamLogHandlerWritesIncludeMetadataProviderMetadata() {
let interceptStream = InterceptStream()
let log = Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: interceptStream, metadataProvider: .exampleProvider)
}
)
let testString = "my message is better than yours"
log.critical("\(testString)")
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines)
.hasSuffix(testString)
#expect(messageSucceeded ?? false)
#expect(interceptStream.strings.count == 1)
let message = interceptStream.strings.first!
#expect(message.contains("example=example-value"), "message must contain metadata, was: \(message)")
}
@Test func stdioOutputStreamWrite() {
self.withWriteReadFDsAndReadBuffer(flushMode: .always) { logStream, readFD, readBuffer in
let log = Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: logStream)
}
)
let testString = "hello\u{0} world"
log.critical("\(testString)")
#if os(Windows)
let size = _read(readFD, readBuffer, 256)
#else
let size = read(readFD, readBuffer, 256)
#endif
let output = String(
decoding: UnsafeRawBufferPointer(start: UnsafeRawPointer(readBuffer), count: numericCast(size)),
as: UTF8.self
)
let messageSucceeded = output.trimmingCharacters(in: .whitespacesAndNewlines).hasSuffix(testString)
#expect(messageSucceeded)
}
}
@Test func stdioOutputStreamFlush() {
// flush on every statement
self.withWriteReadFDsAndReadBuffer(flushMode: .always) { logStream, readFD, readBuffer in
Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: logStream)
}
).critical("test")
#if os(Windows)
let size = _read(readFD, readBuffer, 256)
#else
let size = read(readFD, readBuffer, 256)
#endif
#expect(size > -1, "expected flush")
logStream.flush()
#if os(Windows)
let size2 = _read(readFD, readBuffer, 256)
#else
let size2 = read(readFD, readBuffer, 256)
#endif
#expect(size2 == -1, "expected no flush")
}
// default flushing
self.withWriteReadFDsAndReadBuffer(flushMode: .undefined) { logStream, readFD, readBuffer in
Logger(
label: "test",
factory: {
StreamLogHandler(label: $0, stream: logStream)
}
).critical("test")
#if os(Windows)
let size = _read(readFD, readBuffer, 256)
#else
let size = read(readFD, readBuffer, 256)
#endif
#expect(size == -1, "expected no flush")
logStream.flush()
#if os(Windows)
let size2 = _read(readFD, readBuffer, 256)
#else
let size2 = read(readFD, readBuffer, 256)
#endif
#expect(size2 > -1, "expected flush")
}
}
func withWriteReadFDsAndReadBuffer(
flushMode: StdioOutputStream.FlushMode,
_ body: (StdioOutputStream, CInt, UnsafeMutablePointer<Int8>) -> Void
) {
var fds: [Int32] = [-1, -1]
#if os(Windows)
fds.withUnsafeMutableBufferPointer {
let err = _pipe($0.baseAddress, 256, _O_BINARY)
#expect(err == 0, "_pipe failed \(err)")
}
guard let writeFD = _fdopen(fds[1], "w") else {
Issue.record("Failed to open file")
return
}
#else
fds.withUnsafeMutableBufferPointer { ptr in
let err = pipe(ptr.baseAddress!)
#expect(err == 0, "pipe failed \(err)")
}
guard let writeFD = fdopen(fds[1], "w") else {
Issue.record("Failed to open file")
return
}
#endif
let writeBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
defer {
writeBuffer.deinitialize(count: 256)
writeBuffer.deallocate()
}
var err = setvbuf(writeFD, writeBuffer, _IOFBF, 256)
#expect(err == 0, "setvbuf failed \(err)")
// Create the stream here while writeFD's concrete type is in scope.
// Type inference in the generic StdioOutputStream init picks the right
// C functions for whatever FILE representation this platform/API level uses.
#if os(Windows)
let stream = StdioOutputStream(
file: writeFD,
flushMode: flushMode,
lock: _lock_file,
unlock: _unlock_file,
write: fwrite,
flush: fflush
)
#else
let stream = StdioOutputStream(
file: writeFD,
flushMode: flushMode,
lock: flockfile,
unlock: funlockfile,
write: fwrite,
flush: fflush
)
#endif
let readFD = fds[0]
#if os(Windows)
let hPipe: HANDLE = HANDLE(bitPattern: _get_osfhandle(readFD))!
#expect(hPipe != INVALID_HANDLE_VALUE)
var dwMode: DWORD = DWORD(PIPE_NOWAIT)
let bSucceeded = SetNamedPipeHandleState(hPipe, &dwMode, nil, nil)
#expect(bSucceeded)
#else
err = fcntl(readFD, F_SETFL, fcntl(readFD, F_GETFL) | O_NONBLOCK)
#expect(err == 0, "fcntl failed \(err)")
#endif
let readBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
defer {
readBuffer.deinitialize(count: 256)
readBuffer.deallocate()
}
// the actual test
body(stream, readFD, readBuffer)
for fd in fds {
#if os(Windows)
_close(fd)
#else
close(fd)
#endif
}
}
}
// MARK: - Sendable
// used to test logging stream which requires Sendable conformance
// @unchecked Sendable since manages it own state
extension StreamLogHandlerTest.InterceptStream: @unchecked Sendable {}
@@ -0,0 +1,76 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Testing
@testable import Logging
struct SwiftLogNoOpLogHandlerTest {
@Test func initWithNoArguments() {
let handler = SwiftLogNoOpLogHandler()
#expect(handler.logLevel == .critical)
#expect(handler.metadata == [:])
}
@Test func initWithLabel() {
let handler = SwiftLogNoOpLogHandler("some.label")
#expect(handler.logLevel == .critical)
#expect(handler.metadata == [:])
}
@Test func logLevelIgnoresMutations() {
var handler = SwiftLogNoOpLogHandler()
handler.logLevel = .trace
#expect(handler.logLevel == .critical)
}
@Test func metadataIgnoresMutations() {
var handler = SwiftLogNoOpLogHandler()
handler.metadata = ["key": "value"]
#expect(handler.metadata == [:])
}
@Test func metadataSubscriptAlwaysReturnsNil() {
var handler = SwiftLogNoOpLogHandler()
#expect(handler[metadataKey: "key"] == nil)
handler[metadataKey: "key"] = "value"
#expect(handler[metadataKey: "key"] == nil)
}
@Test func logEventDoesNotCrash() {
let handler = SwiftLogNoOpLogHandler()
let event = LogEvent(
level: .critical,
message: "message",
metadata: ["key": "value"],
source: "test",
file: #file,
function: #function,
line: #line
)
handler.log(event: event)
}
@Test func allLogLevelsDoNotCrash() {
var logger = Logger(label: "noop.test", factory: { _ in SwiftLogNoOpLogHandler() })
logger[metadataKey: "key"] = "value"
logger.trace("trace message")
logger.debug("debug message")
logger.info("info message")
logger.notice("notice message")
logger.warning("warning message")
logger.error("error message")
logger.critical("critical message")
}
}
+1 -1
View File
@@ -485,7 +485,7 @@ internal struct TestLibrary: Sendable {
}
}
// Sendable
// MARK: - Sendable
extension TestLogHandler: @unchecked Sendable {}
extension Recorder: @unchecked Sendable {}
-14
View File
@@ -1,14 +0,0 @@
One line description of your change
Motivation:
Explain here the context, and why you're making that change.
What is the problem you're trying to solve.
Modifications:
Describe the modifications you've done.
Result:
After your change, what will change.