Compare commits

...
94 Commits
Author SHA1 Message Date
Luc Talatinian 82cf87d893 bump minimum Swift tools version to 6.2.3 (#534)
closes #533
2026-11-20 11:36:25 +00:00
Vladimir Kukushkin 47655e0c23 Adopt /swiftlang CI workflows (#536)
Switch from swift-nio to swiftlang CI workflows. As there is no tag yet
available, let's use the latest hash for now.

### Motivation:

Modernize and unify workflows with swiftlang.

### Modifications:

CI configuration updated.

### Result:

No swift-nio references in CI workflows.
Additionally, Swift tools version triplet is now supported to unblock
#534
2026-11-19 15:36:41 +00:00
Honza Dvorsky d05c8efdae Make benchmarks more reliable by using the scale factor (#539)
### Motivation:

Currently the benchmark machinery overhead is causing a lot of noise in
benchmarks of very efficient/fast code.

### Modifications:

Use the scaling factor to amortize the fixed overhead and let the actual
tested code account for most of the measured metrics.

### Result:

More reliable benchmarks that don't fail 20% of the time.
2026-11-19 09:59:58 +00:00
0z5a c7413d967b Make MultiplexLogHandler.metadataProvider setter replace the initializer's provider (#537)
### Motivation:

`MultiplexLogHandler.metadataProvider`'s setter only forwards the new
provider to the underlying handlers. Since #522, `log(event:)` also
merges the provider passed to `init(_:metadataProvider:)` on top of the
underlying handlers' metadata, so after a set that old provider still
overrides the new one for conflicting keys, setting `nil` doesn't remove
it, and the getter keeps returning it.

This shows up through `Logger(label:metadataProvider:)`, which calls the
factory and then sets `handler.metadataProvider`. If the bootstrapped
factory returns a `MultiplexLogHandler` with its own provider, the
provider the library passed is silently overridden. With a plain handler
the same code uses the library's provider, which is what
`Logger(label:metadataProvider:)` documents ("the custom metadata
provider this logger should invoke, instead of the system wide
bootstrapped one").

### Modifications:

- In the setter, also replace the multiplex handler's own provider with
the new value. It is still forwarded to the underlying handlers as
before.
- Document the setter.
- Add regression tests: setting a provider replaces the initializer's
provider for one and two handlers, and setting `nil` clears it (both the
getter and emitted logs). Another test covers an underlying handler that
doesn't support metadata providers.

I kept forwarding to the underlying handlers and replace the multiplex
handler's own provider as well, rather than clearing it. Clearing it
would drop provider metadata for underlying handlers that use the
default `metadataProvider` implementation in the
`Logger(label:metadataProvider:)` case, which works today.

### Result:

After `handler.metadataProvider = p`, logs and the getter use `p`. After
`handler.metadataProvider = nil`, no provider metadata is added. In the
common setup where the factory passes its provider into the
`MultiplexLogHandler` initializer, the number of provider calls per log
stays the same. When the multiplex handler had no provider of its own, a
set now also applies the provider once at the multiplex level, so
underlying handlers without provider support get its metadata too.

The new tests fail on main and pass with this change. All tests pass
locally on macOS (Swift 6.3.3), and `swift format lint` is clean on the
changed files. I couldn't run the benchmarks locally.

This change was drafted with Claude Code (claude-opus-5-5); the test
results above are from the runs described.
2026-11-17 13:24:42 +00:00
Tony Allevato 34b131f794 Support raw-identifier module names in Logger.currentModule. (#535)
When a module name (via `-module-alias`) is a raw identifier (SE-0451),
`#fileID` formats the module component enclosed in backticks (for
example, `` `/a/b/c`/File.swift ``). If the raw identifier contains '/',
splitting on the first '/' in `#fileID` truncates the module name at the
slash inside the backticks.

When `#fileID` starts with a backtick, advance past the matching closing
backtick before searching for the '/' separator that ends the module
name, preserving the enclosing backticks.
2026-11-10 14:27:30 +00:00
e3da040787 Fix metadata priority in MultiplexLogHandler.metadata (#530)
Fixes #498

## Problem

`MultiplexLogHandler` had inconsistent metadata priority:

- `subscript(metadataKey:)` reads the value from the **first** handler
that has the key (documented: "the first handler's values are more
important")
- `metadata` (full dictionary) merged handlers **last-wins**, so the
value came from the **last** handler with that key

## Fix

The `metadata` getter now merges handlers in their initialization order,
keeping the already-stored value on conflicts — the **first handler
wins**, matching the subscript and the docs.

The multiplex handler's own `metadataProvider` still takes priority over
all underlying handlers/providers, matching its documented role ("runs
after all metadata providers of the multiplexed handlers").

## Testing

- Updated `multiplexLogHandlerMetadata_readingHandlerMetadata` and
`multiplexMetadataProviderSet`, which encoded the last-wins behavior
- Extended `multiplexMetadataProviderSet` with subscript-vs-dictionary
consistency checks (both must give the first handler's value on
conflicting keys, including provider-provided metadata)
- Full suite: 174 tests in 17 suites, all passing

---------

Co-authored-by: awaisdev <awais@airtechsolutions.pk>
Co-authored-by: awaisdev5765 <awaisdev5765@users.noreply.github.com>
Co-authored-by: Vladimir Kukushkin <kukushechkin@apple.com>
2026-11-03 10:57:38 +00:00
Matt Massicotte 209524e4da Remove unnecessary optional so example compiles (#501)
There's an unnecessary optional return here that prevents the example
from compiling.

### Motivation:

It took me a moment to figure out how to fix this, but in the end it was
very straightforward. The `prepareMetadata` doesn't ever need to return
nil.

### Modifications:

A small type change fixes the compilation errors in `log(event:)`

### Result:

The example in the documentation can now be used unmodified.
2026-11-03 10:14:16 +00:00
Krishna Permi c44b210eee Add opt-in millisecond precision to StreamLogHandler timestamp (#483)
`StreamLogHandler` timestamps only have second precision, so when
several log lines land in the same second you can't tell what order they
happened in.

This adds an **opt-in** setting for millisecond precision. The default
output doesn't change, since some users parse it.

**Changes**
- Adds `public var timestampPrecision: TimestampPrecision = .seconds` to
`StreamLogHandler`.
- Adds a nested `TimestampPrecision` enum (`@nonexhaustive`, `Sendable`)
with `.seconds` and `.milliseconds`.
- With `.milliseconds`, the timestamp includes a 3-digit millisecond
field:
  - default (`.seconds`): `2021-11-06T18:47:14+0300 info myapp: message`
  - `.milliseconds`: `2021-11-06T18:47:14.123+0300 info myapp: message`
- How each platform reads the time:
  - Darwin, Linux and Android use `clock_gettime(CLOCK_REALTIME)`.
  - Windows uses `_ftime64_s`.
- WASI only has second resolution (`CLOCK_REALTIME` isn't importable
there), so `.milliseconds` always prints `.000`. The doc comments say
so.
- Both new symbols are added to the DocC reference page.

**Tests**
- The default precision is `.seconds`.
- `.milliseconds` produces the expected format (checked with a regex).
- Milliseconds are always zero-padded to 3 digits.
- The existing output-format tests are unchanged and still pass, which
confirms the default format.

Fixes #212
2026-11-03 09:56:27 +00:00
dependabot[bot] d0f784af9e Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.16 to 0.0.17 (#531)
Bumps
[swiftlang/github-workflows/.github/workflows/soundness.yml](https://github.com/swiftlang/github-workflows)
from 0.0.16 to 0.0.17.
<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.17</h2>
<h2>What's Changed</h2>
<ul>
<li>Add embedded_wasm_sdk_build_command option to swift_package_test by
<a href="https://github.com/jmschonfeld"><code>@​jmschonfeld</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/323">swiftlang/github-workflows#323</a></li>
<li>Update proposal validation workflow to use Swift 6.4 by <a
href="https://github.com/dempseyatgithub"><code>@​dempseyatgithub</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/328">swiftlang/github-workflows#328</a></li>
<li>Soundness: add additional tool arguments input to API breakage check
by <a href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/324">swiftlang/github-workflows#324</a></li>
<li>Add documentation for the Soundness API breakage check by <a
href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/325">swiftlang/github-workflows#325</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a
href="https://github.com/jmschonfeld"><code>@​jmschonfeld</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/323">swiftlang/github-workflows#323</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.16...0.0.17">https://github.com/swiftlang/github-workflows/compare/0.0.16...0.0.17</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/87329d126a6992483ba89aabefa1eaef1e5b0aad"><code>87329d1</code></a>
Add documentation for the Soundness API breakage check (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/325">#325</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/f2b93cfd0a54ad78f875a58c846180f6729f7e28"><code>f2b93cf</code></a>
Soundness: add additional tool arguments input to API breakage check (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/324">#324</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/3a7b5fccc7bb752a47c9ea0a0e605bb774077bc3"><code>3a7b5fc</code></a>
Update proposal validation workflow to use Swift 6.4 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/328">#328</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/c80652d51ee2b4df69e8d0d26d78a9d2ff466ecd"><code>c80652d</code></a>
Add embedded_wasm_sdk_build_command option to swift_package_test (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/323">#323</a>)</li>
<li>See full diff in <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.16...0.0.17">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.16&new-version=0.0.17)](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-10-26 17:39:20 +00:00
om singhal c9c6bb9d27 Mutate the logger's handler in place on metadata writes (#529)
Give `Logger.handler` a `_modify` accessor and replace its `get` with
`_read`, so metadata writes update the stored handler instead of a copy.

### Motivation:

`Logger.handler` only has `get` and `set`. A write such as
`logger[metadataKey: "k"] = "v"` gets a copy of the handler, writes to
it while the stored handler still shares the metadata dictionary, and
sets it back. So every write copies the whole dictionary, and
`withLogger(mergingMetadata:)` does that once per key.

### Modifications:

- Give `Logger.handler` `_read`, `set` and `_modify` accessors. `_read`
yields the stored handler. `_modify` keeps the existing uniqueness check
on the storage and then yields the stored handler, so metadata and log
level writes change it in place. `set` keeps the same check for plain
`logger.handler = newHandler` assignments, which are cheaper through a
setter than through `_modify`.
- Add a test handler that counts copies of its metadata, with tests for
direct writes and for `withLogger(mergingMetadata:)`. Without the change
they report 10 copies instead of 0, and 5 instead of 1.

### Result:

A metadata write on a logger that owns its storage no longer copies the
dictionary. A copied logger still copies once on its first write, so
value semantics are unchanged.

1,000 metadata writes with a handler that keeps metadata in a plain
dictionary, debug build, three runs each:

| Keys on the logger | Before | After |
|---|---|---|
| 10 | 7.2 to 8.1 ms | 0.46 to 0.50 ms |
| 1,000 | 20.2 to 20.6 ms | 0.46 to 0.55 ms |
| 10,000 | 134.0 to 134.4 ms | 0.47 to 0.50 ms |
| 100,000 | 1.29 to 1.30 s | 0.32 to 0.35 ms |

`withLogger(mergingMetadata:)` with 10,000 keys went from 0.64 to 0.65 s
down to 2.9 to 3.1 ms. `StreamLogHandler` still rebuilds its pretty
metadata string on every write; this change does not touch that.

All 176 tests pass on macOS with Swift 6.4, and `swift format lint
--strict` and `swift package diagnose-api-breaking-changes` are clean.
Once yielding accessors land, `_read` and `_modify` can become `yielding
borrow` and `yielding mutate`.

Fixes #526.
2026-10-22 10:30:03 +01:00
dependabot[bot] 6404842475 Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.15 to 0.0.16 (#528)
Bumps
[swiftlang/github-workflows/.github/workflows/soundness.yml](https://github.com/swiftlang/github-workflows)
from 0.0.15 to 0.0.16.
<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.16</h2>
<h2>What's Changed</h2>
<ul>
<li>sha-pin for dependencies-action by <a
href="https://github.com/madrob"><code>@​madrob</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/317">swiftlang/github-workflows#317</a></li>
<li>Update all Swift package test defaults to 6.4 by <a
href="https://github.com/finagolfin"><code>@​finagolfin</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/319">swiftlang/github-workflows#319</a></li>
<li>Fix check-docs.sh failing on macOS when an option has no values by
<a
href="https://github.com/jakepetroules"><code>@​jakepetroules</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/320">swiftlang/github-workflows#320</a></li>
<li>Make CONTRIBUTORS.txt optional in license headers by <a
href="https://github.com/crleonard"><code>@​crleonard</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/268">swiftlang/github-workflows#268</a></li>
<li>Add configurable timeouts for Linux, Static SDK, Wasm, and Android
builds by <a
href="https://github.com/austenstone"><code>@​austenstone</code></a> in
<a
href="https://redirect.github.com/swiftlang/github-workflows/pull/321">swiftlang/github-workflows#321</a></li>
<li>Use the new LTS Android NDK alone for both testing packages and for
workflow pulls here by <a
href="https://github.com/finagolfin"><code>@​finagolfin</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/315">swiftlang/github-workflows#315</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a href="https://github.com/crleonard"><code>@​crleonard</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/268">swiftlang/github-workflows#268</a></li>
<li><a
href="https://github.com/austenstone"><code>@​austenstone</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/321">swiftlang/github-workflows#321</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.15...0.0.16">https://github.com/swiftlang/github-workflows/compare/0.0.15...0.0.16</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/3137ed1a48293ae9f4312fce349ed6210251db89"><code>3137ed1</code></a>
Use the new LTS Android NDK alone for both testing packages and for
workflow ...</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/b9dfa3cb6e7361cac9170478c8569df324683ce6"><code>b9dfa3c</code></a>
Add configurable step timeouts for Linux, Static SDK, Wasm, and Android
build...</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/a0e26726cfe9f46c9eec63f7af64060bb733761f"><code>a0e2672</code></a>
Make CONTRIBUTORS.txt optional in license headers (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/268">#268</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/b9633883fec533530ebd7d5e82ef8ca832c2035f"><code>b963388</code></a>
Fix check-docs.sh failing on macOS when an option has no values (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/320">#320</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/fa1e46cf0f07ffde2de131e9ed5bd66a488c289c"><code>fa1e46c</code></a>
Update all Swift package test defaults to 6.4 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/319">#319</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/81d865a4ea288ffefb0055d23ce4a748a845db20"><code>81d865a</code></a>
sha-pin for dependencies-action (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/317">#317</a>)</li>
<li>See full diff in <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.15...0.0.16">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.15&new-version=0.0.16)](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-10-19 17:33:54 +00:00
Azeem Jiva fcd893317d Update benchmark expectations (#527)
_[One line description of your change]_

### Motivation: 

Update benchmark expectations, with the updated performance level

### Modifications:

Update json file with the new instruction count

### Result:

passing test
2026-10-15 14:56:54 +00:00
Azeem Jiva 65b3417512 Update threshold for GH runner (#525)
_[One line description of your change]_

### Motivation: Update threshold

This allows the faster GitHub runners to pass the benchmark tests.

### Modifications:

Updated threshold to a lower value

### Result:

Passing test
2026-10-13 13:23:02 +00:00
Vladimir Kukushkin 666b45a252 Adjust benchmark expectations (#523)
### Motivation:

Benchmarks CI has been failing recently on Swift 6.3 and 6.4, for
example: https://github.com/apple/swift-log/actions/runs/38083241726.
The results are actually better than expected in the thresholds.

### Modifications:

- Swift 6.3
MaxLogLevelNone.critical_log_with_critical_log_level_metadata_set.p90.json
threshold reduced
- Swift 6.4
MaxLogLevelWarning.notice_log_with_notice_log_level_attributed_generic.p90.json
threshold reduced

### Result:

CI should not fail anymore.
2026-10-13 12:03:23 +01:00
Chris Leonard 4038b6a4f7 Fix metadata provider handling when multiplexing log events (#522)
Ensure metadata from the multiplex handler’s own provider reaches
emitted logs.

Fixes #521.

## Motivation

`MultiplexLogHandler` accepts a metadata provider in its initializer,
but `log(event:)` never invokes it. Provider values such as trace IDs
are therefore missing from downstream logs.

## Modifications

- Merge the multiplex provider’s metadata into the event before
forwarding it.
- Preserve explicit per-message metadata overrides.
- Add regression tests covering one and two downstream handlers and
metadata precedence.

## Result

The supplied provider’s metadata is included in emitted logs.

Regression tests fail before the fix and pass afterward. All 174 tests
pass on macOS with Swift 6.4. Formatting and `git diff --check` also
pass.
2026-10-07 15:03:40 +00:00
Chris Leonard 109c380c23 Fix explicit log level when replacing a task-local logger's handler (#520)
Fixes #519.

## Motivation

When both `logLevel` and `handler` are provided, `withLogger` sets the
level on the current handler before replacing it. Since
`Logger.logLevel` forwards to the handler, the replacement discards the
requested level and uses its own instead.

## Modifications

- Install the replacement handler before applying the explicit log level
in both sync and async overloads.
- Add regression tests for `.debug` and `.warning` in both overloads,
covering filtering and scope isolation.

## Result

The scoped logger filters messages at the requested level.

Regression tests fail before the fix and pass afterward. All 172 tests
pass on macOS with Swift 6.4. Formatting and `git diff --check` also
pass.
2026-10-07 10:47:39 +01:00
Vladimir Kukushkin c29472f010 Bump minimal Swift tools version to 6.2 (#518)
The support window is 3 latest minor Swift versions. CI i already
running for Swift 6.2, 6.3 and 6.4 only. Updating the Swift tools and
the package to match this.
2026-10-02 16:39:23 +00:00
dependabot[bot] bca880e799 Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.13 to 0.0.15 (#502)
Bumps
[swiftlang/github-workflows/.github/workflows/soundness.yml](https://github.com/swiftlang/github-workflows)
from 0.0.13 to 0.0.15.
<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.15</h2>
<h2>What's Changed</h2>
<ul>
<li>Add install cmake action by <a
href="https://github.com/etcwilde"><code>@​etcwilde</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/310">swiftlang/github-workflows#310</a></li>
<li>Increase PR url download retry by <a
href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/311">swiftlang/github-workflows#311</a></li>
<li>Make Windows CI fail when command fails to launch by <a
href="https://github.com/snprajwal"><code>@​snprajwal</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/307">swiftlang/github-workflows#307</a></li>
<li>Adding Reusable CMake build workflow by <a
href="https://github.com/etcwilde"><code>@​etcwilde</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/313">swiftlang/github-workflows#313</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a href="https://github.com/etcwilde"><code>@​etcwilde</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/310">swiftlang/github-workflows#310</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.14...0.0.15">https://github.com/swiftlang/github-workflows/compare/0.0.14...0.0.15</a></p>
<h2>0.0.14</h2>
<h2>What's Changed</h2>
<ul>
<li>Group dependabot updates for GHA workflows by <a
href="https://github.com/snprajwal"><code>@​snprajwal</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/302">swiftlang/github-workflows#302</a></li>
<li>Run linux pre-build commands as part of the API breakage step by <a
href="https://github.com/josephnoir"><code>@​josephnoir</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/304">swiftlang/github-workflows#304</a></li>
<li>swift_package_test: Switch to using Swift version-based symlinks by
<a href="https://github.com/lorentey"><code>@​lorentey</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/309">swiftlang/github-workflows#309</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a
href="https://github.com/josephnoir"><code>@​josephnoir</code></a> made
their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/304">swiftlang/github-workflows#304</a></li>
<li><a href="https://github.com/lorentey"><code>@​lorentey</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/309">swiftlang/github-workflows#309</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.13...0.0.14">https://github.com/swiftlang/github-workflows/compare/0.0.13...0.0.14</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/9a10bfdc569159a3463f1273fbd7ed5f97fbe598"><code>9a10bfd</code></a>
Adding Reusable CMake build workflow (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/313">#313</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/baf2598563ae0cadfebf37e353f13bf3db3702b1"><code>baf2598</code></a>
Fix Windows CI passing when a command fails to launch (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/307">#307</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/455afa1d1d36cb7e8884553ea5d808117f8786af"><code>455afa1</code></a>
Increase PR url download retry (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/311">#311</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/f8c5dc13ff142addb79fb622d4a6e2802b26cf38"><code>f8c5dc1</code></a>
Add install cmake action (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/310">#310</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/152252f6e4b45fa96d48f1cbefaa351a7389fc2c"><code>152252f</code></a>
swift_package_test: Switch to using Swift version-based symlinks (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/309">#309</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/497d9ab8410e69981b3b2f28da24cf7bf4b8733d"><code>497d9ab</code></a>
Inline pre-build command into API breakage check step (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/304">#304</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/6af5655d925c8ff204383ff0a22e9baea895c4c5"><code>6af5655</code></a>
Group dependabot updates for GHA workflows (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/302">#302</a>)</li>
<li>See full diff in <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.13...0.0.15">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.13&new-version=0.0.15)](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-10-01 12:43:23 +00:00
Vladimir Kukushkin c581740960 Add Swift 6.4 and disable 6.1 in CI configuration (#517)
Add Swift 6.4 and disable 6.1 in CI configuration.
2026-10-01 13:13:54 +02:00
Vladimir Kukushkin 9c9acde6dc Fix nested metadata values handling (#516)
Only quote leaf metadata values.

### Motivation:

There are several issues with how nested `MetadataValue`s are handled:
1. For highly nested (10k+) metadata, `.description` and `==` operator
hit stack overflow. This is probably not very realistic depth, but
still.
2. For not so highly nested metadata (starting at about 20)
`.description` and `==` operator get very computationally intensive
because of re-escaping of the already escaped children. This makes the
above stack overflow crash not reachable in practice.
3. This also results in simple structured metadata to be rendered
something like
`["[\"[\\\"[\\\\\\\"[\\\\\\\\\\\\\\\"leaf\\\\\\\\\\\\\\\"]\\\\\\\"]\\\"]\"]"]`.
4. Finally, even after solving the re-quoting and stack over flow on
rendering, there is still an issue of [recursion in
`.deinit`](https://github.com/swiftlang/swift/issues/58080), resulting
in a _different_ stack overflow crash.

This PR provides a fix for 2 and 3, leaving 1 and 4 out because there is
no practical way of fixing it in this package, while the case is
borderline unrealistic.

### Modifications:

- Only quote left `String` and `StringRepresentable` values in
`Logger.MetadataValue.description`.
- Add benchmarks for metadata values description rendering.

### Result:

100 nested metadata values render cleanly. 

Resolves #515 

### Alternatives

This is discussable if this fix is really necessary. Iterative approach,
because of allocations, is slower than recursion.
- Is it worth fixing the recursion, or a metadata depth check is enough?
- Is it worth fixing the nested metadata formatting?
2026-09-23 10:13:24 +01:00
mitra cf3e828428 Remove invalid exclude statements from testTarget (#514)
I removed the stale exclude statements from `Package.swift` and
`Package@swift-6.1.swift`

### Motivation:

In #485, CMake build support was added, as part of it, 99c554b added
`exclude: ["CMakeLists.txt"]` to all four SwiftPM targets, including
tests, but the CI was revealing some issues with CMake test-targets. So
after review, in 4a81108 the CMake build files were removed from the
`/Tests` directory but I accidentally left behind the exclusions in the
package manifests.

### Modifications:

Removed the exclude statements from Package.swift and
Package@swift-6.1.swift.

### Result:

No SwiftPM errors!

Fixes: #513
2026-09-17 16:31:04 +00:00
mitraandVladimir Kukushkin 3be27be290 Update stale package names and broken ordo-one/benchmark documentation links (#511)
I updated the `CONTRIBUTING.md` documentation to fix the outdated name
for the benchmarking plugin. The instructions now reference the
`benchmark` plugin instead of the previously outdated
`package-benchmark` plugin, and associated links and descriptions have
been updated accordingly. Previously these were leading to `404 Not
Found` errors.

No code changes were made in this PR.

Fixes: #510

---------

Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-09-16 14:51:18 +00:00
Honza Dvorsky 9c6fb14227 Fix referencing WASILibc.stdout/stderr in Swift 6.5+ (#507)
### Motivation:

Nightly CI on nightly-main toolchains started failing on August 11, when
we started downloading swift-DEVELOPMENT-SNAPSHOT-2026-08-08 instead of
swift-DEVELOPMENT-SNAPSHOT-2026-07-11.

Appears to be fallout from
https://github.com/swiftlang/swift/commit/73fee3394d3102847fef26c1bdea49a67061f043
improving the optionality and concurrency of stdout/stderr/stdin on the
various platforms.

### Modifications:

Adapted Swift Log code to handle both the existing and behavior, guarded
by a `compiler(>=6.5)`

Also enabled nightly-next, which tracks the pre-release 6.4 right now,
but hasn't received this change.

### Result:

Passing CI, hopefully :)
2026-09-08 11:02:37 +01:00
Jeff LenamonandVladimir Kukushkin 53d00853e6 Route the SwiftLog 1.0 default log method to log(event:) (#503)
### Motivation:

The two deprecated `LogHandler` defaults forward to each other: the
source-carrying `log(level:message:metadata:source:file:function:line:)`
default calls `log(event:)`, whose default calls the source-carrying
method, and the SwiftLog 1.0
`log(level:message:metadata:file:function:line:)` default calls the
source-carrying method. A handler that implements only `log(event:)`, as
the protocol documentation asks, therefore recurses until the stack
overflows whenever anything calls the 1.0 method on it. Handlers written
against SwiftLog 1.0 that wrap another handler and forward through the
1.0 method reach this path.

Differs from #248, where the handler implemented no log method at all.

### Modifications:

The 1.0 default builds a `LogEvent` and calls `log(event:)` directly.
The source is still the module derived from `file`, as before. Two tests
in `CompatibilityTest`: the 1.0 method reaching an event-only handler
(SIGSEGV at `main` before the change) and reaching a source-only
handler.

### Result:

A `LogHandler` implementing only `log(event:)` can be called through
every deprecated entry point. No source-breaking change; both deprecated
defaults remain.

Verified on Linux with Swift 6.1.2: `swift test -Xswiftc
-warnings-as-errors --explicit-target-dependency-import-check error
-Xswiftc -require-explicit-sendable` (166 tests) and `swift-format lint
--strict` on the changed files.

Found by an automated audit loop (Claude); patch and description
reviewed by me.

---------

Co-authored-by: Vladimir Kukushkin <kukushechkin@apple.com>
2026-09-07 13:29:33 +01:00
Jeff Lenamon c5ece24786 Document that setting attributes on a collection value is a programmer error (#504)
### Motivation:

`Logger.MetadataValue.attributes` documents the setter as a no-op for
`.dictionary` and `.array`, but it calls `assertionFailure` there. Debug
builds trap, release builds do the documented no-op.

### Modifications:

Doc comment only. The assertion stays; the comment now says setting
attributes on a collection value is a programmer error, that debug
builds assert and release builds leave the value unchanged, and to set
attributes on the leaf values instead.

### Result:

The documentation matches the code. No behaviour change.

Found by an automated audit loop (Claude); patch and description
reviewed by me.
2026-09-04 09:08:57 +00:00
Honza Dvorsky 172948a4b5 Disable simulator testing due to instability (#505)
### Motivation:

Unblock nightly CI runs on main by disabling non-macOS Apple platform
simulator testing due to instability.

### Modifications:

Disabled that CI for now. We'll re-enable when we can make it pass
reliably.

### Result:

Bring nightly CI back to green.
2026-09-03 16:56:49 +00:00
mitra 47a917767f Add CMake build instructions to README (#493)
Add CMake build instructions for macOS, Windows and Linux including
requirements and installation steps.

### Motivation:

Document how to build SwiftLog with CMake for projects that use mixed
build systems and need integration outside of Swift Package Manager.

### Modifications:

- Added a new “Building with CMake” section to `README.md`
- Documented minimum requirements:
  - Swift 6.1+
  - CMake 3.19+
  - Ninja 1.10+
- Added macOS build examples for both Xcode and Ninja generators
- Added Windows build instructions using Ninja
- Added install instructions and notes about shared vs. static builds
- Clarified that tests are not included in the CMake build and are still
managed through Swift Package Manager


### Result:

Users now have platform-specific guidance for building SwiftLog with
CMake on macOS, Windows and Linux.

Fixes #492
2026-08-12 13:49:22 +00:00
Vladimir Kukushkin f054da4c19 Update benchmark thresholds values to match the CI (#497)
### Motivation:

Swift 6.3 benchmarks have been failing for a while now

### Modifications:

- Update 2 benchmark thresholds to match values for Swift 6.3.
- Update thresholds files formatting to reduce noise in the output diff.

### Result:

Benchmarks should not fail sporadically.
2026-08-05 13:35:50 +01:00
Vladimir Kukushkin 3ffafb9722 Make ReadWriteLock.init internal (#496)
### Motivation:

`public` init has no effect for an `internal` class.

### Modifications:

Removed `public` from the `ReadWriteLock.init`.

### Result:

`ReadWriteLock.init` is now `internal`, matching class visibility.
2026-08-04 14:02:34 +02:00
Vladimir KukushkinandJoseph Heck 7af2de138f Document how to construct log handlers that need more than a label (#490)
Document best practice for creating complex `LogHandlers`. 

### Motivation:

`LogHandler`s often need an expensive resource to write or export log
events. This pattern should be documented.

### Modifications:

Add "Constructing handlers that need more than a label" section to
`ImplementingALogHandler.md` guide.

### Result:

Closes #80.

---------

Co-authored-by: Joseph Heck <j_heck@apple.com>
2026-07-24 17:59:05 +01:00
mitraandVladimir Kukushkin e83726cb15 Add CMake support for Swift targets and test configurations (#485)
Add CMake build support to the project to enable toolchain integration
and bootstrapping compatibility.

### Motivation:

Currently, swift-log does not support building with CMake. This addition
resolves issue #484, allowing swift-log to be resolved and compiled
within CMake-based environments (like the repos swift-certificates and
swift-argument-parser which aer mentioned in the issue).

### Modifications:

1. **Project Root Config:** Added
[CMakeLists.txt](file:///Users/adityamitra/Developer/swift-log/CMakeLists.txt)
configuring the CMake project with Swift 6 and C, alongside setting up
compiler flags for MSVC runtime library on Windows.
2. **Helper Modules:** Added the `cmake/` folder:
- `SwiftSupport.cmake`: dylib/module installations and triple detection
helper.
   - `SwiftLogConfig.cmake.in`: package config export templates.
3. **Target CMake Configurations:** Created
[Sources/Logging/CMakeLists.txt](file:///Users/adityamitra/Developer/swift-log/Sources/Logging/CMakeLists.txt)
&
[Sources/InMemoryLogging/CMakeLists.txt](file:///Users/adityamitra/Developer/swift-log/Sources/InMemoryLogging/CMakeLists.txt)
to define the library targets. Included generator expressions pointing
`INTERFACE_INCLUDE_DIRECTORIES` to target output directories for Xcode
generator support.
4. **SwiftPM Exclusions:** Excluded the new CMake files from target
targets inside
[Package.swift](file:///Users/adityamitra/Developer/swift-log/Package.swift)
and
[Package@swift-6.1.swift](file:///Users/adityamitra/Developer/swift-log/Package@swift-6.1.swift)
to keep SwiftPM targets warning-free.
5. **Compile Options Variable:** Consolidates compile options under a
single global definition `SWIFT_LOG_COMMON_COMPILE_OPTIONS` in the root
configuration, enabling Swift 6 compiler features (`ExistentialAny`,
`MemberImportVisibility`, `InternalImportsByDefault`,
`NonisolatedNonsendingByDefault`, and explicit Sendable checks) across
all targets.
6. **CI Integration & Workflow:** Integrated CMake CI validation in
`.github/workflows/pull_request.yml` using the shared workflow from
`apple/swift-nio/.github/workflows/cmake_tests.yml@main` running in a
`swift:6.1-jammy` container. This job compiles the core libraries and
verifies the validity of the CMake files.
7. **License Header Compliance:** Cleaned up license headers across all
CMake files

### Result:

* **SwiftPM:** All 164 unit tests compile and pass successfully under
`swift test` with no warnings.
* **CMake:** Successfully compiles (`** BUILD SUCCEEDED **`) under Xcode
generator (`cmake -B build -G Xcode && cmake --build build`).

### Issue Tracking:
Fixes #484

---------

Co-authored-by: Vladimir Kukushkin <kukushechkin@apple.com>
2026-07-22 17:25:43 +01:00
dependabot[bot] 8056dbfb08 Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.12 to 0.0.13 (#486) 2026-07-14 17:36:30 +00:00
dependabot[bot] 1032aed8a5 Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.11 to 0.0.12 (#480)
Bumps
[swiftlang/github-workflows/.github/workflows/soundness.yml](https://github.com/swiftlang/github-workflows)
from 0.0.11 to 0.0.12.
<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.12</h2>
<h2>What's Changed</h2>
<ul>
<li>Bump gregsdennis/dependencies-action from 1.4.1 to 1.4.2 by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/266">swiftlang/github-workflows#266</a></li>
<li>extract PR Dependency Check for github-workflows into its own file
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/270">swiftlang/github-workflows#270</a></li>
<li>Remove workaround for bug triggered by Android environment variable
by <a href="https://github.com/finagolfin"><code>@​finagolfin</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/246">swiftlang/github-workflows#246</a></li>
<li>Change default Android SDK build command by <a
href="https://github.com/jakepetroules"><code>@​jakepetroules</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/269">swiftlang/github-workflows#269</a></li>
<li>[static sdk] build with sdk triple 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/274">swiftlang/github-workflows#274</a></li>
<li>[freebsd] cd into the proper dir to run package test 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/275">swiftlang/github-workflows#275</a></li>
<li>Update Wasm build command in workflow by <a
href="https://github.com/jakepetroules"><code>@​jakepetroules</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/272">swiftlang/github-workflows#272</a></li>
<li>Android: Add support for .bundle files in emulator tests by <a
href="https://github.com/jakepetroules"><code>@​jakepetroules</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/276">swiftlang/github-workflows#276</a></li>
<li>Update Swift nightly to 6.4.x in workflow file by <a
href="https://github.com/shahmishal"><code>@​shahmishal</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/278">swiftlang/github-workflows#278</a></li>
<li>Parametrize swift format binary by <a
href="https://github.com/rnro"><code>@​rnro</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/285">swiftlang/github-workflows#285</a></li>
<li>Extend ignore list in flake8 config by <a
href="https://github.com/snprajwal"><code>@​snprajwal</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/279">swiftlang/github-workflows#279</a></li>
<li>Fix Android build for non-default NDKs with new swift-build build
system, by updating ANDROID_NDK_ROOT too by <a
href="https://github.com/finagolfin"><code>@​finagolfin</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/280">swiftlang/github-workflows#280</a></li>
<li>docs: add missing closing backtick in error message by <a
href="https://github.com/Avicennasis"><code>@​Avicennasis</code></a> in
<a
href="https://redirect.github.com/swiftlang/github-workflows/pull/286">swiftlang/github-workflows#286</a></li>
<li>Add retry when retrieving PR information by <a
href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/284">swiftlang/github-workflows#284</a></li>
<li>Docs: provide option to skip analysis in doc-check by <a
href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/282">swiftlang/github-workflows#282</a></li>
<li>Add proposal validation workflow and documentation by <a
href="https://github.com/dempseyatgithub"><code>@​dempseyatgithub</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/288">swiftlang/github-workflows#288</a></li>
<li>Update dock check syntax issue by <a
href="https://github.com/bkhouri"><code>@​bkhouri</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/290">swiftlang/github-workflows#290</a></li>
<li>Update actions/checkout to v7 by <a
href="https://github.com/shahmishal"><code>@​shahmishal</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/294">swiftlang/github-workflows#294</a></li>
<li>Update default Xcode versions in workflow to Xcode 27 Beta 2 by <a
href="https://github.com/shahmishal"><code>@​shahmishal</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/293">swiftlang/github-workflows#293</a></li>
<li>Add GITHUB_TOKEN env variable for use by extraction tool by <a
href="https://github.com/dempseyatgithub"><code>@​dempseyatgithub</code></a>
in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/295">swiftlang/github-workflows#295</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/266">swiftlang/github-workflows#266</a></li>
<li><a href="https://github.com/snprajwal"><code>@​snprajwal</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/279">swiftlang/github-workflows#279</a></li>
<li><a
href="https://github.com/Avicennasis"><code>@​Avicennasis</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/286">swiftlang/github-workflows#286</a></li>
<li><a
href="https://github.com/dempseyatgithub"><code>@​dempseyatgithub</code></a>
made their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/288">swiftlang/github-workflows#288</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.11...0.0.12">https://github.com/swiftlang/github-workflows/compare/0.0.11...0.0.12</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/07936268efedce0a6650c75a00150b820f53f384"><code>0793626</code></a>
Add GITHUB_TOKEN env variable for use by extraction tool (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/295">#295</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/1ec62c90c3b8a07150ec8233eb4cb170aeee7eab"><code>1ec62c9</code></a>
Update default Xcode versions in workflow to Xcode 27 Beta 2 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/293">#293</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/fda56f671cbba58575549aedd1f07ff75a28949b"><code>fda56f6</code></a>
Update actions/checkout to v7 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/294">#294</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/60789377b41faf8c0f0aa6e42948b5fa3131a4d9"><code>6078937</code></a>
Update dock check syntax issue (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/290">#290</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/d65527ae024104f80c3c9a204e2255ff6e6dbf24"><code>d65527a</code></a>
Add proposal validation workflow and documentation (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/288">#288</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/b080ab5eaa2d71849e212ec6ffed6e2757791c3d"><code>b080ab5</code></a>
Docs: provide option to skip analysis in doc-check (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/282">#282</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/9abcbf258bca0c8d2157b1bdad4193381f97a866"><code>9abcbf2</code></a>
Add retry when retrieving PR information (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/284">#284</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/8a9e053779acdc244e72dc947fa17c620f671235"><code>8a9e053</code></a>
docs: add missing closing backtick in error message (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/286">#286</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/0a4e35d4b3892988d1b6a24c1fb4281800e5a6d4"><code>0a4e35d</code></a>
Fix Android build for non-default NDKs with new swift-build build
system, by ...</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/cad6f2b75ecfb5813ed8210678c12d307090d930"><code>cad6f2b</code></a>
Extend ignore list in flake8 config (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/279">#279</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.11...0.0.12">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.11&new-version=0.0.12)](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-06-30 11:31:35 +02:00
Subhramit BasuandVladimir Kukushkin 1895d78a91 Make StreamLogHandler initializers public (#477)
Make `StreamLogHandler` initializers public.

### Motivation:

Closes https://github.com/apple/swift-log/issues/273

### Modifications:

Promote the two stream-accepting initializers from `internal` to
`public`. Also as a result, their stream parameter is spelled out as
`any TextOutputStream & Sendable` rather than the internal
`_SendableTextOutputStream` typealias, which cannot appear in a public
signature. ~The private stored property and the internal typealias are
otherwise unchanged.~ The internal typealias has been completely removed
as it was only used to store the stream, and the private stored property
is updated to use the spelled-out type.

Also updates the docc documentation accordingly.

### Result:

Users would be able to construct a `StreamLogHandler` with their own
`TextOutputStream` implementation, reusing the existing logic to format
log messages and prettify metadata instead of reimplementing them.

---------

Signed-off-by: subhramit <subhramit.bb@live.in>
Co-authored-by: Vladimir Kukushkin <kukushechkin@apple.com>
2026-06-25 16:24:26 +01:00
Vladimir KukushkinandJoseph Heck 8a6b9eab84 Add testing logs best practice (#475)
Add a Best Practice guide on how to test logging.

### Motivation:

There are 2 recommended ways of propagating logs in components, both are
testable. But there is no any kind of documentation on how to do it.

### Modifications:

Add a "Testing code that logs" Best Practice guide.

### Result:

Logs testing is now documented.

---------

Co-authored-by: Joseph Heck <j_heck@apple.com>
2026-06-25 11:23:03 +01:00
Joseph HeckandVladimir Kukushkin c4e96785bf Add missing api refs (#478)
Expands on @kukushechkin #474 (add-missing API) and tacks in some
additional work

### Motivation:

resolve the DocC warnings

### Modifications:

- resolves docc warnings for soundness checks 
- updates curation to drop the task-local logger updates into the
correct areas
- updates curation to collect the implemented proposals together

### Result:

Hopefully no issues with soundness checks

---------

Co-authored-by: Vladimir Kukushkin <kukushechkin@apple.com>
2026-06-25 11:00:42 +01:00
Vladimir Kukushkin 54ec9e35cd Update implemented proposals status (#476)
Match proposals status in the docs and the implementation reality.
2026-06-24 16:51:39 +01:00
Vladimir Kukushkin e3b5d65fc9 Enable Xcode tests (#473)
Simulators seem to have stabilized in CI, we can enabled the tests.

### Motivation:

`swift-log` is expected to be used on various platforms, we should run
tests against them.

### Modifications:

- Run tests on various tests in simulators in PRs and nightly.
- Fix tests to actually compile there.

### Result:

Tests are now running in simulators. Supersedes #431.
2026-06-24 13:42:03 +02:00
Vladimir KukushkinandFranz Busch a878e7f8f4 [SLG-0006]: task-local logger implementation (#459)
This proposal adds task-local logger storage so that metadata can
accumulate across async
call stacks without threading a `Logger` through every function
signature.

### Motivation:

Metadata propagation requires threading a logger through every layer.
Every function on
the path from request ingress to the bottom of the call stack has to
accept, mutate, and
forward a `Logger`. Libraries must choose between polluting their public
API with a `logger:` parameter and
losing all the caller's context. There is no third option today.

### Modifications:

- New API surface for reading and modifying the `@TaskLocal` `Logger`
instance added.
- Best practices on how to correctly propagate logger into libraries
updated with `Logger.current` API.

### Result:

Users can now automatically propagate accumulated metadata into
libraries without explicitly passing loggers through the API boundaries.

---------

Co-authored-by: Franz Busch <privat@franz-busch.de>
2026-06-23 15:15:37 +01:00
dependabot[bot] 2c52ee25d2 Bump actions/checkout from 6 to 7 (#472)
Bumps [actions/checkout](https://github.com/actions/checkout) from 6 to
7.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/actions/checkout/releases">actions/checkout's
releases</a>.</em></p>
<blockquote>
<h2>v7.0.0</h2>
<h2>What's Changed</h2>
<ul>
<li>block checking out fork pr for pull_request_target and workflow_run
by <a href="https://github.com/aiqiaoy"><code>@​aiqiaoy</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2454">actions/checkout#2454</a></li>
<li>Bump actions/publish-immutable-action from 0.0.3 to 0.0.4 in the
minor-actions-dependencies group across 1 directory by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2458">actions/checkout#2458</a></li>
<li>Bump flatted from 3.3.1 to 3.4.2 by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2460">actions/checkout#2460</a></li>
<li>Bump js-yaml from 4.1.0 to 4.2.0 by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2461">actions/checkout#2461</a></li>
<li>Bump <code>@​actions/core</code> and
<code>@​actions/tool-cache</code> and Remove uuid by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2459">actions/checkout#2459</a></li>
<li>upgrade module to esm and update dependencies by <a
href="https://github.com/aiqiaoy"><code>@​aiqiaoy</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2463">actions/checkout#2463</a></li>
<li>Bump the minor-npm-dependencies group across 1 directory with 3
updates by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2462">actions/checkout#2462</a></li>
<li>getting ready for checkout v7 release by <a
href="https://github.com/aiqiaoy"><code>@​aiqiaoy</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2464">actions/checkout#2464</a></li>
<li>update error wording by <a
href="https://github.com/aiqiaoy"><code>@​aiqiaoy</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2467">actions/checkout#2467</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a href="https://github.com/aiqiaoy"><code>@​aiqiaoy</code></a> made
their first contribution in <a
href="https://redirect.github.com/actions/checkout/pull/2454">actions/checkout#2454</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/actions/checkout/compare/v6.0.3...v7.0.0">https://github.com/actions/checkout/compare/v6.0.3...v7.0.0</a></p>
<h2>v6.0.3</h2>
<h2>What's Changed</h2>
<ul>
<li>Update changelog by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2357">actions/checkout#2357</a></li>
<li>fix: expand merge commit SHA regex and add SHA-256 test cases by <a
href="https://github.com/yaananth"><code>@​yaananth</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2414">actions/checkout#2414</a></li>
<li>Fix checkout init for SHA-256 repositories by <a
href="https://github.com/yaananth"><code>@​yaananth</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2439">actions/checkout#2439</a></li>
<li>Update changelog for v6.0.3 by <a
href="https://github.com/yaananth"><code>@​yaananth</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2446">actions/checkout#2446</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a href="https://github.com/yaananth"><code>@​yaananth</code></a>
made their first contribution in <a
href="https://redirect.github.com/actions/checkout/pull/2414">actions/checkout#2414</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/actions/checkout/compare/v6...v6.0.3">https://github.com/actions/checkout/compare/v6...v6.0.3</a></p>
<h2>v6.0.2</h2>
<h2>What's Changed</h2>
<ul>
<li>Add orchestration_id to git user-agent when ACTIONS_ORCHESTRATION_ID
is set by <a
href="https://github.com/TingluoHuang"><code>@​TingluoHuang</code></a>
in <a
href="https://redirect.github.com/actions/checkout/pull/2355">actions/checkout#2355</a></li>
<li>Fix tag handling: preserve annotations and explicit fetch-tags by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2356">actions/checkout#2356</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/actions/checkout/compare/v6.0.1...v6.0.2">https://github.com/actions/checkout/compare/v6.0.1...v6.0.2</a></p>
<h2>v6.0.1</h2>
<h2>What's Changed</h2>
<ul>
<li>Update all references from v5 and v4 to v6 by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2314">actions/checkout#2314</a></li>
<li>Add worktree support for persist-credentials includeIf by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2327">actions/checkout#2327</a></li>
<li>Clarify v6 README by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2328">actions/checkout#2328</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/actions/checkout/compare/v6...v6.0.1">https://github.com/actions/checkout/compare/v6...v6.0.1</a></p>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/actions/checkout/blob/main/CHANGELOG.md">actions/checkout's
changelog</a>.</em></p>
<blockquote>
<h1>Changelog</h1>
<h2>v7.0.0</h2>
<ul>
<li>Block checking out fork PR for pull_request_target and workflow_run
by <a href="https://github.com/aiqiaoy"><code>@​aiqiaoy</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2454">actions/checkout#2454</a></li>
<li>Bump actions/publish-immutable-action from 0.0.3 to 0.0.4 in the
minor-actions-dependencies group across 1 directory by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2458">actions/checkout#2458</a></li>
<li>Bump flatted from 3.3.1 to 3.4.2 by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2460">actions/checkout#2460</a></li>
<li>Bump js-yaml from 4.1.0 to 4.2.0 by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2461">actions/checkout#2461</a></li>
<li>Bump <code>@​actions/core</code> and
<code>@​actions/tool-cache</code> and Remove uuid by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2459">actions/checkout#2459</a></li>
<li>upgrade module to esm and update dependencies by <a
href="https://github.com/aiqiaoy"><code>@​aiqiaoy</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2463">actions/checkout#2463</a></li>
<li>Bump the minor-npm-dependencies group across 1 directory with 3
updates by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/actions/checkout/pull/2462">actions/checkout#2462</a></li>
</ul>
<h2>v6.0.3</h2>
<ul>
<li>Fix checkout init for SHA-256 repositories by <a
href="https://github.com/yaananth"><code>@​yaananth</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2439">actions/checkout#2439</a></li>
<li>fix: expand merge commit SHA regex and add SHA-256 test cases by <a
href="https://github.com/yaananth"><code>@​yaananth</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2414">actions/checkout#2414</a></li>
</ul>
<h2>v6.0.2</h2>
<ul>
<li>Fix tag handling: preserve annotations and explicit fetch-tags by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2356">actions/checkout#2356</a></li>
</ul>
<h2>v6.0.1</h2>
<ul>
<li>Add worktree support for persist-credentials includeIf by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2327">actions/checkout#2327</a></li>
</ul>
<h2>v6.0.0</h2>
<ul>
<li>Persist creds to a separate file by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2286">actions/checkout#2286</a></li>
<li>Update README to include Node.js 24 support details and requirements
by <a href="https://github.com/salmanmkc"><code>@​salmanmkc</code></a>
in <a
href="https://redirect.github.com/actions/checkout/pull/2248">actions/checkout#2248</a></li>
</ul>
<h2>v5.0.1</h2>
<ul>
<li>Port v6 cleanup to v5 by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2301">actions/checkout#2301</a></li>
</ul>
<h2>v5.0.0</h2>
<ul>
<li>Update actions checkout to use node 24 by <a
href="https://github.com/salmanmkc"><code>@​salmanmkc</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2226">actions/checkout#2226</a></li>
</ul>
<h2>v4.3.1</h2>
<ul>
<li>Port v6 cleanup to v4 by <a
href="https://github.com/ericsciple"><code>@​ericsciple</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2305">actions/checkout#2305</a></li>
</ul>
<h2>v4.3.0</h2>
<ul>
<li>docs: update README.md by <a
href="https://github.com/motss"><code>@​motss</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/1971">actions/checkout#1971</a></li>
<li>Add internal repos for checking out multiple repositories by <a
href="https://github.com/mouismail"><code>@​mouismail</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/1977">actions/checkout#1977</a></li>
<li>Documentation update - add recommended permissions to Readme by <a
href="https://github.com/benwells"><code>@​benwells</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2043">actions/checkout#2043</a></li>
<li>Adjust positioning of user email note and permissions heading by <a
href="https://github.com/joshmgross"><code>@​joshmgross</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2044">actions/checkout#2044</a></li>
<li>Update README.md by <a
href="https://github.com/nebuk89"><code>@​nebuk89</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2194">actions/checkout#2194</a></li>
<li>Update CODEOWNERS for actions by <a
href="https://github.com/TingluoHuang"><code>@​TingluoHuang</code></a>
in <a
href="https://redirect.github.com/actions/checkout/pull/2224">actions/checkout#2224</a></li>
<li>Update package dependencies by <a
href="https://github.com/salmanmkc"><code>@​salmanmkc</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/2236">actions/checkout#2236</a></li>
</ul>
<h2>v4.2.2</h2>
<ul>
<li><code>url-helper.ts</code> now leverages well-known environment
variables by <a href="https://github.com/jww3"><code>@​jww3</code></a>
in <a
href="https://redirect.github.com/actions/checkout/pull/1941">actions/checkout#1941</a></li>
<li>Expand unit test coverage for <code>isGhes</code> by <a
href="https://github.com/jww3"><code>@​jww3</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/1946">actions/checkout#1946</a></li>
</ul>
<h2>v4.2.1</h2>
<ul>
<li>Check out other refs/* by commit if provided, fall back to ref by <a
href="https://github.com/orhantoy"><code>@​orhantoy</code></a> in <a
href="https://redirect.github.com/actions/checkout/pull/1924">actions/checkout#1924</a></li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/actions/checkout/commit/9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0"><code>9c091bb</code></a>
update error wording (<a
href="https://redirect.github.com/actions/checkout/issues/2467">#2467</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/1044a6dea927916f2c38ba5aeffbc0a847b1221a"><code>1044a6d</code></a>
getting ready for checkout v7 release (<a
href="https://redirect.github.com/actions/checkout/issues/2464">#2464</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/f0282184c7ce73ab54c7e4ab5a617122602e575f"><code>f028218</code></a>
Bump the minor-npm-dependencies group across 1 directory with 3 updates
(<a
href="https://redirect.github.com/actions/checkout/issues/2462">#2462</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/d914b262ffc244530a203ab40decab34c3abf34d"><code>d914b26</code></a>
upgrade module to esm and update dependencies (<a
href="https://redirect.github.com/actions/checkout/issues/2463">#2463</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/537c7ef99cef6e5ddb5e7ff5d16d14510503801d"><code>537c7ef</code></a>
Bump <code>@​actions/core</code> and <code>@​actions/tool-cache</code>
and Remove uuid (<a
href="https://redirect.github.com/actions/checkout/issues/2459">#2459</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/130a169078a413d3a5246a393625e8e742f387f6"><code>130a169</code></a>
Bump js-yaml from 4.1.0 to 4.2.0 (<a
href="https://redirect.github.com/actions/checkout/issues/2461">#2461</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/7d09575332117a40b46e5e020664df234cd416f3"><code>7d09575</code></a>
Bump flatted from 3.3.1 to 3.4.2 (<a
href="https://redirect.github.com/actions/checkout/issues/2460">#2460</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/0f9f3aa320cb53abeb534aeb54048075d9697a0e"><code>0f9f3aa</code></a>
Bump actions/publish-immutable-action (<a
href="https://redirect.github.com/actions/checkout/issues/2458">#2458</a>)</li>
<li><a
href="https://github.com/actions/checkout/commit/f9e715a95fcd1f9253f77dd28f11e88d2d6460c7"><code>f9e715a</code></a>
block checking out fork pr for pull_request_target and workflow_run (<a
href="https://redirect.github.com/actions/checkout/issues/2454">#2454</a>)</li>
<li>See full diff in <a
href="https://github.com/actions/checkout/compare/v6...v7">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=actions/checkout&package-manager=github_actions&previous-version=6&new-version=7)](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-06-22 10:15:12 +01:00
Vladimir Kukushkin ca61184698 [SLG-0006]: task-local logger proposal (#460)
This proposal adds task-local logger storage so that metadata can
accumulate across async
call stacks without threading a `Logger` through every function
signature.

### Motivation:

Metadata propagation requires threading a logger through every layer.
Every function on
the path from request ingress to the bottom of the call stack has to
accept, mutate, and
forward a `Logger`. Libraries must choose between polluting their public
API with a `logger:` parameter and
losing all the caller's context. There is no third option today.

### Modifications:

SLG-0006 proposal is added.

### Result:

Proposal is ready for review.
2026-06-11 06:47:52 -07:00
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
Samuel MurrayandVladimir Kukushkin 5073617dac SLG-0003: Error parameter implementation (#425)
Add new methods on `Logger` that allows the caller to attach `Error`s to
log events, which will be propagated to the `LogHandler` as-is.

### Motivation:

Error information is typically of high interest in logs and log
analysis. Currently, however, there is no standardized way of attaching
`Error` information to logs, forcing users to either append it to the
log message (`logger.warning("Something went wrong: \(error)")`), or
attach it as metadata. By providing a separate parameter for this, and
passing it as-is to the `LogHandler`, we both provide a standard,
visible way to attach it, while also letting the `LogHandler` format it
as it sees fit.
Closes #291 

### Modifications:

* New methods on `Logger` that accept an (optional) `Error`.
* An `error` property is added to `LogEvent`, which contains the `Error`
from the new `Logger` methods.
* Adjust `LogHandler` implementations to serialize error as metadata.

### Result:

Users of `Logger` can use the new methods to attach `Error`s to their
logs, which should help unify how `Error`s get logged in various code
bases.
`LogHandler` implementations can use the new `error` property on
`LogEvent` and serialize it in a way that's suitable for that
implementation. In general, extracting the string representation and the
(qualified) type name should be a good baseline.

---------

Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-04-14 06:03:57 -07:00
dependabot[bot]andVladimir Kukushkin 6f3fbace66 Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.8 to 0.0.9 (#437)
Bumps
[swiftlang/github-workflows/.github/workflows/soundness.yml](https://github.com/swiftlang/github-workflows)
from 0.0.8 to 0.0.9.
<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.9</h2>
<h2>What's Changed</h2>
<ul>
<li>When splitting lines for the cross-PR checkout also split on \r\n by
<a href="https://github.com/ahoppen"><code>@​ahoppen</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/249">swiftlang/github-workflows#249</a></li>
<li>Fix template injection 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/247">swiftlang/github-workflows#247</a></li>
<li>Remove tailing comma in matrix JSON by <a
href="https://github.com/plemarquand"><code>@​plemarquand</code></a> in
<a
href="https://redirect.github.com/swiftlang/github-workflows/pull/254">swiftlang/github-workflows#254</a></li>
<li>Update default Xcode versions in workflow to 16.4, 26.3, and 26.4 by
<a href="https://github.com/shahmishal"><code>@​shahmishal</code></a> in
<a
href="https://redirect.github.com/swiftlang/github-workflows/pull/255">swiftlang/github-workflows#255</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.8...0.0.9">https://github.com/swiftlang/github-workflows/compare/0.0.8...0.0.9</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/f84da042883848ad67aadd051dc322eec18660d3"><code>f84da04</code></a>
Update default Xcode versions in workflow to 16.4, 26.3, and 26.4 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/255">#255</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/47c9717a9218ab60fe9fc6e957980d55fe949f1d"><code>47c9717</code></a>
Remove tailing comma in matrix JSON (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/254">#254</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/8e529b937e15ba0a65af9b492393704fe3f16bdf"><code>8e529b9</code></a>
Fix template injection (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/247">#247</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/58677410ce8ef88844850c908bcd830ad108c812"><code>5867741</code></a>
When splitting lines for the cross-PR checkout also split on \r\n (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/249">#249</a>)</li>
<li>See full diff in <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.8...0.0.9">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.8&new-version=0.0.9)](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>
Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-04-13 14:50:09 +01:00
Samuel Murray 41f6c72707 Retroactively update status of SLG-0005 to Approved (#438)
### Motivation:

SLG-0005 is implemented and released in 1.11.0.

### Modifications:

Update status to 'Approved'.

### Result:

The proposal reflects the actual status.
2026-04-09 08:35:48 +00:00
Rick Newton-Rogers bffceaf778 Drop Swift 6.0 (#436)
Motivation:

Swift 6.0 is no longer supported, we should bump the tools version and
remove it from our CI.

Modifications:

* Bump the Swift tools version to Swift 6.1
* Remove Swift 6.0 jobs where appropriate in main.yml, pull_request.yml

Result:

Code reflects our support window.
2026-04-08 14:52:39 +01:00
Vladimir Kukushkin 6558438e46 SLG-0004: Metadata privacy levels proposal (#416)
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 as
sensitive to allow Log Handlers to control logging behavior.

### Modifications:

Added the SLG-004 proposal, introducing attributed metadata values
mechanism and privacy levels for metadata values.

### Result:

Proposal is ready for review.

Review result: the proposal is not accepted and needs rework.
2026-04-02 17:10:43 +01:00
Rick Newton-Rogers 7c04f86fba Enable Swift 6.3 jobs in CI (#435)
Motivation:

Swift 6.3 has been released, we should add it to our CI coverage.

Modifications:

Add additional Swift 6.3 jobs where appropriate in main.yml,
pull_request.yml

Result:

Improved test coverage.
2026-04-01 14:18:23 +01:00
Vladimir Kukushkin 8c0f217f01 [CI] Add automated release workflow using swift-temporal-sdk (#434)
Integrate swift-temporal-sdk's reusable auto-release workflow for
automated semantic versioning releases. Update CONTRIBUTING.md with a
link to the workflow documentation.

### Motivation

- Automate the release process using semantic versioning labels,
reducing manual overhead and ensuring consistent versioning across
releases.

### Modifications

- Add .github/workflows/auto-release.yml that uses swift-temporal-sdk's
reusable workflow
- Update CONTRIBUTING.md with automated release process documentation
linking to swift-temporal-sdk's workflow README

### Result

- When PRs are merged with semver labels (semver/patch, semver/minor),
the workflow automatically creates GitHub releases. Major releases
require manual creation.

### Test Plan

- Workflow will be validated after merge by labeling PRs with semver
labels and verifying that releases are created automatically.
2026-03-31 12:06:46 +01:00
Mads Odgaard f4f84c9f26 Avoid using CFilePointer typealias in default logger (#433)
Rewrites the default log handler to avoid typing out what the C file
pointer looks like on different platforms.

This fixes #374 - as we do not make any assumptions at compile time
about what `FILE*` is imported as in Swift.
2026-03-27 13:27:10 +00:00
Vladimir Kukushkin 1f38a59922 [SLG-0005]: LogEvent LogHandler API implementation (#423)
Replace the flat-parameter
`log(level:message:metadata:source:file:function:line:)` method on
`LogHandler` with
`log(event: LogEvent)`, enabling forward-compatible evolution of the
`LogHandler` interface without breaking existing
handler implementations.

### Motivation:

Changes to the `LogHandler` API require dance around creating new
overloads, deprecating old overloads, which unnecessary bloats
`LogHandler` protocol surface (like happened with the source:
parameter). We have upcoming changes that would introduce new
capabilities to the `LogHandler` protocol, for example
https://forums.swift.org/t/proposal-slg-0003-standardized-error-metadata-via-logger-convenience/84518/35.
It makes sense to introduce a single container structure for all the
data associated with a log event before introducing any new overloads in
`LogHandler` protocol.

### Modifications:

- New struct `LogEvent` is added.
- `LogHandler` protocol now has an additional `log(event: LogEvent)`
method.
- `Logger` is calling handler's `log(event: LogEvent)` method.

### Result:

Further changes to the `LogEvent` with new information passed from the
`Logger` to a `LogHandler` does not require changes in the `LogHandler`
API. As a bonus, `LogEvent` makes `source` a computable variable,
improving performance for log handlers who do not need the default
source created based on the log file location.
2026-03-27 13:13:04 +00:00
Honza Dvorsky 39e14910f6 [CI] Disable Darwin tests while we investigate flakiness (#430)
### Motivation:

Darwin tests got enabled recently to test out reliability, unfortunately
they're flaky so let's disable them for now and I'll open a test PR
where we can iterate on them instead.

### Modifications:

Disabled Darwin test runs on nightly jobs.

### Result:

More reliable CI again.
2026-03-24 11:29:03 +00:00
Vladimir Kukushkin 63ee499927 Enable tests on simulators (#429) 2026-03-20 22:06:35 +00:00
Vladimir Kukushkin c9ceb519e7 [SLG-0005]: LogEvent LogHandler API proposal (#424)
Replace the flat-parameter
`log(level:message:metadata:source:file:function:line:)` method on
`LogHandler` with
`log(event: LogEvent)`, enabling forward-compatible evolution of the
`LogHandler` interface without breaking existing
handler implementations.

### Motivation:

Changes to the `LogHandler` API require dance around creating new
overloads, deprecating old overloads, which unnecessary bloats
`LogHandler` protocol surface (like happened with the source:
parameter). We have upcoming changes that would introduce new
capabilities to the `LogHandler` protocol, for example
https://forums.swift.org/t/proposal-slg-0003-standardized-error-metadata-via-logger-convenience/84518/35.
It makes sense to introduce a single container structure for all the
data associated with a log event before introducing any new overloads in
`LogHandler` protocol.

### Modifications:

- SLG-0005 proposal added.

### Result:

Proposal is ready for implementation.
The reason the proposal has
2026-03-20 12:16:20 +00:00
dependabot[bot] 154acdf7d4 Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.7 to 0.0.8 (#428)
Bumps
[swiftlang/github-workflows/.github/workflows/soundness.yml](https://github.com/swiftlang/github-workflows)
from 0.0.7 to 0.0.8.
<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.8</h2>
<h2>What's Changed</h2>
<ul>
<li>Fix build warnings in the workflow for iOS by <a
href="https://github.com/kkebo"><code>@​kkebo</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/173">swiftlang/github-workflows#173</a></li>
<li>Check if the locally installed Android NDK matches the wanted NDK
version by <a
href="https://github.com/finagolfin"><code>@​finagolfin</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/235">swiftlang/github-workflows#235</a></li>
<li>Update installed version of static linux SDK to 0.1.0 when using
released toolchains by <a
href="https://github.com/owenv"><code>@​owenv</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/241">swiftlang/github-workflows#241</a></li>
<li>Update the Xcode versions - 26.3 and 26.4b2 by <a
href="https://github.com/shahmishal"><code>@​shahmishal</code></a> in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/245">swiftlang/github-workflows#245</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a href="https://github.com/kkebo"><code>@​kkebo</code></a> made
their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/173">swiftlang/github-workflows#173</a></li>
<li><a
href="https://github.com/finagolfin"><code>@​finagolfin</code></a> made
their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/235">swiftlang/github-workflows#235</a></li>
<li><a href="https://github.com/owenv"><code>@​owenv</code></a> made
their first contribution in <a
href="https://redirect.github.com/swiftlang/github-workflows/pull/241">swiftlang/github-workflows#241</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.7...0.0.8">https://github.com/swiftlang/github-workflows/compare/0.0.7...0.0.8</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/61db6917df4ec2ddeeb493757e2d1effd46af855"><code>61db691</code></a>
Update the Xcode versions - 26.3 and 26.4b2 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/245">#245</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/d7f8c780c9994917d6088e165e0fee6fb0bd06a1"><code>d7f8c78</code></a>
Update installed version of static linux SDK to 0.1.0 (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/241">#241</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/bca81f75d7d1ae2474f1213169aab56dcad8961f"><code>bca81f7</code></a>
Revert Use local copy on action invocation (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/239">#239</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/27ad4acfa502b0cb8b901532e8294a14b7273988"><code>27ad4ac</code></a>
Add symlinks for backwards compatability (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/238">#238</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/555b8029955d1e91ed50768afb969805c796bdd6"><code>555b802</code></a>
Check if the locally installed Android NDK matches the wanted NDK
version (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/235">#235</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/c6fcbaf70a845126ec165107a2d509bda17a2fd1"><code>c6fcbaf</code></a>
Use local copy on action invocation (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/236">#236</a>)</li>
<li><a
href="https://github.com/swiftlang/github-workflows/commit/2b7c7405cd7ce3627f84fb0765c785f099d19715"><code>2b7c740</code></a>
Fix build warnings in the workflow for iOS (<a
href="https://redirect.github.com/swiftlang/github-workflows/issues/173">#173</a>)</li>
<li>See full diff in <a
href="https://github.com/swiftlang/github-workflows/compare/0.0.7...0.0.8">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.7&new-version=0.0.8)](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-03-13 19:46:39 +00:00
Samuel MurrayandVladimir Kukushkin b93451412b Update proposal SLG-0003 after public review (#419)
Motivation:

The public review of the original proposal

(https://forums.swift.org/t/proposal-slg-0003-standardized-error-metadata-via-logger-convenience/84518)
is done, and these changes adjust for what was decided on.

Modifications:

The main difference is to pass Error instances as-is to LogHandlers,
rather than serializing it to metadata in Logger.

Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-03-12 12:19:26 +00:00
Mike Drob c5f42781c4 Use org security policy instead of our bespoke version (#426) 2026-03-12 11:00:27 +00:00
Vladimir Kukushkin 4f1022c5cd Fix benchmarks — traits are only available in 6.1+ (#417) 2026-02-18 10:01:24 +00:00
Vladimir Kukushkin f22537f94d Do not run benchmarks on linux, we can’t collect anything anyway (#415)
`swift-nio` reusable workflow for running benchmarks has been recently
fixed and now linux benchmarks are failing because we do not have any
thresholds recorded. The main purpose for `swift-log` benchmarks is to
keep track of the amount of instructions and on linux runners
performance metrics are not available, so we cannot check the relevant
metric. Let's remove them.
2026-02-17 18:51:49 +00:00
Honza Dvorsky 185a56a488 Enable dependabot and switch GHA references to tags (#412)
### Motivation:

For better control over GitHub workflows, switch over to a tags-based
dependency.

### Modifications:

- Switch to tags
- Enable dependabot to get weekly update checks

### Result:

More streamlined and controlled GHA dependency updates.
2026-02-17 18:16:30 +00:00
Honza Dvorsky bbd81b6725 Fix: Only use unsafe flag on Swift 6.2 (#411)
### Motivation:

Package.swift needs to use tools-version 6.2, as we have dedicated 6.0
and 6.1 manifests.

Here, when building on 6.1, the Package.swift was being picked and an
unsafe flag was found, which isn't allowed on 6.1 (only on 6.2+).

### Modifications:

Bump Package.swift's tools-version to 6.2.

### Result:

Should fix dependees.
2026-02-16 18:22:18 +01:00
scottmarchant 8fb4e7147d chore: update Lock implementation with latest changes from swift-nio (#408)
Ports changes to `Lock` from swift-nio to swift-log.

### Motivation:

The copy-paste of `Lock` in swift-log should be updated with changes
from swift-nio.

### Modifications:

- Rolls back changed [made previously for
FreeBSD](https://github.com/apple/swift-log/pull/387/changes#diff-7b1bd45403dd1a7418287bd60682bf05ba2e4bf75dca1c0ca55a86d0477c9af5L73)
in favor of a consolidated implementation in swift-nio that will be in
place once https://github.com/apple/swift-nio/pull/3494 merges. @kkebo
Please confirm this works. After both of our PR's merge, swift-log and
swift-nio will have the same implementation as far as FreeBSD is
concerned.
- Brought the following recent changes from swift-nio over to swift-log:

  - https://github.com/apple/swift-nio/pull/3482
  - https://github.com/apple/swift-nio/pull/3480
  - https://github.com/apple/swift-nio/pull/3483

- Removed stale `// SRWLOCK does not need to be free'd` comment.

### Result:

`Lock` implementation will have the same implementation as swift-nio
(assuming https://github.com/apple/swift-nio/pull/3494 merges).
2026-02-12 12:51:03 +00:00
Samuel MurrayandVladimir Kukushkin d5dbc04d53 [SLG-0003]: [Proposal] Standardized Error Metadata via Logger Convenience (#405)
Add a proposal for the standardized way of attaching data from Error instances to log
posts.

### Motivation:

Addresses https://github.com/apple/swift-log/issues/291

### Modifications:

The "SLG-0003" proposal doc added.

### Result:

The proposal is ready for review.

---------

Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-02-02 16:30:32 +00:00
Vladimir Kukushkin 47ef0ec6a4 Enable upcoming compiler features (#401)
Enable several upcoming compiler features to make the codebase more
explicit in intention:

```
    // https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md
    // Require `any` for existential types.
    settings.append(.enableUpcomingFeature("ExistentialAny"))

    // https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
    settings.append(.enableUpcomingFeature("MemberImportVisibility"))

    // https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
    settings.append(.enableUpcomingFeature("InternalImportsByDefault"))

    // https://docs.swift.org/compiler/documentation/diagnostics/nonisolated-nonsending-by-default/
    settings.append(.enableUpcomingFeature("NonisolatedNonsendingByDefault"))

    // Ensure all public types are explicitly annotated as Sendable or not Sendable.
    settings.append(.unsafeFlags(["-Xfrontend", "-require-explicit-sendable"]))
```

### Motivation:

Sync codebase with the modern practice, get ready for the upcoming
features.

### Modifications:

- Compiler flags added for all the existing targets.
- Imports and access modifiers adjusted.
- `LoggingSystem` marked as `Sendable`

### Result:

Codebase is updated with the modern practices.
2026-01-30 08:58:47 +01:00
Vladimir Kukushkin 7d6d55f9ed Update benchmarks expectations on Tahoe (#404)
Update macOS benchmarks after moving to Tahoe runners.

### Motivation:

`swift-log` has performance benchmarks measuring instructions. Results
may vary from version to version of macOS.

### Modifications:

Benchmarking thresholds updated based on the Tahoe runners results.

### Result:

Benchmark jobs pass.
2026-01-23 16:38:37 +01:00
Kenta KuboandFranz Busch 8f634e4e68 Add support for FreeBSD and OpenBSD (#387)
I've added support for FreeBSD. I've only tested this PR on FreeBSD, but
I believe it should also work on OpenBSD.

### Motivation:

closes #372 

Also, [Swift on FreeBSD preview
toolchain](https://forums.swift.org/t/swift-on-freebsd-preview/83064) is
now available.

### Modifications:

- changed pthread-related code for *BSD
- changed `Glibc.stdout` and `Glibc.stderr` for *BSD because they are
non-optional on *BSD

### Result:

swift-log and packages depending on it will be usable on FreeBSD.

### Checks:

I tested it with `swift build` and `swift test`. All tests have passed.

```console
$ swift test
...
Test Suite 'All tests' passed at 2025-11-07 04:29:34.003                                                                                         
         Executed 0 tests, with 0 failures (0 unexpected) in 0.0 (0.0) seconds
...
✔ Test run with 52 tests in 7 suites passed after 0.309 seconds.
```

Environment:

```console
$ uname -a
FreeBSD Coconut-rhinoceros-beetle 15.0-BETA4 FreeBSD 15.0-BETA4 releng/15.0-n280841-a7707f2a3bf4 GENERIC amd64
$ swift --version
Swift version 6.3-dev (LLVM bff1370bd79c983, Swift 57cf4ce563f700b)
Target: x86_64-unknown-freebsd14.3
Build config: +assertions
```

Swift toolchain is from
https://forums.swift.org/t/swift-on-freebsd-preview/83064.

---------

Co-authored-by: Franz Busch <f.busch@apple.com>
2026-01-19 16:37:43 +00:00
Si Beaumont 2778fd4e5a Reinstate InMemoryLogging product in Swift 6.0 manifest (#403)
### Motivation:

In the latest release (1.9.0) the package manifest was split for Swift
6.0 and 6.1+. The 6.0 manifest lost the `InMemoryLogging` library
product, causing API breakage for adopters using Swift 6.0:

```diff
% diff -u <(git show 1.8.0:Package.swift) <(git show 1.9.0:Package@swift-6.0.swift)
--- /dev/fd/63  2026-01-19 10:30:21
+++ /dev/fd/62  2026-01-19 10:30:21
@@ -18,25 +18,16 @@
 let package = Package(
     name: "swift-log",
     products: [
-        .library(name: "Logging", targets: ["Logging"]),
-        .library(name: "InMemoryLogging", targets: ["InMemoryLogging"]),
+        .library(name: "Logging", targets: ["Logging"])
     ],
     targets: [
         .target(
             name: "Logging",
             dependencies: []
         ),
-        .target(
-            name: "InMemoryLogging",
-            dependencies: ["Logging"]
-        ),
         .testTarget(
             name: "LoggingTests",
             dependencies: ["Logging"]
-        ),
-        .testTarget(
-            name: "InMemoryLoggingTests",
-            dependencies: ["InMemoryLogging", "Logging"]
         ),
     ]
 )

```

### Modifications:

Reinstate InMemoryLogging product in Swift 6.0 manifest

### Result:

Adopters using `InMemoryLogging` on Swift 6.0 are unbroken.

### Related issues:

Fixes #402
2026-01-19 10:46:49 +00:00
Konrad `ktoso` MalawskiandVladimir Kukushkin 0d9c9ae808 Change document title to 'SLG-0001: Metadata Providers' (#400)
Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
2026-01-15 19:55:51 +09:00
scottmarchant a92ccc626c feat: Update lock implementation to more closely align with swift-nio implementation (#398) 2026-01-15 08:08:44 +00:00
Vladimir Kukushkin 7ee16e4656 The SLG-0002 implementation is merged, update the proposal status (#399)
Just bumping the status before making the release.
2026-01-14 13:04:51 +00:00
Vladimir Kukushkin 1ccd2c5a27 [SLG-0002] Implementation: Compile-time log level elimination using traits (#389)
Add compile-time traits for eliminating log levels from binaries

###  Motivation:

Applications often know in advance which log levels will never be needed
in production. For example, a production service might only need warning
and above, while trace and debug levels are only useful during
development. This PR introduces
compile-time traits that completely eliminate unwanted log levels from
binaries, achieving zero runtime overhead for disabled log statements.

### Modifications:

- Added seven `MaxLogLevel*` traits
- Extended benchmarks with the `MaxLogLevelWarning` suite
- Added "Disable log levels during compilation" section to the best
practices guide

### Result:

Users can eliminate unwanted log levels at compile time by specifying
traits in their `Package.swift` dependency declaration.
2026-01-13 14:23:51 +00:00
Salman Chishti 477fab4170 Upgrade GitHub Actions for Node 24 compatibility (#397)
## Summary

Upgrade GitHub Actions to their latest versions to ensure compatibility
with Node 24, as Node 20 will reach end-of-life in April 2026.

## Changes

| Action | Old Version(s) | New Version | Release | Files |
|--------|---------------|-------------|---------|-------|
| `actions/checkout` |
[`v4`](https://github.com/actions/checkout/releases/tag/v4) |
[`v6`](https://github.com/actions/checkout/releases/tag/v6) |
[Release](https://github.com/actions/checkout/releases/tag/v6) |
pull_request_label.yml |

## Context

Per [GitHub's
announcement](https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/),
Node 20 is being deprecated and runners will begin using Node 24 by
default starting March 4th, 2026.

### Why this matters

- **Node 20 EOL**: April 2026
- **Node 24 default**: March 4th, 2026
- **Action**: Update to latest action versions that support Node 24

### Security Note

Actions that were previously pinned to commit SHAs remain pinned to SHAs
(updated to the latest release SHA) to maintain the security benefits of
immutable references.

### Testing

These changes only affect CI/CD workflow configurations and should not
impact application functionality. The workflows should be tested by
running them on a branch before merging.

Signed-off-by: Salman Muin Kayser Chishti <13schishti@gmail.com>
2025-12-18 06:27:47 +09:00
Vladimir Kukushkin bc386b95f2 [SLG-0002]: Compile-time log level elimination using traits (#391)
Enable compile-time elimination of log levels to achieve zero runtime
overhead for logs that will never be needed in production.

### Motivation:

In production deployments, applications often know in advance which log
levels will never be needed. For example, a production service typically
only needs warning and above, while trace and debug levels are
exclusively useful during development. Currently, even with the log
level set to `.warning` at runtime, the code for trace and debug
statements still exists in the binary and incurs overhead.

### Modifications:

The "SLG-0002: Compile-time log level elimination using traits" proposal
doc added.

### Result:

The proposal is ready for implementation.
2025-12-11 12:31:11 +00:00
Vladimir Kukushkin 6856e42a3f Adapt separate benchmark workflows from swift-nio (#396)
Depends on https://github.com/apple/swift-nio/pull/3461, which is not
yet merged

### Motivation:

`swift-nio` now has 2 separate workflows for running benchmarks on Linux
and macOS to remove unnecessary noise of skipped macOS benchmarks, see
[`swift-nio` PR](https://github.com/apple/swift-nio/pull/3461) for
details.

### Modifications:

Split Linux and macOS benchmarks into different jobs.

### Result:

Linux and macOS benchmarks are running as different jobs.
2025-12-11 12:47:43 +01:00
Francesco Paolo Severino cdaa5ac879 Conform Logger.Level to CustomStringConvertible and LosslessStringConvertible (#395)
Conform `Logger.Level` to `CustomStringConvertible` and
`LosslessStringConvertible`.

### Motivation:

There are libraries, such as Vapor, that add these conformances
privately and `@retroactive`ly. This would avoid having to implement
these conformances manually in each library and would unify and
standardise the implementation.

### Modifications:

Make `Logger.Level` conform to `CustomStringConvertible` and
`LosslessStringConvertible`, adding a public `description` computed
property that returns the `rawValue` and a public initializer that takes
a `description` string, lowercases it, and passes it to the `rawValue`
initializer.

### Result:

`Logger.Level` conforms to `CustomStringConvertible` and
`LosslessStringConvertible`.
2025-12-08 20:11:23 +01:00
hamzahrmalik b1fa4ef41f Make InMemoryLogging available on all platforms (#394)
Make InMemoryLogging available on all platforms

### Motivation:

Users might want to adopt the in memory logger on lower platform
versions.

### Modifications:

Remove availability annotations by using swift-logs own Lock instead of
Mutex

### Result:

In memory logger can be used on all platforms that swift-log supports
2025-12-04 11:52:31 +00:00
Max DesiatovandKonrad `ktoso` Malawski 63eaca6f4d Add Wasm builds to pull_request.yml (#371)
Co-authored-by: Konrad `ktoso` Malawski <konrad_malawski@apple.com>
2025-12-04 19:02:45 +09:00
Max Desiatov f3a82f1119 Fix Android build error with @preconcurrency import Android (#393) 2025-12-04 08:33:10 +09:00
Vladimir Kukushkin 6b380c9f4b Move pre-process proposal to the proposals folder (#392)
Move single pre-process proposal file to the new location.

### Motivation:

To have all the proposals in one place.

### Modifications:

One .md file moved.

### Result:

All proposals are in one place.
2025-12-03 16:27:10 +01:00
134 changed files with 9174 additions and 1889 deletions

No files matched your search

+8
View File
@@ -0,0 +1,8 @@
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "daily"
labels:
- "semver/none"
+12
View File
@@ -0,0 +1,12 @@
name: Auto Release
on:
workflow_dispatch:
permissions:
contents: write
pull-requests: read
jobs:
auto-release:
uses: apple/swift-temporal-sdk/.github/workflows/auto-release.yml@main
+56 -49
View File
@@ -10,57 +10,64 @@ on:
- cron: "0 8,20 * * *"
jobs:
unit-tests:
name: Unit tests
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
tests:
name: Tests
uses: swiftlang/github-workflows/.github/workflows/package_test.yml@0.0.18
with:
linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_6_0_enabled: true
windows_6_1_enabled: true
windows_6_2_enabled: true
windows_nightly_next_enabled: true
windows_nightly_main_enabled: true
windows_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
# After https://github.com/swiftlang/github-workflows/pull/362 fix is available, this can be simplified to:
# windows_command: |
# Debug-Test: swift test
# Release-Build: swift build -c release
# windows_version_overrides: |
# default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
# nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
# nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
windows_env_vars: '{"COMMON_SWIFT_FLAGS": "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"}'
windows_command: |
Debug-Test:
command: swift test -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
versions: ["current-2", "current-1", "current"]
Release-Build:
command: swift build -c release -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
versions: ["current-2", "current-1", "current"]
Debug-Test-Nightly:
command: swift test %COMMON_SWIFT_FLAGS%
versions: ["nightly-release", "nightly-main"]
Release-Build-Nightly:
command: swift build -c release %COMMON_SWIFT_FLAGS%
versions: ["nightly-release", "nightly-main"]
# The Windows runner installs a pinned Swift patch release. The container image tracks the newest patch release.
# Context: https://github.com/swiftlang/github-workflows/issues/356
windows_use_docker: true
# Strict flags for the release toolchains. The nightly toolchains skip -warnings-as-errors.
linux_version_overrides: |
default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
macos_runner_pool: nightly
xcode_scheme: swift-log-Package
xcode_targets: |
macOS:
build: true
test: true
wasm_sdk_versions: '["current", "nightly-main"]'
enable_embedded_wasm_sdk_build: false
enable_macos_swiftly: false
enable_freebsd: false
benchmarks:
name: Benchmarks
uses: apple/swift-nio/.github/workflows/benchmarks.yml@main
macos-benchmarks:
name: macOS benchmarks
uses: swiftlang/github-workflows/.github/workflows/benchmarks.yml@0.0.18
with:
benchmark_package_path: "Benchmarks"
macos_xcode_16_4_enabled: true
macos_xcode_26_1_enabled: true
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
enable_linux: false
enable_macos: true
macos_swift_versions: '["current-1", "current"]'
macos_runner_pool: nightly
cxx-interop:
name: Cxx interop
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
static-sdk:
name: Static SDK
# Workaround https://github.com/nektos/act/issues/1875
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
macos-tests:
name: macOS tests
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
cmake-build:
name: CMake build
uses: swiftlang/github-workflows/.github/workflows/cmake_build.yml@0.0.18
with:
runner_pool: nightly
build_scheme: swift-log-Package
swift_test_enabled: true
release-builds:
name: Release builds
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
with:
windows_6_0_enabled: true
windows_6_1_enabled: true
windows_6_2_enabled: true
windows_nightly_next_enabled: true
windows_nightly_main_enabled: true
enable_windows_checks: false
linux_pre_build_command: apt-get update && apt-get install -y ninja-build
+56 -51
View File
@@ -10,63 +10,68 @@ on:
jobs:
soundness:
name: Soundness
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.18
with:
license_header_check_project_name: "Swift Logging API"
unit-tests:
name: Unit tests
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
tests:
name: Tests
uses: swiftlang/github-workflows/.github/workflows/package_test.yml@0.0.18
with:
linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_6_0_enabled: true
windows_6_1_enabled: true
windows_6_2_enabled: true
windows_nightly_next_enabled: true
windows_nightly_main_enabled: true
windows_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
benchmarks:
name: Benchmarks
uses: apple/swift-nio/.github/workflows/benchmarks.yml@main
with:
benchmark_package_path: "Benchmarks"
# After https://github.com/swiftlang/github-workflows/pull/362 fix is available, this can be simplified to:
# windows_command: |
# Debug-Test: swift test
# Release-Build: swift build -c release
# windows_version_overrides: |
# default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
# nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
# nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
windows_env_vars: '{"COMMON_SWIFT_FLAGS": "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"}'
windows_command: |
Debug-Test:
command: swift test -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
versions: ["current-2", "current-1", "current"]
Release-Build:
command: swift build -c release -Xswiftc -warnings-as-errors %COMMON_SWIFT_FLAGS%
versions: ["current-2", "current-1", "current"]
Debug-Test-Nightly:
command: swift test %COMMON_SWIFT_FLAGS%
versions: ["nightly-release", "nightly-main"]
Release-Build-Nightly:
command: swift build -c release %COMMON_SWIFT_FLAGS%
versions: ["nightly-release", "nightly-main"]
# The Windows runner installs a pinned Swift patch release. The container image tracks the newest patch release.
# Context: https://github.com/swiftlang/github-workflows/issues/356
windows_use_docker: true
# Strict flags for the release toolchains. The nightly toolchains skip -warnings-as-errors.
linux_version_overrides: |
default: -Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
nightly-release: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
nightly-main: --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable
macos_runner_pool: general
macos_xcode_16_4_enabled: true
macos_xcode_26_1_enabled: true
xcode_scheme: swift-log-Package
xcode_targets: |
macOS:
build: true
test: true
wasm_sdk_versions: '["current", "nightly-main"]'
enable_embedded_wasm_sdk_build: false
enable_macos_swiftly: false
enable_freebsd: false
cxx-interop:
name: Cxx interop
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
static-sdk:
name: Static SDK
# Workaround https://github.com/nektos/act/issues/1875
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
macos-tests:
name: macOS tests
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
macos-benchmarks:
name: macOS benchmarks
uses: swiftlang/github-workflows/.github/workflows/benchmarks.yml@0.0.18
with:
runner_pool: general
build_scheme: swift-log-Package
swift_test_enabled: true
benchmark_package_paths: '["Benchmarks/NoTraits", "Benchmarks/MaxLogLevelWarning", "Benchmarks/MaxLogLevelNone"]'
enable_linux: false
enable_macos: true
macos_swift_versions: '["current-1", "current"]'
macos_runner_pool: general
release-builds:
name: Release builds
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
cmake-build:
name: CMake build
uses: swiftlang/github-workflows/.github/workflows/cmake_build.yml@0.0.18
with:
windows_6_0_enabled: true
windows_6_1_enabled: true
windows_6_2_enabled: true
windows_nightly_next_enabled: true
windows_nightly_main_enabled: true
enable_windows_checks: false
linux_pre_build_command: apt-get update && apt-get install -y ninja-build
+2 -9
View File
@@ -2,6 +2,7 @@ name: PR label
permissions:
contents: read
pull-requests: read
on:
pull_request:
@@ -10,12 +11,4 @@ on:
jobs:
semver-label-check:
name: Semantic version label check
runs-on: ubuntu-latest
timeout-minutes: 1
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
persist-credentials: false
- name: Check for Semantic Version label
uses: apple/swift-nio/.github/actions/pull_request_semver_label_checker@main
uses: swiftlang/github-workflows/.github/workflows/pull_request_label.yml@0.0.18
+2 -2
View File
@@ -5,7 +5,6 @@
.gitattributes
.git-blame-ignore-revs
.mailfilter
.mailmap
.spi.yml
.swift-format
.editorconfig
@@ -19,6 +18,8 @@ Package.swift
**/Package.swift
Package@-*.swift
**/Package@-*.swift
Package@swift-*.swift
**/Package@swift-*.swift
Package.resolved
**/Package.resolved
Makefile
@@ -32,7 +33,6 @@ Makefile
Dockerfile
**/Dockerfile
Snippets/*
dev/git.commit.template
dev/update-benchmark-thresholds
*.crt
**/*.crt
-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>
@@ -1,57 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Benchmark
import Foundation
import Logging
let benchmarks: @Sendable () -> Void = {
let iterations = 1_000_000
let metrics: [BenchmarkMetric] = [.instructions, .objectAllocCount]
// Take a pair of levels to cover all condition ranges between the active level and logged level.
let logLevelParameterization: [Logger.Level] = [.debug, .error]
for logLevel in logLevelParameterization {
for logLevelUsed in logLevelParameterization {
var logger = Logger(label: "BenchmarkRunner_\(logLevel)_\(logLevelUsed)")
// Use a NoOpLogHandler to avoid polluting the logs
logger.handler = NoOpLogHandler(label: "NoOpLogHandler")
logger.logLevel = logLevel
Benchmark(
"\(logLevelUsed)_log_with_\(logLevel)_log_level",
configuration: .init(
metrics: metrics,
maxIterations: iterations,
thresholds: [
.instructions: BenchmarkThresholds(
relative: [
.p90: 1.0 // we only record p90
]
),
.objectAllocCount: BenchmarkThresholds(
absolute: [
.p90: 0 // we only record p90
]
),
]
)
) { benchmark in
// This is what we actually benchmark
logger.log(level: logLevelUsed, "hello, benchmarking world")
}
}
}
}
+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.3
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "MaxLogLevelNone",
platforms: [
.macOS(.v13)
],
products: [
.executable(name: "MaxLogLevelNone", targets: ["MaxLogLevelNone"])
],
dependencies: [
// swift-log
.package(
path: "../../",
traits: ["MaxLogLevelNone"]
),
// Parent Benchmarks
.package(name: "Benchmarks", path: "../"),
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
],
targets: [
.executableTarget(
name: "MaxLogLevelNone",
dependencies: [
.product(name: "BenchmarksFactory", package: "Benchmarks"),
.product(name: "Benchmark", package: "benchmark"),
.product(name: "Logging", package: "swift-log"),
],
path: "Benchmarks/MaxLogLevelNoneBenchmarks",
plugins: [
.plugin(name: "BenchmarkPlugin", package: "benchmark")
]
)
]
)
@@ -0,0 +1,4 @@
{
"instructions" : 6775,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6771,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6875,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6879,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6895,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6867,
"objectAllocCount" : 0
}
+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,43 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Benchmark
import BenchmarksFactory
import Foundation
import Logging
public let benchmarks: @Sendable () -> Void = {
makeBenchmark(loggerLevel: .notice, logLevel: .notice) { logger in
logger.notice("hello, benchmarking world")
}
makeBenchmark(loggerLevel: .notice, logLevel: .notice, "_generic") { logger in
logger.log(level: .notice, "hello, benchmarking world")
}
makeBenchmark(loggerLevel: .warning, logLevel: .warning) { logger in
logger.warning("hello, benchmarking world")
}
makeBenchmark(loggerLevel: .warning, logLevel: .warning, "_generic") { logger in
logger.log(level: .warning, "hello, benchmarking world")
}
makeBenchmark(loggerLevel: .notice, logLevel: .notice, "_attributed_generic") { logger in
logger.log(
level: .notice,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", sensitivity: .public)",
"private-key": "\("private-value", sensitivity: .sensitive)",
]
)
}
}
@@ -0,0 +1,38 @@
// swift-tools-version: 6.2.3
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "MaxLogLevelWarning",
platforms: [
.macOS(.v13)
],
products: [
.executable(name: "MaxLogLevelWarning", targets: ["MaxLogLevelWarning"])
],
dependencies: [
// swift-log
.package(
path: "../../",
traits: ["MaxLogLevelWarning"]
),
// Parent Benchmarks
.package(name: "Benchmarks", path: "../"),
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
],
targets: [
.executableTarget(
name: "MaxLogLevelWarning",
dependencies: [
.product(name: "BenchmarksFactory", package: "Benchmarks"),
.product(name: "Benchmark", package: "benchmark"),
.product(name: "Logging", package: "swift-log"),
],
path: "Benchmarks/MaxLogLevelWarningBenchmarks",
plugins: [
.plugin(name: "BenchmarkPlugin", package: "benchmark")
]
)
]
)
@@ -0,0 +1,4 @@
{
"instructions" : 6775,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6747,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6775,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 1251327,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 1251327,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6847,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6863,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 6871,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 1189887,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 1189887,
"objectAllocCount" : 0
}
+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,106 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Benchmark
import BenchmarksFactory
import Foundation
import Logging
public let benchmarks: @Sendable () -> Void = {
makeBenchmark(loggerLevel: .error, logLevel: .error, "_generic") { logger in
logger.log(level: .error, "hello, benchmarking world")
}
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_generic") { logger in
logger.log(level: .debug, "hello, benchmarking world")
}
// MARK: - Task-local logger benchmarks
makeBenchmark(loggerLevel: .error, logLevel: .error, "_current_read_fallback") { _ in
blackHole(Logger.current)
}
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_current_read_inside_scope") {
logger in
blackHole(Logger.current)
}
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_withLogger_mergingMetadata") {
logger in
withLogger(mergingMetadata: ["key": "value"]) { inner in
blackHole(inner)
}
}
makeBenchmark(loggerLevel: .error, logLevel: .error, setScopedLogger: true, "_withLogger_handler") { logger in
withLogger(handler: logger.handler) { inner in
blackHole(inner)
}
}
makeBenchmark(loggerLevel: .error, logLevel: .error, "_1_attribute") { logger in
logger.log(
level: .error,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", sensitivity: .public)"
]
)
}
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_1_attribute") { logger in
logger.log(
level: .debug,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", sensitivity: .public)"
]
)
}
makeBenchmark(loggerLevel: .error, logLevel: .error, "_2_attributes") { logger in
logger.log(
level: .error,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", attributes: [BenchmarkSensitivity.public, BenchmarkColor.red])"
]
)
}
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_2_attributes") { logger in
logger.log(
level: .debug,
"hello, benchmarking world",
metadata: [
"public-key": "\("public-value", attributes: [BenchmarkSensitivity.public, BenchmarkColor.red])"
]
)
}
// MARK: - metadata serialization performance
func nestedArrayMetadataValue(depth: Int) -> Logger.MetadataValue {
var value: Logger.MetadataValue = .string("leaf")
for _ in 0..<depth {
value = .array([value])
}
return value
}
for depth in [1, 5, 20, 1_000] {
let nested = nestedArrayMetadataValue(depth: depth)
makeBenchmark(loggerLevel: .info, logLevel: .debug, "_metadata_nesting_depth_\(depth)") { _ in
blackHole(nested.description)
}
}
}
+37
View File
@@ -0,0 +1,37 @@
// swift-tools-version:6.2.3
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "NoTraits",
platforms: [
.macOS(.v13)
],
products: [
.executable(name: "NoTraits", targets: ["NoTraits"])
],
dependencies: [
// swift-log
.package(
path: "../../"
),
// Parent Benchmarks
.package(name: "Benchmarks", path: "../"),
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
],
targets: [
.executableTarget(
name: "NoTraits",
dependencies: [
.product(name: "BenchmarksFactory", package: "Benchmarks"),
.product(name: "Benchmark", package: "benchmark"),
.product(name: "Logging", package: "swift-log"),
],
path: "Benchmarks/NoTraitsBenchmarks",
plugins: [
.plugin(name: "BenchmarkPlugin", package: "benchmark")
]
)
]
)
@@ -0,0 +1,4 @@
{
"instructions" : 324863,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 324863,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 320767,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 4751359,
"objectAllocCount" : 1000
}
@@ -0,0 +1,4 @@
{
"instructions" : 5039157355,
"objectAllocCount" : 2016000
}
@@ -0,0 +1,4 @@
{
"instructions" : 81723391,
"objectAllocCount" : 37000
}
@@ -0,0 +1,4 @@
{
"instructions" : 17661951,
"objectAllocCount" : 6000
}
@@ -0,0 +1,4 @@
{
"instructions" : 5644287,
"objectAllocCount" : 2000
}
@@ -0,0 +1,4 @@
{
"instructions" : 7065599,
"objectAllocCount" : 3000
}
@@ -0,0 +1,4 @@
{
"instructions" : 272895,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 284927,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 1249279,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 3273000,
"objectAllocCount" : 1000
}
@@ -0,0 +1,4 @@
{
"instructions" : 9117695,
"objectAllocCount" : 4000
}
@@ -0,0 +1,4 @@
{
"instructions" : 324863,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 324863,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 323071,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 4415487,
"objectAllocCount" : 1000
}
@@ -0,0 +1,4 @@
{
"instructions" : 4322989256,
"objectAllocCount" : 2016000
}
@@ -0,0 +1,4 @@
{
"instructions" : 68354047,
"objectAllocCount" : 37000
}
@@ -0,0 +1,4 @@
{
"instructions" : 14581759,
"objectAllocCount" : 6000
}
@@ -0,0 +1,4 @@
{
"instructions" : 5795839,
"objectAllocCount" : 2000
}
@@ -0,0 +1,4 @@
{
"instructions" : 7192575,
"objectAllocCount" : 3000
}
@@ -0,0 +1,4 @@
{
"instructions" : 301055,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 243967,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 1189887,
"objectAllocCount" : 0
}
@@ -0,0 +1,4 @@
{
"instructions" : 2841000,
"objectAllocCount" : 1000
}
@@ -0,0 +1,4 @@
{
"instructions" : 8929279,
"objectAllocCount" : 4000
}
+16 -19
View File
@@ -1,30 +1,27 @@
// swift-tools-version: 6.0
// swift-tools-version:6.2.3
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "Benchmarks",
name: "BenchmarksFactory",
platforms: [
.macOS(.v13)
],
products: [
.library(name: "BenchmarksFactory", targets: ["BenchmarksFactory"])
],
dependencies: [
.package(path: "../"),
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
.package(url: "https://github.com/ordo-one/benchmark.git", from: "1.29.6"),
.package(path: "../"), // swift-log
],
targets: [
.target(
name: "BenchmarksFactory",
dependencies: [
.product(name: "Benchmark", package: "benchmark"),
.product(name: "Logging", package: "swift-log"),
]
)
]
)
// Benchmark of SwiftLogBenchmarks
package.targets += [
.executableTarget(
name: "SwiftLogBenchmarks",
dependencies: [
.product(name: "Benchmark", package: "package-benchmark"),
.product(name: "Logging", package: "swift-log"),
],
path: "Benchmarks/SwiftLogBenchmarks",
plugins: [
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
]
)
]
@@ -0,0 +1,71 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Benchmark
import Foundation
import Logging
public func makeBenchmark(
loggerLevel: Logger.Level,
logLevel: Logger.Level,
setScopedLogger: Bool = false,
_ suffix: String = "",
_ body: @escaping (Logger) -> Void
) {
let iterations = 1_000_000
let metrics: [BenchmarkMetric] = [.instructions, .objectAllocCount]
var logger = Logger(label: "BenchmarkRunner_\(loggerLevel)_\(logLevel)")
// Use a NoOpLogHandler to avoid polluting the logs
logger.handler = NoOpLogHandler(label: "NoOpLogHandler")
logger.logLevel = loggerLevel
Benchmark(
"\(logLevel)_log_with_\(loggerLevel)_log_level\(suffix)",
configuration: .init(
metrics: metrics,
scalingFactor: .kilo,
maxIterations: iterations,
thresholds: [
.instructions: BenchmarkThresholds(
relative: [
.p90: 10.0 // we only record p90
]
),
.objectAllocCount: BenchmarkThresholds(
absolute: [
.p90: 0 // we only record p90
]
),
]
)
) { benchmark in
if setScopedLogger {
withLogger(logger) { logger in
benchmark.startMeasurement()
for _ in benchmark.scaledIterations {
body(logger)
}
benchmark.stopMeasurement()
}
} else {
benchmark.startMeasurement()
for _ in benchmark.scaledIterations {
body(logger)
}
benchmark.stopMeasurement()
}
}
}
@@ -14,6 +14,40 @@
import Logging
// MARK: - Benchmark attributes
public enum BenchmarkSensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case sensitive = 1
case `public` = 2
}
extension Logger.MetadataValue.StringInterpolation {
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T,
sensitivity: BenchmarkSensitivity
) {
self.appendInterpolation(value, attributes: { $0[BenchmarkSensitivity.self] = sensitivity })
}
}
public enum BenchmarkColor: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case red = 1
case blue = 2
}
extension Logger.MetadataValue.StringInterpolation {
@inlinable
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T,
color: BenchmarkColor
) {
self.appendInterpolation(value, attributes: { $0[BenchmarkColor.self] = color })
}
}
// MARK: - NoOpLogHandler
struct NoOpLogHandler: LogHandler {
let label: String
public var metadataProvider: Logger.MetadataProvider?
@@ -28,6 +62,19 @@ struct NoOpLogHandler: LogHandler {
self.metadataProvider = LoggingSystem.metadataProvider
}
func log(
event: LogEvent
) {
// Access metadata attributes
if let metadata = event.metadata {
for (_, value) in metadata {
let _ = value.attributes
}
}
// Do nothing
}
func log(
level: Logger.Level,
message: Logger.Message,
@@ -37,6 +84,13 @@ struct NoOpLogHandler: LogHandler {
function: String,
line: UInt
) {
// Access metadata attributes
if let metadata = explicitMetadata {
for (_, value) in metadata {
let _ = value.attributes
}
}
// Do nothing
}
@@ -1,4 +0,0 @@
{
"instructions" : 3279,
"objectAllocCount" : 1
}
@@ -1,4 +0,0 @@
{
"instructions" : 3279,
"objectAllocCount" : 1
}
@@ -1,4 +0,0 @@
{
"instructions" : 3279,
"objectAllocCount" : 1
}
@@ -1,4 +0,0 @@
{
"instructions" : 3197,
"objectAllocCount" : 1
}
@@ -1,4 +0,0 @@
{
"instructions" : 3197,
"objectAllocCount" : 1
}
@@ -1,4 +0,0 @@
{
"instructions" : 3197,
"objectAllocCount" : 1
}
+72
View File
@@ -0,0 +1,72 @@
#===----------------------------------------------------------------------===#
#
# This source file is part of the Swift Logging API open source project
#
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
# Licensed under Apache License v2.0
#
# See LICENSE.txt for license information
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
#
# SPDX-License-Identifier: Apache-2.0
#
#===----------------------------------------------------------------------===#
cmake_minimum_required(VERSION 3.19)
# Initialize C language first to inspect the compiler environment
project(swift-log LANGUAGES C)
# Set Swift compiler target from C compiler target if not manually set for Windows
if(WIN32 AND NOT CMAKE_Swift_COMPILER_TARGET)
if(CMAKE_C_COMPILER_ARCHITECTURE_ID MATCHES "(ARM64|arm64|aarch64)")
set(CMAKE_Swift_COMPILER_TARGET "aarch64-unknown-windows-msvc" CACHE STRING "Swift compiler target triple")
elseif(CMAKE_C_COMPILER_ARCHITECTURE_ID MATCHES "(X86|x64|AMD64|x86_64)")
set(CMAKE_Swift_COMPILER_TARGET "x86_64-unknown-windows-msvc" CACHE STRING "Swift compiler target triple")
endif()
endif()
# Enable Swift after C defines the architecture
enable_language(Swift)
option(BUILD_SHARED_LIBS "Build shared libraries by default" YES)
set(CMAKE_Swift_LANGUAGE_VERSION 6)
if(CMAKE_Swift_COMPILER_VERSION VERSION_LESS "6.2.3")
message(FATAL_ERROR "swift-log requires Swift compiler version 6.2.3 or newer. Detected version: ${CMAKE_Swift_COMPILER_VERSION}")
endif()
set(SWIFT_LOG_COMMON_COMPILE_OPTIONS
"SHELL:-enable-upcoming-feature ExistentialAny"
"SHELL:-enable-upcoming-feature MemberImportVisibility"
"SHELL:-enable-upcoming-feature InternalImportsByDefault"
"SHELL:-enable-upcoming-feature NonisolatedNonsendingByDefault"
"SHELL:-Xfrontend -require-explicit-sendable"
"SHELL:-package-name swift_log")
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
set(CMAKE_Swift_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/swift)
if(MSVC)
message(STATUS "MSVC condition triggered successfully!")
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
set(CMAKE_Swift_COMPILE_OPTIONS_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
endif()
include(GNUInstallDirs)
include(SwiftSupport)
if(NOT APPLE)
find_package(dispatch QUIET)
find_package(Foundation QUIET)
endif()
add_subdirectory(Sources)
add_subdirectory(cmake/modules)
-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.
+19 -24
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
@@ -104,17 +87,29 @@ directory, for example:
## Benchmarks
Benchmarks for `swift-log` are in a separate Swift Package in the `Benchmarks` subfolder of this repository.
They use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin.
Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `package-benchmark` to capture memory allocation statistics.
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `package-benchmark`.
They use the [`benchmark`](https://github.com/ordo-one/benchmark) plugin.
On Swift versions prior to 6.3 Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `benchmark` to capture memory allocation statistics.
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `benchmark`.
Afterwards you can run the benchmarks from CLI by going to the `Benchmarks` subfolder (e.g. `cd Benchmarks`) and invoking:
```
swift package benchmark
```
For more information please refer to `swift package benchmark --help` or the [documentation of `package-benchmark`](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark).
For more information please refer to `swift package benchmark --help` or the [documentation of `benchmark`](https://swiftpackageindex.com/ordo-one/benchmark/documentation/benchmark).
## How to contribute your work
Please open a pull request at https://github.com/apple/swift-log. Make sure the CI passes, and then wait for code review.
For non-trivial changes that affect the public API, it is good practice to have a discussion phase before writing code. Please follow the [proposal process](Sources/Logging/Docs.docc/Proposals/Proposals.md) to gather feedback and align on the approach with other contributors.
1. Prepare your change, keeping in mind that a good patch is:
- Concise, and contains as few changes as needed to achieve the end result.
- Tested, ensuring that any tests provided failed before the patch and pass after it.
- Documented, adding API documentation as needed to cover new functions and properties.
- Accompanied by a great commit message.
2. Open a pull request at https://github.com/apple/swift-log and wait for code review by the maintainers.
## Automated release process
This repository uses automated releases based on semantic versioning labels. See the [Auto Release Workflow documentation](https://github.com/apple/swift-temporal-sdk/blob/main/.github/workflows/README.md) for details.
-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`
+44 -34
View File
@@ -1,17 +1,4 @@
// swift-tools-version:6.0
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
// swift-tools-version:6.2.3
import PackageDescription
@@ -21,14 +8,34 @@ let package = Package(
.library(name: "Logging", targets: ["Logging"]),
.library(name: "InMemoryLogging", targets: ["InMemoryLogging"]),
],
traits: [
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
.trait(
name: "MaxLogLevelWarning",
description: "Warning and above available (compiles out trace, debug, info, notice)"
),
.trait(
name: "MaxLogLevelError",
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
),
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
// By default, no traits are enabled (all log levels available)
.default(enabledTraits: []),
],
targets: [
.target(
name: "Logging",
dependencies: []
dependencies: [],
exclude: ["CMakeLists.txt"]
),
.target(
name: "InMemoryLogging",
dependencies: ["Logging"]
dependencies: ["Logging"],
exclude: ["CMakeLists.txt"]
),
.testTarget(
name: "LoggingTests",
@@ -41,24 +48,27 @@ let package = Package(
]
)
for target in package.targets {
for target in package.targets
where [.executable, .test, .regular].contains(
target.type
) {
var settings = target.swiftSettings ?? []
settings.append(.enableExperimentalFeature("StrictConcurrency=complete"))
// https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md
// Require `any` for existential types.
settings.append(.enableUpcomingFeature("ExistentialAny"))
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
settings.append(.enableUpcomingFeature("MemberImportVisibility"))
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
settings.append(.enableUpcomingFeature("InternalImportsByDefault"))
// https://docs.swift.org/compiler/documentation/diagnostics/nonisolated-nonsending-by-default/
settings.append(.enableUpcomingFeature("NonisolatedNonsendingByDefault"))
// Ensure all public types are explicitly annotated as Sendable or not Sendable.
settings.append(.unsafeFlags(["-Xfrontend", "-require-explicit-sendable"]))
target.swiftSettings = settings
}
// --- STANDARD CROSS-REPO SETTINGS DO NOT EDIT --- //
for target in package.targets {
switch target.type {
case .regular, .test, .executable:
var settings = target.swiftSettings ?? []
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
settings.append(.enableUpcomingFeature("MemberImportVisibility"))
target.swiftSettings = settings
case .macro, .plugin, .system, .binary:
() // not applicable
@unknown default:
() // we don't know what to do here, do nothing
}
}
// --- END: STANDARD CROSS-REPO SETTINGS DO NOT EDIT --- //
+12 -2
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
@@ -17,7 +22,7 @@ choose from the many
The following snippet shows how to add SwiftLog to your Swift Package:
```swift
// swift-tools-version: 6.1
// swift-tools-version: 6.2.3
import PackageDescription
let package = Package(
@@ -62,3 +67,8 @@ The community has built numerous specialized logging backends.
A great way to discover available log backend implementations is searching the
[Swift Package Index](https://swiftpackageindex.com/search?query=swift-log)
for the `swift-log` keyword.
## Building with CMake
While Swift Package Manager (SPM) is the primary build system for development and testing, CMake build support is also available for integrated or mixed build environments if needed. Note that tests are not included in the CMake build, they are managed through Swift Package Manager with `swift test`.
-43
View File
@@ -1,43 +0,0 @@
# Security
This document specifies the security process for the SwiftLog project.
## Disclosures
### Private Disclosure Process
The SwiftLog maintainers ask that known and suspected vulnerabilities be
privately and responsibly disclosed by emailing
[sswg-security-reports@forums.swift.org](mailto:sswg-security-reports@forums.swift.org)
with the all the required detail.
**Do not file a public issue.**
#### When to report a vulnerability
* You think you have discovered a potential security vulnerability in SwiftLog.
* You are unsure how a vulnerability affects SwiftLog.
#### What happens next?
* A member of the team will acknowledge receipt of the report within 3
working days (United States). This may include a request for additional
information about reproducing the vulnerability.
* We will privately inform the Swift Server Work Group ([SSWG][sswg]) of the
vulnerability within 10 days of the report as per their [security
guidelines][sswg-security].
* Once we have identified a fix we may ask you to validate it. We aim to do this
within 30 days. In some cases this may not be possible, for example when the
vulnerability exists at the protocol level and the industry must coordinate on
the disclosure process.
* If a CVE number is required, one will be requested from [MITRE][mitre]
providing you with full credit for the discovery.
* We will decide on a planned release date and let you know when it is.
* Prior to release, we will inform major dependents that a security-related
patch is impending.
* Once the fix has been released we will publish a security advisory on GitHub
and in the Server → Security Updates category on the [Swift forums][swift-forums-sec].
[sswg]: https://github.com/swift-server/sswg
[sswg-security]: https://www.swift.org/sswg/security/
[swift-forums-sec]: https://forums.swift.org/c/server/security-updates/
[mitre]: https://cveform.mitre.org/
+16
View File
@@ -0,0 +1,16 @@
#===----------------------------------------------------------------------===#
#
# This source file is part of the Swift Logging API open source project
#
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
# Licensed under Apache License v2.0
#
# See LICENSE.txt for license information
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
#
# SPDX-License-Identifier: Apache-2.0
#
#===----------------------------------------------------------------------===#
add_subdirectory(Logging)
add_subdirectory(InMemoryLogging)
+28
View File
@@ -0,0 +1,28 @@
#===----------------------------------------------------------------------===#
#
# This source file is part of the Swift Logging API open source project
#
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
# Licensed under Apache License v2.0
#
# See LICENSE.txt for license information
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
#
# SPDX-License-Identifier: Apache-2.0
#
#===----------------------------------------------------------------------===#
add_library(InMemoryLogging
"InMemoryLogHandler.swift"
)
set_target_properties(InMemoryLogging PROPERTIES
INTERFACE_INCLUDE_DIRECTORIES "$<BUILD_INTERFACE:$<TARGET_PROPERTY:Swift_MODULE_DIRECTORY>>;$<BUILD_INTERFACE:$<TARGET_FILE_DIR:InMemoryLogging>>")
target_compile_options(InMemoryLogging PRIVATE
${SWIFT_LOG_COMMON_COMPILE_OPTIONS})
target_link_libraries(InMemoryLogging PRIVATE Logging)
_install_target(InMemoryLogging)
set_property(GLOBAL APPEND PROPERTY SwiftLog_EXPORTS InMemoryLogging)
@@ -12,8 +12,7 @@
//
//===----------------------------------------------------------------------===//
import Logging
import Synchronization
public import Logging
/// A custom log handler which just collects logs into memory.
/// You can then retrieve an array of those log entries.
@@ -35,7 +34,6 @@ import Synchronization
/// let logEntries = logger.entries
/// ```
///
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, *)
public struct InMemoryLogHandler: LogHandler {
public var metadata: Logger.Metadata = [:]
public var metadataProvider: Logger.MetadataProvider?
@@ -48,6 +46,8 @@ public struct InMemoryLogHandler: LogHandler {
public var level: Logger.Level
/// The message which was logged.
public var message: Logger.Message
/// The error which was logged.
public var error: (any Error)?
/// The metadata which was logged.
public var metadata: Logger.Metadata
@@ -56,17 +56,54 @@ public struct InMemoryLogHandler: LogHandler {
self.message = message
self.metadata = metadata
}
public init(
level: Logger.Level,
message: Logger.Message,
error: (any Error)?,
metadata: Logger.Metadata
) {
self.level = level
self.message = message
self.error = error
self.metadata = metadata
}
public static func == (lhs: Entry, rhs: Entry) -> Bool {
lhs.level == rhs.level
&& lhs.message == rhs.message
&& lhs.metadata == rhs.metadata
&& errorsEqual(lhs.error, rhs.error)
}
private static func errorsEqual(_ lhs: (any Error)?, _ rhs: (any Error)?) -> Bool {
switch (lhs, rhs) {
case (nil, nil):
return true
case let (l?, r?):
return "\(l)" == "\(r)" && String(reflecting: type(of: l)) == String(reflecting: type(of: r))
default:
return false
}
}
}
private final class LogStore: Sendable {
private let logs: Mutex<[Entry]> = .init([])
private final class LogStore: @unchecked Sendable {
private var _entries: [Entry] = []
private let lock = Lock()
fileprivate func append(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata) {
self.logs.withLock {
$0.append(
fileprivate func append(
level: Logger.Level,
message: Logger.Message,
error: (any Error)?,
metadata: Logger.Metadata
) {
self.lock.withLockVoid {
self._entries.append(
Entry(
level: level,
message: message,
error: error,
metadata: metadata
)
)
@@ -74,13 +111,13 @@ public struct InMemoryLogHandler: LogHandler {
}
fileprivate func clear() {
self.logs.withLock {
$0.removeAll()
self.lock.withLockVoid {
_entries.removeAll()
}
}
var entries: [Entry] {
self.logs.withLock { $0 }
self.lock.withLock { self._entries }
}
}
@@ -93,6 +130,27 @@ public struct InMemoryLogHandler: LogHandler {
self.init(logStore: .init())
}
public func log(event: LogEvent) {
var merged = self.metadata
if let provider = self.metadataProvider {
let provided = provider.get()
merged.merge(provided, uniquingKeysWith: { _, rhs in rhs })
}
if let eventMetadata = event.metadata {
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
}
self.logStore.append(
level: event.level,
message: event.message,
error: event.error,
metadata: merged
)
}
@available(*, deprecated, renamed: "log(event:)")
public func log(
level: Logger.Level,
message: Logger.Message,
@@ -102,14 +160,17 @@ public struct InMemoryLogHandler: LogHandler {
function: String,
line: UInt
) {
// 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(metadata ?? [:]) { $1 }
self.logStore.append(level: level, message: message, metadata: mergedMetadata)
self.log(
event: LogEvent(
level: level,
message: message,
metadata: metadata,
source: source,
file: file,
function: function,
line: line
)
)
}
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
+36
View File
@@ -0,0 +1,36 @@
#===----------------------------------------------------------------------===#
#
# This source file is part of the Swift Logging API open source project
#
# Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
# Licensed under Apache License v2.0
#
# See LICENSE.txt for license information
# See CONTRIBUTORS.txt for the list of Swift Logging API project authors
#
# SPDX-License-Identifier: Apache-2.0
#
#===----------------------------------------------------------------------===#
add_library(Logging
"Handlers/MultiplexLogHandler.swift"
"Handlers/StreamLogHandler.swift"
"Handlers/SwiftLogNoOpLogHandler.swift"
"Locks.swift"
"LogEvent.swift"
"LogHandler.swift"
"Logger+Attributes.swift"
"Logger+With.swift"
"Logger.swift"
"LoggingSystem.swift"
"MetadataProvider.swift"
)
set_target_properties(Logging PROPERTIES
INTERFACE_INCLUDE_DIRECTORIES "$<BUILD_INTERFACE:$<TARGET_PROPERTY:Swift_MODULE_DIRECTORY>>;$<BUILD_INTERFACE:$<TARGET_FILE_DIR:Logging>>")
target_compile_options(Logging PRIVATE
${SWIFT_LOG_COMMON_COMPILE_OPTIONS})
_install_target(Logging)
set_property(GLOBAL APPEND PROPERTY SwiftLog_EXPORTS Logging)
@@ -9,7 +9,7 @@ creating well-behaved libraries that don't overwhelm logging systems or misuse
severity levels. This practice provides clear guidance on when to use each
level.
### Motivation
### Motivation
Libraries must be well-behaved across various use cases and cannot assume
specific logging backend configurations. Using inappropriate log levels can
@@ -51,7 +51,7 @@ Each level serves different purposes:
- **Performance**: May impact performance; assume it won't be used in production.
- **Content**: Internal state, detailed operation flows, diagnostic information.
##### Debug Level
##### Debug Level
- **Usage**: May be enabled in some production deployments.
- **Performance**: Should not significantly undermine production performance.
- **Content**: High-level operation overview, connection events, major decisions.
@@ -128,7 +128,7 @@ logger.info("Request failed")
```swift
// ❌ Bad: Normal operations at info level flood production logs
logger.info("HTTP request received")
logger.info("Database query executed")
logger.info("Database query executed")
logger.info("Response sent")
// ✅ Good: Use appropriate levels instead
@@ -1,29 +1,88 @@
# 003: Accepting loggers in libraries
# 003: Logger propagation in libraries
Accept loggers through method parameters to ensure proper metadata propagation.
Propagate caller context by accepting a `Logger` parameter or reading the task-local
``Logger/current`` — never by constructing your own logger.
## Overview
Libraries should accept logger instances through method parameters rather than
storing them as instance variables. This practice ensures metadata (such as
correlation IDs) is properly propagated down the call stack, while giving
applications control over logging configuration.
Libraries should obtain a `Logger` in one of two ways: accept one through a method
parameter or read ``Logger/current`` from the task-local. Both approaches
preserve the caller's metadata, log level, and handler choice. Constructing a logger
inside a library — via ``Logger/init(label:)`` — takes those choices away from the
application and breaks metadata propagation.
### Motivation
When libraries accept loggers as method parameters, they enable automatic
propagation of contextual metadata attached to the logger instance. This is
especially important for distributed systems where correlation IDs must flow
through the entire request processing pipeline.
The application controls logging: which backend, which log level, which metadata
travels with each request. Libraries that participate in this picture obtain a logger
the application has set up, rather than constructing their own from scratch. This
ensures correlation IDs and other contextual metadata flow through the entire call
stack, and gives the application a single place to redirect or filter all log output.
Two propagation mechanisms are available, and they coexist. Choose the explicit
parameter when the library's API already accepts a `Logger` (or it's natural to add
one) — the call site stays declarative about what gets logged where. Choose the
task-local when adding a `logger:` parameter would pollute an API that otherwise has
no logging concern in its signature. Application code binds the initial task-local;
library code reads it and updates the metadata.
### Example
#### Recommended: Accept logger through method parameters
#### Recommended: Read ``Logger/current`` from the task-local
When there is no `logger:` parameter in the API, read the
task-local. The application's accumulated metadata (`request.id`, etc.) flows in
automatically without an explicit hand-off.
```swift
// ✅ Good: Pass the logger through method parameters.
// ✅ Good: Library reads Logger.current; caller scopes context via withLogger.
public struct AnalyticsClient {
public func track(_ event: String) {
Logger.current.info("event", metadata: ["event.name": "\(event)"])
}
}
// Application binds at @main and scopes per-request metadata.
@main
struct MyServer {
static func main() async throws {
let logger = Logger(label: "my-server")
try await withLogger(logger) { _ in
try await runServices()
}
}
}
func handleRequest(_ req: HTTPRequest) async throws {
try await withLogger(mergingMetadata: ["request.id": "\(req.id)"]) { _ in
AnalyticsClient().track("request.received") // sees request.id automatically
}
}
```
For per-statement metadata, pass it via the `metadata:` parameter on the log call:
```swift
Logger.current.info("step", metadata: ["step.name": "validate"])
```
For a few back-to-back lines, take a local copy and stamp metadata there — also no
propagation:
```swift
var local = Logger.current
local[metadataKey: "step.name"] = "validate"
local.info("entering")
local.info("done")
```
#### Alternative: Accept logger through method parameters
```swift
// ✅ Good: Pass the logger through method parameters,
// default to Logger.current in the public API.
struct RequestProcessor {
func processRequest(_ request: HTTPRequest, logger: Logger) async throws -> HTTPResponse {
func processRequest(_ request: HTTPRequest, logger: Logger = Logger.current) async throws -> HTTPResponse {
// Add structured metadata that every log statement should contain.
var logger = logger
logger[metadataKey: "request.method"] = "\(request.method)"
@@ -31,44 +90,40 @@ struct RequestProcessor {
logger[metadataKey: "request.id"] = "\(request.id)"
logger.debug("Processing request")
// Pass the logger down to maintain metadata context.
let validatedData = try validateRequest(request, logger: logger)
let result = try await executeBusinessLogic(validatedData, logger: logger)
logger.debug("Request processed successfully")
return result
}
private func validateRequest(_ request: HTTPRequest, logger: Logger) throws -> ValidatedRequest {
logger.debug("Validating request parameters")
// Include validation logic that uses the same logger context.
return ValidatedRequest(request)
}
private func executeBusinessLogic(_ data: ValidatedRequest, logger: Logger) async throws -> HTTPResponse {
logger.debug("Executing business logic")
// Further propagate the logger to other services.
let dbResult = try await databaseService.query(data.query, logger: logger)
logger.debug("Business logic completed")
return HTTPResponse(data: dbResult)
}
}
```
#### Alternative: Accept logger through initializer when appropriate
#### Alternative: Accept logger through initializer for long-lived components
```swift
// ✅ Acceptable: Logger through initializer for long-lived components
// ⚠️ Acceptable: Logger through initializer for long-lived components
final class BackgroundJobProcessor {
private let logger: Logger
init(logger: Logger) {
self.logger = logger
}
func run() async {
// Execute some long running work
logger.debug("Update about long running work")
@@ -79,22 +134,52 @@ final class BackgroundJobProcessor {
#### Avoid: Libraries creating their own loggers
Libraries might create their own loggers; however, this leads to two problems.
First, users of the library can't inject their own loggers which means they have
no control in customizing the log level or log handler. Secondly, it breaks the
metadata propagation since users can't pass in a logger with already attached
metadata.
Constructing ``Logger/init(label:)`` inside a library takes control over the handler, log
level, and base metadata away from the application. The application cannot redirect,
filter, or silence the library's output.
```swift
// ❌ Bad: Library creates its own logger
// ❌ Bad: Library creates its own logger — loses caller's context.
final class MyLibrary {
private let logger = Logger(label: "MyLibrary") // Loses all context
}
// ✅ Good: Library accepts logger from caller
final class MyLibrary {
func operation(logger: Logger) {
// Maintains caller's context and metadata
}
private let logger = Logger(label: "MyLibrary")
}
```
``Logger/init(label:)`` is for the application — typically at `@main` paired with `.withLogger()`.
Library code, including internal application modules, should not construct loggers.
If they do, setting up the global factory with ``LoggingSystem/bootstrap(_:)`` allows
enforcing a specific factory on all the loggers constructed in the process. This
does not necessary need to be the same factory as was used to create the task-local
logger.
#### Avoid: Relying on ``Logger/current`` across non-Task boundaries
``Logger/current`` is backed by a `TaskLocal` and propagates through Swift's structured
concurrency model only. Callbacks invoked on non-Task threads — GCD blocks,
`URLSession` completion handlers, delegate methods dispatched onto specific queues,
`NotificationCenter` observers, C-API callbacks — see the *default* fallback logger,
not the bound one. Metadata bound by the calling `Task` is invisible inside those
callbacks.
```swift
// ❌ Bad: completion handler runs without the Task context; Logger.current is the fallback.
try await withLogger(mergingMetadata: ["request.id": "r1"]) { _ in
URLSession.shared.dataTask(with: req) { data, _, _ in
Logger.current.info("response") // empty-label fallback, no request.id
}.resume()
}
```
For libraries with async completion-handler APIs, accept an explicit `Logger` parameter.
If capturing and rebinding across the boundary is the only option:
```swift
// ✅ Good: capture before the boundary, rebind on the other side.
try await withLogger(mergingMetadata: ["request.id": "r1"]) { captured in
URLSession.shared.dataTask(with: req) { data, _, _ in
withLogger(captured) { _ in // Bind Logger.current inside the callback
Logger.current.info("response") // Logger.current now has request.id
}
}.resume()
}
```
@@ -0,0 +1,81 @@
# 004: Testing code that logs
Validate what you code logs by capturing entries in memory rather than bootstrapping a process-wide backend.
## Overview
Import and use `InMemoryLogging`, which provides an `InMemoryLogHandler` that collects every emitted record into an array you can inspect.
Keep a handler you create local to each test.
Each handler that you create in a test has no shared state, so the test stays isolated is safe to run on parallel with other tests.
Don't use ``LoggingSystem/bootstrap(_:)`` in a test, it sets one process-wide backend and traps if called twice.
Add the product to your test target:
```swift
.product(name: "InMemoryLogging", package: "swift-log")
```
### Capture logs from a logger you pass in
When the code under test accepts a `Logger` (see <doc:003-AcceptingLoggers>), back it with
an `InMemoryLogHandler` and validate the results on `entries`.
The following code illustrates how to set up and validate a handler using `InMemoryLogging` to check the expected results:
```swift
import InMemoryLogging
import Logging
import Testing
struct RequestProcessor {
func handle(id: String, logger: Logger) {
logger.info("request received", metadata: ["request.id": "\(id)"])
}
}
@Test
func stampsRequestID() {
let handler = InMemoryLogHandler()
let logger = Logger(label: "test", factory: { _ in handler })
RequestProcessor().handle(id: "42", logger: logger)
#expect(handler.entries.count == 1)
#expect(handler.entries[0].message == "request received")
#expect(handler.entries[0].metadata["request.id"] == "42")
}
```
Each `Entry` is equatable and exposes `level`, `message`, `metadata`, and `error`.
The handler log level defaults to ``Logger/Level/info``; set `handler.logLevel = .trace` before you use it to
capture lower levels.
### Capture logs from code that reads `Logger.current`
When the code you want to test reads the task-local ``Logger/current`` instead of taking a parameter, bind an `InMemoryLogHandler` for the scope of that by using ``withLogger(logLevel:handler:metadata:_:)-2pd9p``.
The handler shares its storage by reference, so the copy you hold sees what was logged.
Bind the handler for the scope of the call and validate the captured entry:
```swift
import InMemoryLogging
import Logging
import Testing
struct AnalyticsClient {
func track(_ event: String) {
Logger.current.info("event", metadata: ["event.name": "\(event)"])
}
}
@Test
func tracksEvent() {
let handler = InMemoryLogHandler()
withLogger(handler: handler) { _ in
AnalyticsClient().track("signup") // calls Logger.current.info(...)
}
#expect(handler.entries.count == 1)
#expect(handler.entries[0].metadata["event.name"] == "signup")
}
```
@@ -0,0 +1,84 @@
# Disable log levels during compilation
SwiftLog provides compile-time traits to eliminate less severe log levels from
your binary reducing the runtime overhead.
## Overview
### Motivation
When deploying applications to production, you often know in advance which log
levels will never be needed. For example, a production service might only need
warning and above, while trace and debug levels are only useful during
development. By using traits, you can completely remove these unnecessary log
levels at compile time, achieving zero runtime overhead.
### Available traits
SwiftLog defines seven maximum log level traits, ordered from most permissive
to most restrictive:
- `MaxLogLevelDebug`: Debug and above available (compiles out trace)
- `MaxLogLevelInfo`: Info and above available (compiles out trace, debug)
- `MaxLogLevelNotice`: Notice and above available (compiles out trace, debug,
info)
- `MaxLogLevelWarning`: Warning and above available (compiles out trace, debug,
info, notice)
- `MaxLogLevelError`: Error and above available (compiles out trace, debug,
info, notice, warning)
- `MaxLogLevelCritical`: Only critical available (compiles out all except
critical)
- `MaxLogLevelNone`: All logging compiled out (no log levels available)
By default (when no traits are specified), all log levels are available.
When you specify a maximum log level trait, all less severe levels are
completely removed from your binary at compile time. This applies to both
level-specific methods (e.g., `logger.debug()`) and calls to the generic
`logger.log(level:)` method. Traits are additive. If multiple max level traits
are specified, the most restrictive one takes effect.
> Note: Traits should only be set by the applications and not libraries as
> any traits defined in a transitive dependency will affect the whole resolution tree.
### Example
To enable a trait, specify it when declaring your package dependency:
```swift
// In your Package.swift:
dependencies: [
.package(
url: "https://github.com/apple/swift-log.git",
from: "1.0.0",
traits: ["MaxLogLevelWarning"]
)
]
```
With `MaxLogLevelWarning` enabled, all trace, debug, info, and notice log
statements are compiled out:
```swift
// These become no-ops (compiled out completely):
logger.trace("This will not be in the binary")
logger.debug("This will not be in the binary")
logger.info("This will not be in the binary")
logger.notice("This will not be in the binary")
logger.log(level: .debug, "This will not log anything")
// These work normally:
logger.warning("This still works")
logger.error("This still works")
logger.critical("This still works")
logger.log(level: .error, "This still works")
```
When `MaxLogLevelNone` is enabled no log statement can ever fire, so
mutations that only configure the underlying ``LogHandler`` for future log
statements are also compiled out. Specifically, the body of the
``Logger/subscript(metadataKey:)`` setter and the body of the
``Logger/logLevel`` setter become empty, so calls like
`logger[metadataKey: "user-id"] = "\(id)"` and `logger.logLevel = .info`
do not reach the handler. Reads continue to work and return whatever the
handler reports.
@@ -23,11 +23,11 @@ func logHandlerValueSemantics() {
var logger1 = Logger(label: "first logger")
logger1.logLevel = .debug
logger1[metadataKey: "only-on"] = "first"
var logger2 = logger1
logger2.logLevel = .error // Must not affect logger1
logger2[metadataKey: "only-on"] = "second" // Must not affect logger1
// These expectations must pass
#expect(logger1.logLevel == .debug)
#expect(logger2.logLevel == .error)
@@ -51,37 +51,29 @@ public struct PrintLogHandler: LogHandler {
private let label: String
public var logLevel: Logger.Level = .info
public var metadata: Logger.Metadata = [:]
public init(label: String) {
self.label = label
}
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
public func log(event: LogEvent) {
let timestamp = ISO8601DateFormatter().string(from: Date())
let levelString = level.rawValue.uppercased()
let levelString = event.level.rawValue.uppercased()
// Merge handler metadata with message metadata
let combinedMetadata = Self.prepareMetadata(
base: self.metadata
explicit: metadata
base: self.metadata,
explicit: event.metadata
)
// Format metadata
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
// Create log line and print to console
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(event.message)"
print(logLine)
}
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get {
return self.metadata[key]
@@ -110,6 +102,136 @@ public struct PrintLogHandler: LogHandler {
```
### Constructing handlers that need more than a label
Many log handler backends need more than a `label` in order to construct them: a file path, a remote address, credentials, or
a buffer. A handler is an ordinary value that you construct, so nothing constrains its
initializer — it can take any parameters it needs, and it can `throw`. There is no
protocol-required `init(label:)`. The single `label` argument on factory methods such as
`StreamLogHandler.standardOutput(label:)` is a convention, not a requirement.
Open expensive or fallible resources, such as a file, a socket, early and up front in your own initializer that can `throw`, so that failures surface at setup time.
``LogHandler/log(event:)`` cannot throw, so an error deferred to logging time has nowhere to go.
Keep the handler `struct` cheap and copyable by placing any shared resource behind a thread-safe reference type.
Value semantics apply to a handler's *configuration* — its level and metadata — not its *destination*, so copies writing to
the same file are correct and expected.
The `FileLogHandler` below opens its file once, in an initializer that throws and exception when you create it with an overlapping `Destination`.
The handler `struct` itself stays a cheap, copyable value:
```swift
import Foundation
import Logging
import Synchronization
/// A log handler that appends formatted log lines to a file on disk.
public struct FileLogHandler: LogHandler {
/// The shared, thread-safe destination. Open it once, then share it across handlers: because
/// the destination is a reference type, all those value-semantic handlers write through a single
/// locked file handle.
public final class Destination: @unchecked Sendable {
private let fileHandle: Mutex<FileHandle>
/// Opens `url` for appending. All validation happens here, at setup time.
public init(writingTo url: URL) throws {
let fileManager = FileManager.default
if !fileManager.fileExists(atPath: url.path) {
guard fileManager.createFile(atPath: url.path, contents: nil) else {
throw Failure.cannotCreateFile(url)
}
}
self.fileHandle = .init(try FileHandle(forWritingTo: url))
_ = try self.fileHandle.withLock { try $0.seekToEnd() }
}
func write(_ line: String) {
// `log(event:)` cannot throw, so a write failure is handled here, not propagated.
do {
try self.fileHandle.withLock { try $0.write(contentsOf: Data(line.utf8)) }
} catch {
// Surface the failure without crashing the application.
try? FileHandle.standardError.write(contentsOf: Data("FileLogHandler: \(error)\n".utf8))
}
}
/// Flushes and closes the file. Call this during shutdown.
public func close() {
self.fileHandle.withLock { try? $0.close() }
}
}
/// Errors thrown while opening a ``Destination``.
public enum Failure: Error {
case cannotCreateFile(URL)
}
private let label: String
private let destination: Destination
// Per-logger configuration — this is what must carry value semantics.
public var logLevel: Logger.Level = .info
public var metadata: Logger.Metadata = [:]
public var metadataProvider: Logger.MetadataProvider?
/// Cheap and non-throwing, so it is safe to call from a bootstrap factory closure per label.
public init(label: String, destination: Destination, metadataProvider: Logger.MetadataProvider? = nil) {
self.label = label
self.destination = destination
self.metadataProvider = metadataProvider
}
public func log(event: LogEvent) {
var merged = self.metadata
if let provided = self.metadataProvider?.get() {
merged.merge(provided, uniquingKeysWith: { _, new in new })
}
if let explicit = event.metadata {
merged.merge(explicit, uniquingKeysWith: { _, new in new })
}
let renderedMetadata =
merged.isEmpty
? ""
: " " + merged.sorted { $0.key < $1.key }.map { "\($0.key)=\($0.value)" }.joined(separator: " ")
self.destination.write("\(event.level) \(self.label):\(renderedMetadata) \(event.message)\n")
}
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get { self.metadata[key] }
set { self.metadata[key] = newValue }
}
}
```
#### Using your log handler
Construct the destination where you can use `try` to build a logger backed by your handler, then bind it
as ``Logger/current`` for the application's lifetime using `withLogger`:
```swift
// Open the file once, where setup can throw.
let destination = try FileLogHandler.Destination(writingTo: URL(fileURLWithPath: "/var/log/myapp.log"))
defer { destination.close() }
// Build a logger backed by the handler, then bind it for the scope.
let logger = Logger(label: "app") { label in
FileLogHandler(label: label, destination: destination)
}
try await withLogger(logger) { logger in
logger.info("Application started")
// Code in this scope reads the handler through Logger.current.
}
```
The `try` on `Destination` is where setup fails if the path is unwritable: validation happens
before the logger is constructed, so you never need a throwing factory overload.
Use the same pattern for handlers that connect to a remote service:
- validate and connect up front
- keep ``LogHandler/log(event:)`` non-blocking by buffering onto a background task
- provide a `close()` or `shutdown()` (or use [Swift Service Lifecycle](https://github.com/swift-server/swift-service-lifecycle) service) to flush on shutdown
For runtime failures the handler can't avoid, such as a full disk or a broken pipe, degrade gracefully inside `log(event:)` by dropping the log message, retrying, or reporting to `stderr`.
Never call `fatalError` on the logging path.
### Advanced features
#### Metadata providers
@@ -128,41 +250,30 @@ public struct PrintLogHandler: LogHandler {
public var logLevel: Logger.Level = .info
public var metadata: Logger.Metadata = [:]
public var metadataProvider: Logger.MetadataProvider?
public init(label: String) {
self.label = label
}
public func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
public func log(event: LogEvent) {
let timestamp = ISO8601DateFormatter().string(from: Date())
let levelString = level.rawValue.uppercased()
// Get provider metadata
let providerMetadata = metadataProvider?.get() ?? [:]
let levelString = event.level.rawValue.uppercased()
// Merge handler metadata with message metadata
let combinedMetadata = Self.prepareMetadata(
base: self.metadata,
provider: self.metadataProvider,
explicit: metadata
explicit: event.metadata
)
// Format metadata
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
// Create log line and print to console
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(event.message)"
print(logLine)
}
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
get {
return self.metadata[key]
@@ -176,7 +287,7 @@ public struct PrintLogHandler: LogHandler {
base: Logger.Metadata,
provider: Logger.MetadataProvider?,
explicit: Logger.Metadata?
) -> Logger.Metadata? {
) -> Logger.Metadata {
var metadata = base
let provided = provider?.get() ?? [:]
@@ -199,6 +310,49 @@ public struct PrintLogHandler: LogHandler {
}
```
#### Reading metadata attributes in LogHandlers
Metadata values can carry attributes alongside their string representation. Attributes are embedded inside
`MetadataValue` via the `.stringConvertible` case and are accessible through the `value.attributes` property. This
enables features like sensitivity annotations without any changes to your handler's protocol conformance.
To read attributes in your log handler:
```swift
public func log(event: LogEvent) {
// Merge handler metadata, provider metadata, and event metadata as usual
var merged = self.metadata
if let provider = self.metadataProvider {
merged.merge(provider.get(), uniquingKeysWith: { _, rhs in rhs })
}
if let eventMetadata = event.metadata {
merged.merge(eventMetadata, uniquingKeysWith: { _, rhs in rhs })
}
// Read attributes from individual values:
for (key, value) in merged {
let attributes = value.attributes // Empty if the value carries no attributes
// Process based on your handler's needs
// For example, check for a custom attribute:
// if attributes[MyAttribute.self] == .flagged { ... }
}
}
```
**Key considerations:**
- **Opt-in inspection**: Attributes are invisible unless you call `value.attributes`. Handlers that do not care about
attributes work without any changes.
- **No new protocol requirements**: Reading attributes does not require implementing any new `LogHandler` properties
or subscripts. The `metadata` property and `metadataKey` subscript work exactly as before.
- **Attributes flow through metadata**: Attributed values flow naturally through metadata merging, `MetadataProvider`,
and `MultiplexLogHandler` — no special handling needed.
### Performance considerations
1. **Avoid blocking**: Don't block the calling thread for I/O operations.
@@ -41,3 +41,4 @@ practice includes:
- <doc:001-ChoosingLogLevels>
- <doc:002-StructuredLogging>
- <doc:003-AcceptingLoggers>
- <doc:004-TestingLogging>
@@ -35,4 +35,15 @@ If you have any questions, ask in an issue on GitHub.
## Topics
### Implemented Proposals
- <doc:SLG-0001-metadata-providers>
- <doc:SLG-0002>
- <doc:SLG-0003>
- <doc:SLG-0004-metadata-value-attributes>
- <doc:SLG-0005-log-event-LogHandler-API>
- <doc:SLG-0006-task-local-logger>
### Proposal Template
- <doc:SLG-NNNN>
@@ -1,11 +1,11 @@
# Metadata Providers
Authors: [Moritz Lang](https://github.com/slashmo), [Konrad 'ktoso' Malawski](https://github.com/ktoso)
## Introduction
# SLG-0001: Metadata Providers
While global metadata attributes may be manually set on a `LogHandler` level, there's currently no way of reliably providing contextual, automatically propagated, metadata when logging with swift-log.
## Authors
[Moritz Lang](https://github.com/slashmo), [Konrad 'ktoso' Malawski](https://github.com/ktoso)
## Motivation
To benefit from tools such as [Distributed Tracing](https://github.com/apple/swift-distributed-tracing) it is necessary for libraries to make use of the trace information.
@@ -0,0 +1,173 @@
# SLG-0002: Compile-time log level elimination using traits
Enable compile-time elimination of log levels to achieve zero runtime overhead for logs that will never be needed in production.
## Overview
- Proposal: SLG-0002
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
- Status: **Approved**
- Issue: [apple/swift-log#378](https://github.com/apple/swift-log/issues/378)
- Implementation:
- [apple/swift-log#389](https://github.com/apple/swift-log/pull/389)
- Related links:
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
### Introduction
Add Swift package traits to allow applications to compile out less severe log levels, completely eliminating their runtime overhead from the final binary.
### Motivation
In production deployments, applications often know in advance which log levels will never be needed. For example, a production service typically only needs warning and above, while trace and debug levels are exclusively useful during development. Currently, even with the log level set to `.warning` at runtime, the code for trace and debug statements still exists in the binary and incurs overhead.
For performance-critical applications or resource-constrained environments, this overhead is unacceptable. Applications need a way to completely remove unnecessary log levels at compile time, achieving zero runtime cost.
Before this proposal, the only workarounds were:
- Manually wrapping log statements in `#if DEBUG` checks (error-prone and verbose)
- Accepting the runtime overhead (unacceptable for many use cases)
### Proposed solution
This proposal introduces seven package traits that correspond to maximum log level thresholds. Applications specify a trait when declaring their dependency on SwiftLog, and all less severe log levels are completely compiled out.
In your `Package.swift`:
```swift
dependencies: [
.package(
url: "https://github.com/apple/swift-log.git",
from: "1.0.0",
traits: ["MaxLogLevelWarning"]
)
]
```
With `MaxLogLevelWarning` enabled:
```swift
// These become no-ops (compiled out completely):
logger.trace("This will not be in the binary")
logger.debug("This will not be in the binary")
logger.info("This will not be in the binary")
logger.notice("This will not be in the binary")
logger.log(level: .debug, "This will not log anything")
// These work normally:
logger.warning("This still works")
logger.error("This still works")
logger.critical("This still works")
logger.log(level: .error, "This still works")
```
### Detailed design
The seven available traits, ordered from most permissive to most restrictive, are:
```swift
traits: [
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
.trait(
name: "MaxLogLevelWarning",
description: "Warning and above available (compiles out trace, debug, info, notice)"
),
.trait(
name: "MaxLogLevelError",
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
),
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
.default(enabledTraits: []),
]
```
By default (when no traits are specified), all log levels remain available.
Traits are additive: if multiple max level traits are specified in the dependency graph, the most restrictive one takes effect. This ensures that if any dependency requests stricter elimination, the entire build respects it.
> Important: Traits should only be set by applications, not libraries, as any trait defined in a transitive dependency will affect the entire dependency resolution tree.
For the generic `log(level:)` method, the implementation switches behavior based on whether any trait is enabled:
```swift
public func log(
level: Logger.Level,
_ message: @autoclosure () -> Logger.Message,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
) {
#if MaxLogLevelDebug || MaxLogLevelInfo || MaxLogLevelNotice || MaxLogLevelWarning || MaxLogLevelError || MaxLogLevelCritical || MaxLogLevelNone
// When traits are enabled, dispatch to level-specific methods
// to leverage their compile-time elimination
switch level {
case .trace:
self.trace(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
case .debug:
self.debug(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
// ... (all levels)
}
#else
// When no traits are enabled, avoid the switch overhead
self._log(
level: level,
message(),
metadata: metadata(),
source: source(),
file: file,
function: function,
line: line
)
#endif
}
```
This approach adds a minimal switch statement overhead when traits are enabled, but allows the level-specific methods' compile-time elimination to work even when called through `log(level:)`. When no traits are enabled, the original zero-overhead path is preserved. Level-specific methods has no additional overhead.
### API stability
**For existing `Logger` users:**
- When no traits are enabled (the default), behavior is identical to before
- Users can opt in to traits at the application level without modifying any source code
**For existing `LogHandler` implementations:**
- No changes are required to any `LogHandler` implementation
### Future directions
No future directions identified.
### Alternatives considered
#### Per-log-level traits
An alternative approach would be to define one trait per log level that could be individually disabled:
```swift
traits: [
.trait(name: "DisableTraceLogs"),
.trait(name: "DisableDebugLogs"),
.trait(name: "DisableInfoLogs"),
.trait(name: "DisableNoticeLogs"),
.trait(name: "DisableWarningLogs"),
.trait(name: "DisableErrorLogs"),
.trait(name: "DisableCriticalLogs"),
]
```
Users would specify multiple traits to eliminate multiple levels:
```swift
.package(
url: "https://github.com/apple/swift-log.git",
from: "1.0.0",
traits: ["DisableTraceLogs", "DisableDebugLogs", "DisableInfoLogs", "DisableNoticeLogs"]
)
```
This approach was rejected in favor of a `MaxLogLevel` semantics to make it less verbose to use the functionality and to be aligned with the similar functionality in logging packages in other languages users might already be familiar with.
@@ -0,0 +1,416 @@
# SLG-0003: Support for Attaching Errors to Log Entries
Add standardized way of attaching data from `Error` instances to log entries.
## Overview
- Proposal: SLG-0003
- Author(s): [Samuel Murray](https://github.com/samuelmurray)
- Status: **Approved**
- Issue: [apple/swift-log#291](https://github.com/apple/swift-log/issues/291)
- Implementation:
- [apple/swift-log#425](https://github.com/apple/swift-log/pull/425)
- Related links:
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
- [First attempt at solution](https://github.com/apple/swift-log/pull/384)
### Introduction
Add new methods on `Logger` that accept an `Error` instance, which is passed as-is to the underlying `LogHandler`. To ensure backwards compatibility and a smooth adoption, a default implementation where the error is serialized into `MetadataValue`s is provided.
### Motivation
SwiftLog advocates for the use of _structured logging_, which in its implementation is achieved by using the `metadata` attribute in the log methods. This is important since it allows for automated tools to parse the logs and extract metadata values for filtering and/or visualization. When logging in a catch-block, it often makes sense to attach some information from the thrown `Error` in the log post, so as to capture the root cause.
```swift
do {
try someThrowingFunc()
} catch {
logger.warning("Something went wrong") // Want to somehow attach information about the error
}
```
Currently, there is no standardized way of doing this. The simplest way to do it would be to simply attach the stringified error to the message.
```swift
logger.warning("Something went wrong: \(error)")
```
This of course is not _structured_, so a better way would be:
```swift
logger.warning("Something went wrong", metadata: ["error": "\(error)"])
```
However, since there is no clear preference for what metadata key to use, it is likely that different code bases use variations of the above. This makes it hard for automated tools to extract error information, since there is no single key to look for.
Additionally, there is more information that we could extract from the error, such as the type name.
```swift
logger.warning("Something went wrong", metadata: ["error.message": "\(error)", "error.type": "\(String(reflecting: type(of: error)))"])
```
The above is a reasonable way to log a generic error, but it is unlikely that everyone will use the same metadata keys. It is also quite a lot of code, for something that feels like it should be easy to do - i.e. attach an error to a log.
Finally, even if you log errors in a consistent way in your code, you do not control logs generated in other modules/packages that you use. In practice, this makes it so that different parts of your application could log error information under different keys, which, again, makes it harder for tooling.
### Proposed solution
The solution we propose is to add convenience methods in `Logger` that allows the caller to do the following:
```swift
do {
try someThrowingFunc()
} catch {
logger.warning("Something went wrong", error: error)
}
```
The error would get passed as-is to the underlying `LogHandler`, which is free to serialize it in an appropriate way. We propose that such convenience methods are added for all log methods (even if it arguably makes less sense for e.g. `trace` and `debug` than `warning`).
There are two clear gains from this:
* It is obvious for the caller _how_ to attach an `Error` to a log (and the caller code also looks cleaner).
* `LogHandler`s are free to serialize the `Error` in an way appropriate to that handler.
A `LogHandler` instance can access the `Error` using a new protocol method. A typical `LogHandler` implementation could be to extract the string representation and type name, and serialize it as metadata.
```swift
struct ErrorLogHandler: LogHandler {
func log(
level: Logger.Level,
message: Logger.Message,
error: (any Error)?,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
) {
var metadata = metadata ?? [:]
if let error {
metadata.merge([
"error.message": "\(error)",
"error.type": "\(String(reflecting: type(of: error)))",
]) { $1 }
}
// ...
}
/* ... */
}
```
As we extend the API of both `Logger` and `LogHandler`, we need to ensure compatibility with existing solutions on both sides. Specifically, users should be able to use the new `Logger` methods with existing `LogHandler`s, and get a reasonable serialization of the error. Otherwise, early adopters would have to manually serialize it _in addition to_ passing it using the new argument, until all `LogHandler`s have been updated. To achieve this, we add a default implementation on the `LogHandler` method, that serializes the `Error` as metadata, similar to the example above.
### Detailed design
The proposed solution is to add a new overload for each log method (`trace`, ..., `critical`) that accepts an `Error` as its second argument, as well as a new overload for `Logger.log`, that accepts an `Error` as its third argument.
```swift
extension Logger {
/// Log a message at the 'trace' log level with the source that you provide.
///
/// If ``Level/trace`` is at least as severe as this logger's ``logLevel`` the system logs the message;
/// otherwise nothing will happen.
///
/// - parameters:
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func trace(
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
/// Log a message at the 'debug' log level with the source that you provide.
///
/// If ``Level/debug`` is at least as severe as this logger's ``logLevel`` the system logs the message;
/// otherwise nothing will happen.
///
/// - parameters:
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func debug(
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
/// Log a message at the 'info' log level with the source that you provide.
///
/// If ``Level/info`` is at least as severe as this logger's ``logLevel`` the system logs the message;
/// otherwise nothing will happen.
///
/// - parameters:
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func info(
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
/// Log a message at the 'notice' log level with the source that you provide.
///
/// If ``Level/notice`` is at least as severe as this logger's ``logLevel`` the system logs the message;
/// otherwise nothing will happen.
///
/// - parameters:
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func notice(
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
/// Log a message at the 'warning' log level with the source that you provide.
///
/// If ``Level/warning`` is at least as severe as this logger's ``logLevel`` the system logs the message;
/// otherwise nothing will happen.
///
/// - parameters:
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func warning(
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
/// Log a message at the 'error' log level with the source that you provide.
///
/// If ``Level/error`` is at least as severe as this logger's ``logLevel`` the system logs the message;
/// otherwise nothing will happen.
///
/// - parameters:
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func error(
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
/// Log a message at the 'critical' log level with the source that you provide.
///
/// If ``Level/critical`` is at least as severe as this logger's ``logLevel`` the system logs the message;
/// otherwise nothing will happen.
///
/// - parameters:
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func critical(
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
/// Log a message using the log level and source that you provide.
///
/// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library
/// logs the message, otherwise nothing will happen.
///
/// - parameters:
/// - level: The severity level of the `message`.
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
/// - error: An `Error` to attach to this log message.
/// - metadata: One-off metadata to attach to this log message.
/// - source: The source this log message originates from. The value defaults
/// to the module that emits the log message.
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#fileID`.
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
/// it defaults to `#function`.
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
/// defaults to `#line`.
@inlinable
public func log(
level: Logger.Level,
_ message: @autoclosure () -> Logger.Message,
error: (any Error)?,
metadata: @autoclosure () -> Logger.Metadata? = nil,
source: @autoclosure () -> String? = nil,
file: String = #fileID,
function: String = #function,
line: UInt = #line
)
}
```
A new method is also added to `LogHandler`, which receives the `Error` passed to `Logger`.
```swift
protocol LogHandler {
/// The library calls this method when a log handler must emit a log message.
///
/// There is no need for the `LogHandler` to check if the `level` is above or
/// below the configured `logLevel` as `Logger` already performed this check and
/// determined that a message should be logged.
///
/// - Parameters:
/// - level: The log level of the message.
/// - message: The message to log. To obtain a `String` representation call `message.description`.
/// - error: The `Error` associated to this log message.
/// - metadata: The metadata associated to this log message.
/// - source: The source where the log message originated, for example the logging module.
/// - file: The file this log message originates from.
/// - function: The function this log message originates from.
/// - line: The line this log message originates from.
func log(
level: Logger.Level,
message: Logger.Message,
error: (any Error)?,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
)
}
```
A default implementation is included via an extension method, that calls the existing `log` function. This is to ensure backwards compatibility, and is similar to how `source` was added. The default implementation will serialize the `Error`, extracting its string representation and fully qualified type name, and add those to the metadata under the keys `"error.message"` and `"error.type"` respectively.
A draft implementation can be found in [apple/swift-log#425](https://github.com/apple/swift-log/pull/425).
We choose the keys `"error.message"` and `"error.type"` since they correspond to what [ECS](https://www.elastic.co/docs/reference/ecs/ecs-error) and [OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/#error-type) use. However, we propose that the metadata keys used should **not** be considered stable or part of the `swift-log` API. Instead, if a `LogHandler` wants to use separate keys, it should implement the new protocol method, rather than re-map the metadata keys.
### API stability
The proposed additions are fully backwards compatible, meaning that all existing code will continue to function as is. Additionally, a user of `Logger` can start using the new convenience methods, without any modifications of the `LogHandler`, thanks to the default implementation and since a `LogHandler` is already expected to handle `Metadata`.
However, when using the default implementation, a potential metadata collision exists when an `Error` is passed via the new methods while the same keys (`"error.message"`, `"error.type"`) are present in metadata:
```swift
logger.warning("Something went wrong", error: error, metadata: ["error.message": "some other info"])
```
We recommend that the `error` parameter takes precedence in such cases, with conflicting metadata values discarded. This aligns with the principle that explicit `error:` parameters represent primary data, while the same keys in metadata are likely incidental. In practice, we don't expect callers to deliberately pass conflicting error information.
Conversely, a `LogHandler` can implement the new protocol method, and still function with existing users of `Logger` - the `error` parameter will then always be `nil`.
### Future directions
#### recordError
If `swift-log` develops better support for scoped loggers, it might be possible to add a `recordError` method on `Logger`, that would attach the `Error` to all logs in that scope.
### Alternatives considered
#### Standardized Error metadata via Logger convenience
The first proposed solution was to treat the new `Logger` methods as "convenience methods", that simply serialized the `Error` as metadata and did not pass the raw `Error` to `LogHandler`. The end result was similar to the currently proposed default implementation in `LogHandler`. In this solution, the metadata keys (`"error.message"` and `"error.type"`) were considered stable and part of the API, since that allowed for `LogHandler` implementations to re-map the keys (e.g. to `"err.*"`).
Ultimately, this was declined in favor of the current proposal. While the metadata based solution was simple, it lacked the flexibility that passing the raw `Error` allows for.
#### recordError convenience method
In the first iteration, we considered adding a new convenience method `recordError` on `Logger`, that would take an `Error`, serialize it, and add to the metadata on the `Logger`. This would primarily have been useful for when a `Logger` instance were passed down a call hierarchy and the `Error` metadata were relevant further down. However, it doesn't work well with the current proposal, since the serialization happens at a later stage.
#### Using .stringConvertible to pass Error to LogHandler
An alternative way to let the `LogHandler` get access to the raw `Error` would be to use the existing `.stringConvertible` enum case of `MetadataValue`. By putting the `Error` under a well-known metadata key (such as `"error"`), a `LogHandler` could get access to it, without any changes to the `LogHandler` protocol. However, this would only work for `Error`s that conform to `CustomStringConvertible`.
#### some Error vs any Error
The error argument in `Logger` was considered to be `some Error` rather than `any Error`. Ultimately, `any Error` was preferred. This is because in most typical use cases (e.g. general catch blocks), the error is an existential, so by using `some Error` we would get a slight performance penalty.
@@ -0,0 +1,512 @@
# SLG-0004: Metadata value attributes
Add an extensible per-value attribute mechanism for metadata.
## Overview
- Proposal: SLG-0004
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
- Status: **Approved**
- Issue: [apple/swift-log#204](https://github.com/apple/swift-log/issues/204)
- Implementation:
- [apple/swift-log#453](https://github.com/apple/swift-log/pull/453)
- Related links:
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
- [First iteration of the proposal](https://forums.swift.org/t/proposal-slg-0004-metadata-values-privacy-attribute/85249)
### Introduction
Introduce an extensible mechanism for attaching per-value attributes to metadata. The core `Logging` module provides
the protocol and storage. Attribute packages define concrete attributes using the
`Logger.MetadataValueAttributes.Attribute` protocol.
### Motivation
Metadata values in `swift-log` are opaque strings by the time the `LogHandler` receives them. The call site often
knows things about a value that the handler cannot infer — for example, whether the value should be redacted in
different environments.
Today, there is no way to express this. A single log statement can contain values that need different treatment, and
log levels cannot help because they are per-statement, not per-value:
```swift
logger.info("Login", metadata: [
"action": "\(action)", // safe to log
"user_email": "\(email)", // should be redacted in production, but nothing tells the handler
])
```
The workaround is handler-side key-based rules (`redact: ["email", "card-*", ...]`), but this is fragile:
- Rules break when libraries rename keys.
- Rules require coordination across all dependencies.
- The rule mapping is invisible at the call site.
### Proposed solution
Attributes are embedded directly in `MetadataValue` via the existing `.stringConvertible` case. A custom
`MetadataValue.StringInterpolation` type produces attributed values when any interpolation segment specifies
attributes. Libraries define attribute types conforming to `Logger.MetadataValueAttributes.Attribute` and provide
ergonomic string interpolation overloads. Handlers read the attributes via `value.attributes` and act on them:
```swift
import Logging
public enum Sensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case sensitive = 1
case `public` = 2
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, sensitivity: Sensitivity
) {
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
}
}
logger.info("Request", metadata: [
"method": "\(req.method)",
"user_id": "\(req.userId, sensitivity: .sensitive)",
])
```
Handlers that support specific attributes read them from `value.attributes` and act accordingly. Handlers that do not
understand attributes see plain `MetadataValue` instances — attributes are invisible unless explicitly inspected. The
existing `metadata:` parameter is the only parameter needed; no new log method overloads are added.
Attributed values can also be created programmatically with the `.attributed` factory, which behaves like an additional
enum case without breaking existing exhaustive switches:
```swift
let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
```
Intermediate handlers can read **and modify** attributes as metadata flows through a handler chain. The `attributes`
property supports both getting and setting, enabling composable pipelines where each handler in the chain can enrich,
transform, or strip attributes before forwarding:
```swift
// An enriching handler that tags all metadata with a processing timestamp attribute
func log(event: LogEvent) {
var mutatedEvent = event
if var eventMetadata = event.metadata {
for (key, _) in eventMetadata {
var attrs = eventMetadata[key]!.attributes
attrs[ProcessingStage.self] = .enriched
eventMetadata[key]?.attributes = attrs
}
mutatedEvent.metadata = eventMetadata
}
self.inner.log(event: mutatedEvent)
}
```
Attributes are **classifications, not enforcement**. An attribute does not guarantee any particular handler behavior —
the handler may not support it. Applications needing guaranteed behavior must enforce it at a different abstraction.
The attribute mechanism is extensible: packages define their own attribute types using
`Logger.MetadataValueAttributes.Attribute`. A
chained `LogHandler` can read the attributes it cares about, act on them, and forward the rest to the next handler in
the chain — enabling composable handler pipelines (e.g., redaction handler -> metrics-extraction handler -> output
handler). Common attributes should be defined in separate packages so that the core `Logging` module remains free of
domain-specific attributes while providing shared vocabulary across libraries. To improve discoverability, `swift-log`
can reference attribute packages that are common across the whole ecosystem.
### Detailed design
#### `Attribute` protocol
```swift
extension Logger.MetadataValueAttributes {
/// A protocol for defining custom metadata attributes.
///
/// Conform to this protocol to define a custom attribute that can be stored in
/// ``MetadataValueAttributes``. Each conforming type acts as both the key (identified
/// by its metatype) and the value.
///
/// This protocol is designed for **small, fixed-vocabulary attributes**.
/// Each attribute value is stored as an `Int64` raw value, so attributes occupy minimal
/// space (one inline slot without heap allocation for the common single-attribute case).
///
/// ## Examples
///
/// ```swift
/// public enum Priority: Int64, Sendable, Logger.MetadataValueAttributes.Attribute {
/// case low = 1
/// case high = 2
/// }
/// ```
///
/// ```swift
/// public struct Priority: Sendable, Hashable, Logger.MetadataValueAttributes.Attribute {
/// public let rawValue: Int64
/// public init(rawValue: Int64) {
/// self.rawValue = rawValue
/// }
/// public static let low = Priority(rawValue: 1)
/// public static let high = Priority(rawValue: 2)
/// }
/// ```
public protocol Attribute: Sendable,
RawRepresentable where RawValue == Int64 {}
}
```
Each conforming type serves as both the key and the value for an attribute. The metatype (`Key.Type`) identifies
the attribute at runtime — no coordination between packages is needed.
#### `MetadataValueAttributes`
```swift
extension Logger {
/// Attributes that can be associated with metadata values.
public struct MetadataValueAttributes: Sendable, Equatable, ExpressibleByArrayLiteral {
/// Nested ``Attribute`` protocol (see above).
public protocol Attribute: Sendable, RawRepresentable where RawValue == Int64 {}
/// Create empty metadata value attributes.
public init()
/// Create metadata value attributes from an array literal of attribute values.
///
/// ```swift
/// let attrs: MetadataValueAttributes = [Sensitivity.sensitive, ValueType.int64]
/// ```
public init(arrayLiteral elements: any Attribute...)
/// Get or set a custom attribute by its type.
///
/// - Parameter attribute: The metatype of the attribute to access.
/// - Returns: The attribute value, or `nil` if not set.
public subscript<Attr: Attribute>(attribute: Attr.Type) -> Attr? { get set }
}
}
```
The common case (0–1 attributes) avoids heap allocation. `Equatable` compares entries as an unordered set (O(n²),
n typically 0–2).
#### `MetadataValue.attributes` computed property
```swift
extension Logger.MetadataValue {
/// The attributes associated with this metadata value, if any.
///
/// **Getting:** When the value is a ``stringConvertible(_:)`` wrapping an attributed carrier,
/// returns that carrier's attributes. For all other cases returns empty attributes.
///
/// **Setting:** Replaces the value with `.stringConvertible(AttributedStringCarrier(...))`
/// carrying the given attributes. For `.string` and `.stringConvertible` cases the string
/// representation is preserved. For `.dictionary` and `.array` cases the setter is a no-op.
public var attributes: Logger.MetadataValueAttributes { get set }
}
```
This is the handler-side read/write API. Internally, the `Logging` module stores attributes in an internal
`AttributedStringCarrier` class wrapped by `.stringConvertible`. The getter check is a concrete type comparison — no
protocol conformance lookup. Users attach attributes via string interpolation and read them via this property. The
setter allows handlers to modify or add attributes as they process metadata values through the handler chain.
#### `MetadataValue.attributed` factory method
```swift
extension Logger.MetadataValue {
/// Creates an attributed metadata value from a string-convertible value and attributes.
public static func attributed(
_ value: some CustomStringConvertible & Sendable,
attributes: Logger.MetadataValueAttributes
) -> Self
}
```
This convenience factory behaves like an additional enum case, producing a
`.stringConvertible(AttributedStringCarrier(...))` value without requiring string interpolation:
```swift
let value: Logger.MetadataValue = .attributed(userId, attributes: [Sensitivity.sensitive])
```
#### String interpolation
`MetadataValue` replaces its empty `ExpressibleByStringInterpolation` conformance with a custom `StringInterpolation`
type. When no attributes are specified, the result is `.string(...)` — identical to the previous behavior. When any
interpolation segment specifies attributes, the result is `.stringConvertible(...)` wrapping the internal carrier:
```swift
extension Logger.MetadataValue: ExpressibleByStringInterpolation {
/// Custom string interpolation that optionally captures metadata attributes.
///
/// When no attributes are specified, produces `.string(...)` — identical to the
/// default `DefaultStringInterpolation` behavior. When any interpolation segment
/// specifies attributes (via the `attributes:` parameter), the result is
/// `.stringConvertible(AttributedStringCarrier(...))` carrying both the string
/// and the accumulated attributes.
///
/// Attribute packages (like `LoggingAttributes`) can add overloads with
/// domain-specific parameters (e.g. `sensitivity:`) that call through to
/// `appendInterpolation(_:attributes:)`.
public struct StringInterpolation: StringInterpolationProtocol, Sendable {
public init(literalCapacity: Int, interpolationCount: Int)
public mutating func appendLiteral(_ literal: String)
/// Interpolation with a custom attributes closure.
///
/// When called, the result will be `.stringConvertible(AttributedStringCarrier(...))`
/// instead of `.string(...)`.
///
/// ```swift
/// "\(userId, attributes: { $0[MyAttribute.self] = .flagged })"
/// ```
public mutating func appendInterpolation<T>(
_ value: T,
attributes: @Sendable (inout Logger.MetadataValueAttributes) -> Void
) where T: CustomStringConvertible & Sendable
/// Plain interpolation without attributes.
public mutating func appendInterpolation<T>(
_ value: T
) where T: CustomStringConvertible & Sendable
/// Fallback interpolation for types that are not `CustomStringConvertible`.
public mutating func appendInterpolation<T>(
_ value: T
) where T: Sendable
/// Unconstrained fallback for non-`Sendable` types.
///
/// The value is immediately converted to `String` via `String(describing:)` and never
/// stored, so no `Sendable` safety issue arises. This overload exists so that interpolating
/// a non-`Sendable` type into a `MetadataValue` continues to compile, matching the behavior
/// of `DefaultStringInterpolation`.
public mutating func appendInterpolation<T>(
_ value: T
)
}
/// Creates a metadata value from string interpolation.
///
/// If any interpolation segment specified attributes, the result is
/// `.stringConvertible(AttributedStringCarrier(...))`. Otherwise, `.string(...)`.
public init(stringInterpolation: StringInterpolation)
}
```
Attribute packages add ergonomic overloads that wrap the closure-based method — for example:
```swift
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, sensitivity: Sensitivity
) {
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
}
}
```
This enables the clean call-site syntax: `"\(userId, sensitivity: .sensitive)"`.
When a single `MetadataValue` contains multiple interpolated segments with different attributes, the merging behavior
is defined by each attribute's `appendInterpolation` implementation.
#### No changes to `Logger`, `LogHandler`, `LogEvent`, or `MetadataProvider`
Unlike earlier iterations of this proposal, the piggyback approach requires **no new API** on `Logger`, `LogHandler`,
`LogEvent`, or `MetadataProvider`:
- **`Logger`**: No new `attributedMetadata:` log method overloads. Attributes flow through the existing `metadata:`
parameter.
- **`LogHandler`**: No new protocol requirements. No `attributedMetadata` property, no `attributedMetadataKey`
subscript. Existing handlers work unchanged.
- **`LogEvent`**: No dual storage. `metadata` remains a simple `Logger.Metadata?` stored property. Values inside the
dictionary may carry attributes, but `LogEvent` is unaware of this.
- **`MetadataProvider`**: No `.attributed()` factory or `getAttributedMetadata()` method. Providers return
`Logger.Metadata` where values may carry attributes via string interpolation.
### API stability
- **Existing `Logger` users.** No changes to existing API. The same `metadata:` parameter carries attributed values.
- **Existing `LogHandler` implementations.** No protocol changes. Handlers that only call `.description` on metadata
values see the string as before — attributes are invisible. Handlers that want to inspect attributes read
`value.attributes`.
### Future directions
- **Attribute-aware equality.** The current `MetadataValue` equality for `.stringConvertible` values compares only
`.description`, ignoring attributes. Two values with the same text but different attributes compare as equal. A
future proposal could refine equality to include attributes when both sides carry them, but this
requires careful consideration of backward compatibility since existing code may rely on description-only equality.
- **Metadata values sensitivity attribute.** A separate ecosystem package could add the sensitivity attribute,
allowing compatible `LogHandler` to redact values in certain situations.
- **Typed metadata values.** A separate ecosystem package could add typed variants to `MetadataValue` (`.int64`,
`.double`, `.bool`), reducing the need for attributes that compensate for stringly-typed metadata.
### Alternatives considered
#### Wrapper type with parallel API ("attributed metadata value" approach)
Introduce an `AttributedMetadataValue` struct wrapping `MetadataValue` + `MetadataValueAttributes`, a separate
`AttributedMetadata` typealias, new `attributedMetadata:` overloads on all Logger methods, dual storage in
`LogEvent`, and new `LogHandler` protocol requirements. This was the design in the first iteration of this proposal.
It provides strong type separation but creates a parallel API surface: 7 new convenience methods, new protocol
requirements with default implementations, dual `MetadataStorage` enum in `LogEvent`, and `mapValues` bridging
between plain and attributed representations. The piggyback approach achieves the same functionality by embedding
attributes inside `MetadataValue` via the existing `.stringConvertible` case, avoiding the parallel universe
entirely.
#### Sidecar dictionary on `LogEvent`
Store attributes in a separate `[String: MetadataValueAttributes]` dictionary on `LogEvent`, keyed by the same
metadata keys. This keeps `MetadataValue` unchanged but introduces sync issues — attributes can drift out of sync
with metadata keys when handlers merge or transform metadata. The piggyback approach avoids this by co-locating
attributes with the value they describe.
#### New enum case on `MetadataValue`
Add a dedicated `.attributed(String, MetadataValueAttributes)` case to the `MetadataValue` enum. This would make
attributes statically visible in the type — no runtime downcast needed, and `switch` statements would handle
attributed values explicitly. However, `MetadataValue` is a public enum that is exhaustively matched by every
`LogHandler` in the ecosystem. Adding a case is source-breaking: every existing handler's `switch` over
`MetadataValue` would fail to compile until updated. The piggyback approach avoids this by reusing the existing
`.stringConvertible` case, which handlers already handle.
#### Concrete stored property instead of extensible mechanism
Add concrete stored properties (e.g., `var sensitivity: Sensitivity?`) on `MetadataValueAttributes`. Simpler, but
closed — chained handlers cannot define their own attributes. The extensible mechanism keeps the core `Logging` module
free of domain-specific attributes.
#### Bitmask storage
Pack attribute values into an inline `UInt64` using declared bit offsets. O(1) access, but requires authors to
coordinate bit layout and risks collisions between independent packages.
#### Pure dynamic array storage
Use a dynamic array for all attributes with no inline slot. Simpler, but requires heap allocation even for the first
attribute.
#### No per-value attributes
Rely on handler-side configuration (key-name-based rules). Simpler, but fragile — rules break when keys are renamed,
require coordination across all dependencies, and are invisible at the call site.
### Example attributes
The following examples illustrate how ecosystem packages could define attributes using the
`Logger.MetadataValueAttributes.Attribute` protocol. These are not part of this proposal.
#### Sensitivity
A sensitivity attribute for marking metadata values that contain private or personally identifiable information:
```swift
public enum Sensitivity: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case sensitive = 1
case `public` = 2
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, sensitivity: Sensitivity
) {
self.appendInterpolation(value, attributes: { $0[Sensitivity.self] = sensitivity })
}
}
logger.info("Request", metadata: [
"method": "\(req.method)",
"user_id": "\(req.userId, sensitivity: .sensitive)",
])
```
A handler reads the attribute:
```swift
for (key, value) in mergedMetadata {
if value.attributes[Sensitivity.self] == .sensitive {
// redact this value
}
}
```
#### Value type hint
A type hint for structured logging backends that benefit from native types:
```swift
public enum ValueType: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case string = 1
case int64 = 2
case double = 3
case bool = 4
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, valueType: ValueType
) {
self.appendInterpolation(value, attributes: { $0[ValueType.self] = valueType })
}
}
logger.info("Metrics", metadata: [
"latency_ms": "\(latency, valueType: .double)",
"retry_count": "\(retries, valueType: .int64)",
])
```
#### Metric extraction
A metric attribute for a chained `LogHandler` that dual-writes to swift-metrics:
```swift
public enum MetricKind: Int64, Logger.MetadataValueAttributes.Attribute, Sendable {
case counter = 1
case gauge = 2
case histogram = 3
}
extension Logger.MetadataValue.StringInterpolation {
public mutating func appendInterpolation<T: CustomStringConvertible & Sendable>(
_ value: T, metricKind: MetricKind
) {
self.appendInterpolation(value, attributes: { $0[MetricKind.self] = metricKind })
}
}
logger.info("Request completed", metadata: [
"duration_ms": "\(duration, metricKind: .histogram)",
"error_count": "\(errors, metricKind: .counter)",
])
```
#### Attribute-enriching intermediate handler
An intermediate `LogHandler` that reads and modifies attributes before forwarding to the next handler in the chain.
This pattern enables composable pipelines — for example, a handler that adds a default sensitivity to all metadata
values that do not already carry one:
```swift
struct DefaultSensitivityHandler: LogHandler {
private var inner: any LogHandler
// ... logLevel, metadata, metadataProvider forwarded to inner ...
func log(event: LogEvent) {
var mutatedEvent = event
if var eventMetadata = event.metadata {
for (key, _) in eventMetadata {
if eventMetadata[key]?.attributes[Sensitivity.self] == nil {
eventMetadata[key]?.attributes = [Sensitivity.sensitive]
}
}
mutatedEvent.metadata = eventMetadata
}
self.inner.log(event: mutatedEvent)
}
}
```
With this handler in the chain, any metadata value without an explicit sensitivity annotation is treated as sensitive
by default — a "deny by default" policy that individual call sites can override with `.public`.
@@ -0,0 +1,180 @@
# SLG-0005: `LogEvent`-based `LogHandler` API
Replace the flat-parameter `log(level:message:metadata:source:file:function:line:)` method on `LogHandler` with
`log(event: LogEvent)`, enabling forward-compatible evolution of the `LogHandler` interface without breaking existing
handler implementations.
## Overview
- Proposal: SLG-0005
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
- Status: **Approved**
- Issue: [apple/swift-log#421](https://github.com/apple/swift-log/issues/421)
- Implementation:
- [apple/swift-log#423](https://github.com/apple/swift-log/pull/423)
- Related links:
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
- [SLG-0003: Standardized Error Metadata via Logger Convenience](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/SLG-0003.md)
### Introduction
Introduce `LogEvent` that bundles all log-statement data, and replace the flat-parameter
`log(level:message:metadata:source:file:function:line:)` method on `LogHandler` with `log(event: LogEvent)`.
### Motivation
The `LogHandler` protocol currently requires implementing a single method with seven parameters:
```swift
func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
)
```
Every time a new piece of data needs to be forwarded from a log call site to the handler — an error, or a richer metadata type — the only options are:
- **Add a new parameter to the existing method.** This is a source-breaking change: every existing `LogHandler`
implementation across the entire Swift ecosystem must be updated simultaneously.
- **Add a new `Logger` overload.** This requires 2 parallel APIs to coexist until the old one can be safely deprecated.
### Proposed solution
Introduce `LogEvent`, a `struct` that carries all the data associated with a single log statement. `LogEvent` is
a handler-side type: it is constructed by `Logger._log` and passed to `LogHandler`. The public `Logger` call-site
API — `logger.info(...)`, `logger.log(level:...)` and so on — is unchanged.
The `LogHandler` protocol gains a new required method `log(event: LogEvent)`, while the old flat-parameter method
is deprecated.
For existing handlers, a default implementation of `log(event:)` forwards to the old method, so no code changes
are required to keep existing implementations working. Handlers that want to take advantage of new fields added to
`LogEvent` in future proposals implement `log(event:)`.
### Detailed design
#### New `LogEvent` type
A new top-level `struct` in the `Logging` module:
```swift
public struct LogEvent: Sendable {
public var level: Logger.Level
public var message: Logger.Message
private var _metadata: Logger.Metadata?
public var metadata: Logger.Metadata? {
get { self._metadata }
set { self._metadata = newValue }
}
public var source: String
public var file: String
public var function: String
public var line: UInt
public init(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
)
}
```
#### Updated `LogHandler` protocol
```swift
public protocol LogHandler: _SwiftLogSendableLogHandler {
/// The library calls this method when a log handler must emit a log message.
///
/// There is no need for the `LogHandler` to check if the level is above or below the configured `logLevel`
/// as `Logger` already performed this check and determined that a message should be logged.
///
/// - Parameter event: The log event containing the level, message, metadata, and source location.
func log(event: LogEvent)
/// Please do _not_ implement this method when you create a `LogHandler` implementation.
/// Implement ``log(event:)`` instead.
///
/// - Parameters:
/// - level: The log level of the message.
/// - message: The message to log. To obtain a `String` representation call `message.description`.
/// - metadata: The metadata associated to this log message.
/// - source: The source where the log message originated, for example the logging module.
/// - file: The file this log message originates from.
/// - function: The function this log message originates from.
/// - line: The line this log message originates from.
@available(*, deprecated, renamed: "log(event:)")
func log(
level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt
)
}
```
#### Default implementation
The default for `log(event:)` forwards all event fields to the old flat-parameter method,
preserving the behavior of existing handlers with no source changes required.
The default implementation is marked as deprecated to encourage handler authors to migrate to `log(event:)`.
Handlers that still rely on the forwarding bridge will see a deprecation warning at compile time, signaling that
they should adopt the new method directly.
```swift
extension LogHandler {
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
public func log(event: LogEvent) {
self.log(
level: event.level,
message: event.message,
metadata: event.metadata,
source: event.source,
file: event.file,
function: event.function,
line: event.line
)
}
}
```
### API stability
**For existing `Logger` users:** No changes. All existing call sites continue to compile and behave identically.
**For existing `LogHandler` implementations:** Implementations of
`log(level:message:metadata:source:file:function:line:)` continue to work without any source changes. The
default implementation of `log(event:)` forwards to the old method.
### Future directions
Future proposals can add new fields to `LogEvent` with sensible defaults — a richer metadata
type, or an attached `Error` (as a follow-up for [SLG-0003 proposal](https://forums.swift.org/t/proposal-slg-0003-standardized-error-metadata-via-logger-convenience/84518/39)) —
without touching the `LogHandler` protocol and without requiring any changes to
existing handler implementations. This is the primary motivation for this proposal.
The [SLG-0004 proposal](https://github.com/apple/swift-log/pull/416) introduces an `AttributedMetadata` type that wraps
`Logger.Metadata` with additional context. Adding it to `LogEvent` as a new optional field would be
source-compatible, and the existing `metadata` field could become a computed property that projects from
`attributedMetadata` when present, keeping old handlers fully functional without modification.
### Alternatives considered
#### Adding parameters with default values to the existing method
Adding new parameters with default values avoids introducing a new method, but still constitutes a
source-breaking change: every existing `LogHandler` implementation that implements the method explicitly
must add the new parameter. The whole point of this proposal is to avoid that pattern indefinitely.
@@ -0,0 +1,439 @@
# SLG-0006: Task-local logger with automatic metadata propagation
Accumulate structured logging metadata across async call stacks using task-local storage.
## Overview
- Proposal: SLG-0006
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
- Status: **Approved**
- Issue: [apple/swift-log#261](https://github.com/apple/swift-log/issues/261)
- Implementation: [apple/swift-log#459](https://github.com/apple/swift-log/pull/459)
- Feature flag: none
- Related links:
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
### Introduction
This proposal adds task-local logger storage so that metadata can accumulate across async
call stacks without threading a `Logger` through every function signature.
### Motivation
Metadata propagation requires threading a logger through every layer. Every function on
the path from request ingress to the bottom of the call stack has to accept, mutate, and
forward a `Logger`:
```swift
func handleHTTPRequest(_ request: HTTPRequest, logger: Logger) async throws {
var logger = logger
logger[metadataKey: "request.id"] = "\(request.id)"
try await processBusinessLogic(request, logger: logger)
}
```
Libraries must choose between polluting their public API with a `logger:` parameter and
losing all the caller's context. There is no third option today.
### Proposed solution
Use Swift's `@TaskLocal` to propagate a logger with accumulated metadata. The caller sets up
a scope, callees read `Logger.current`:
```swift
func handleRequest(_ request: HTTPRequest) async throws -> HTTPResponse {
try await withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
logger.info("Handling request") // Has request.id automatically
return try await processRequest(request) // no logger parameter needed
}
}
func processRequest(_ request: HTTPRequest) async throws -> User {
Logger.current.debug("Processing...") // Has request.id automatically
DatabaseClient.query(request.sqlQuery)
}
```
Libraries keep their APIs clean while still emitting logs with the caller's full context.
A library reads `Logger.current` directly — the caller's accumulated metadata flows in
automatically without a `logger:` parameter:
```swift
public struct DatabaseClient {
public static func query(_ sql: String) async throws -> [Row] {
Logger.current.debug("Executing", metadata: ["sql": "\(sql)"])
return try await performQuery(sql)
}
}
```
**Wiring it up with swift-service-lifecycle.** At the application entry point, bind the
bootstrapped logger once; service lifecycle propagates the task-local through the
`ServiceGroup` and into every task spawned from its `run()`:
```swift
@main
struct MyServer {
static func main() async throws {
let logger = Logger(label: "my-server")
try await withLogger(logger) { _ in
let serviceGroup = ServiceGroup(
configuration: .init(
services: [HTTPServer(), BackgroundWorker()],
gracefulShutdownSignals: [.sigint],
cancellationSignals: [.sigterm],
logger: logger
)
)
try await serviceGroup.run()
}
}
}
```
Metadata accumulates through nesting and task-local values propagate through structured
concurrency (`async let`, `withTaskGroup`, child `Task {}`). `Task.detached` does not
inherit context — capture the logger explicitly if needed.
### Detailed design
#### `Logger.current`
Returns the logger bound by the nearest enclosing `withLogger` scope. If none is active,
returns the process-wide unbound default: a `Logger(label: "")` constructed via
`LoggingSystem.factory` the first time the task-local is touched.
```swift
extension Logger {
/// The current task-local logger.
///
/// Returns the logger bound by the nearest enclosing ``withLogger(_:_:)`` scope.
/// If none is active, returns the process-wide unbound default: a
/// `Logger(label: "")` cached from the first time the task-local is touched.
///
/// Task-local values propagate through structured concurrency (`async let`,
/// `withTaskGroup`, child `Task {}`) but are **not** inherited by `Task.detached`.
/// Capture the logger explicitly across detached boundaries.
///
/// For many log calls in a tight scope, prefer extracting the logger once —
/// either `let logger = Logger.current` or the closure's `logger` parameter
/// from `withLogger { logger in ... }` — instead of re-reading the task-local
/// on every call.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public static var current: Logger { get }
}
```
The per-symbol `@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)` mirrors
`@TaskLocal`'s own runtime availability.
#### `withLogger` free functions
Three overload groups, each with sync and async variants. The closure receives the logger
as a parameter to avoid repeated task-local lookups inside the closure body.
**Bind a specific logger:**
```swift
/// Runs `operation` with `logger` bound to the task-local context.
///
/// Code called within `operation` can read the logger via ``Logger/current`` without an
/// explicit parameter. Binding a different logger with this overload **replaces** the
/// current task-local logger; any metadata accumulated by an outer
/// ``withLogger(mergingMetadata:_:)`` or
/// ``withLogger(logLevel:handler:metadata:_:)`` scope is not carried over.
///
/// This overload is the application-bootstrap binding mechanism: pass a `Logger`
/// constructed via ``Logger/init(label:)`` at your application entry point. Because
/// ``Logger/init(label:)`` consults ``LoggingSystem/factory``, the constructed `Logger`
/// only carries a useful handler once ``LoggingSystem/bootstrap(_:)`` has been called.
/// For mid-call-tree backend swaps that should work without bootstrap (tests, scoped
/// routing), use ``withLogger(logLevel:handler:metadata:_:)`` instead — it modifies the
/// current logger's handler in place without constructing a new one.
///
/// let logger = Logger(label: "app")
/// await withLogger(logger) { logger in
/// logger.info("Application started")
/// await handleRequests() // reads Logger.current
/// }
///
/// - Parameters:
/// - logger: The logger to bind for the duration of `operation`.
/// - operation: The closure to run with `logger` bound. Receives `logger` as a
/// parameter so the body does not need to re-read ``Logger/current``.
/// - Returns: The value returned by `operation`.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@inlinable
public func withLogger<Result, Failure: Error>(
_ logger: Logger,
_ operation: (Logger) throws(Failure) -> Result
) throws(Failure) -> Result
/// Runs `operation` with `logger` bound to the task-local context. Async variant of
/// ``withLogger(_:_:)``; see that function for full semantics.
///
/// - Parameters:
/// - logger: The logger to bind for the duration of `operation`.
/// - operation: The async closure to run with `logger` bound. Receives `logger` as
/// a parameter so the body does not need to re-read ``Logger/current``.
/// - Returns: The value returned by `operation`.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@inlinable
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
_ logger: Logger,
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
) async throws(Failure) -> Result
```
**Append metadata for a scope:**
```swift
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` **layered on
/// top of** the inherited base metadata. Keys present in `metadata` override existing
/// keys with the same name; other inherited metadata is preserved. Handler and log
/// level are unchanged.
///
/// Use this overload at request boundaries and any point where context should
/// accumulate. Nested ``withLogger(mergingMetadata:_:)`` scopes layer on top of each
/// other.
///
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { logger in
/// logger.info("Handling request")
/// withLogger(mergingMetadata: ["user.id": "\(user.id)"]) { logger in
/// logger.info("Authenticated") // sees both request.id and user.id
/// }
/// }
///
/// - Parameters:
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
/// Keys override existing values with the same name.
/// - operation: The closure to run with the merged logger bound. Receives the
/// merged logger as a parameter.
/// - Returns: The value returned by `operation`.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@inlinable
public func withLogger<Result, Failure: Error>(
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
_ operation: (Logger) throws(Failure) -> Result
) throws(Failure) -> Result
/// Runs `operation` with a copy of ``Logger/current`` that has `metadata` layered on
/// top of the inherited base metadata. Async variant of ``withLogger(mergingMetadata:_:)``;
/// see that function for full semantics.
///
/// - Parameters:
/// - metadata: Metadata keys merged onto the inherited base metadata for the scope.
/// Keys override existing values with the same name.
/// - operation: The async closure to run with the merged logger bound. Receives the
/// merged logger as a parameter.
/// - Returns: The value returned by `operation`.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@inlinable
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
mergingMetadata metadata: @autoclosure () -> Logger.Metadata,
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
) async throws(Failure) -> Result
```
**Replace aspects of the current logger:**
```swift
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are **replaced** by
/// the provided arguments. `nil` parameters leave the corresponding aspect unchanged.
///
/// Unlike ``withLogger(mergingMetadata:_:)``, which layers metadata on top of the
/// inherited base, this overload **replaces** the base metadata when `metadata` is
/// non-nil. Pass `metadata: [:]` to wipe the inherited metadata entirely.
///
/// With no arguments, this overload re-binds ``Logger/current`` unchanged — a convenient
/// way to extract it into a local variable for repeated use inside the closure.
///
/// withLogger(mergingMetadata: ["request.id": "\(request.id)"]) { _ in
/// // Background job: start a scope with metadata unrelated to the request.
/// withLogger(metadata: ["job.id": "\(job.id)"]) { logger in
/// logger.info("running") // metadata: job.id only — request.id wiped
/// }
/// }
///
/// - Parameters:
/// - logLevel: When non-nil, replaces the current log level for the scope. When
/// `nil`, the inherited log level is preserved.
/// - handler: When non-nil, replaces the current logger's handler for the scope.
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for
/// the scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to
/// start a scope from a known state. When `nil`, the inherited base metadata is
/// preserved.
/// - operation: The closure to run with the modified logger bound. Receives the
/// modified logger as a parameter.
/// - Returns: The value returned by `operation`.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@inlinable
public func withLogger<Result, Failure: Error>(
logLevel: Logger.Level? = nil,
handler: (any LogHandler)? = nil,
metadata: @autoclosure () -> Logger.Metadata? = nil,
_ operation: (Logger) throws(Failure) -> Result
) throws(Failure) -> Result
/// Runs `operation` with a copy of ``Logger/current`` whose aspects are replaced by
/// the provided arguments. Async variant of
/// ``withLogger(logLevel:handler:metadata:_:)``; see that function for full semantics.
///
/// - Parameters:
/// - logLevel: When non-nil, replaces the current log level for the scope. When
/// `nil`, the inherited log level is preserved.
/// - handler: When non-nil, replaces the current logger's handler for the scope.
/// Useful in tests to route logs through an `InMemoryLogHandler` or similar while
/// keeping the caller's label. When `nil`, the inherited handler is preserved.
/// - metadata: When non-nil, replaces the handler's base metadata dictionary for
/// the scope. Pass `[:]` to erase inherited metadata; pass a fresh dictionary to
/// start a scope from a known state. When `nil`, the inherited base metadata is
/// preserved.
/// - operation: The async closure to run with the modified logger bound. Receives
/// the modified logger as a parameter.
/// - Returns: The value returned by `operation`.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@inlinable
public nonisolated(nonsending) func withLogger<Result, Failure: Error>(
logLevel: Logger.Level? = nil,
handler: (any LogHandler)? = nil,
metadata: @autoclosure () -> Logger.Metadata? = nil,
_ operation: nonisolated(nonsending) (Logger) async throws(Failure) -> Result
) async throws(Failure) -> Result
```
Calling `withLogger { logger in ... }` with no arguments is the single-lookup idiom for
extracting `Logger.current` into a local variable for repeated use inside the closure —
analogous to `withSpan { span in ... }` in `swift-distributed-tracing`.
#### Relationship to `MetadataProvider`
Metadata merged via `withLogger(mergingMetadata:)` is written into the handler's base
metadata on the per-task logger copy. If a handler has a `MetadataProvider` attached — for
example a bootstrapped OpenTelemetry provider that reads `trace.id` from `ServiceContext` —
the provider still runs at log-emission time and follows the handler's conventional merge
order (base < provider < per-statement).
This proposal does **not** add a `metadataProvider:` parameter to the modifying overload.
Application code that wants to swap the provider for a scope should construct a new `Logger`
and use the binding overload. Keeping the two concerns separate avoids shipping the
replace-vs-compose question as part of the core API.
### API stability
**For existing `Logger` users:** no changes. The new API is purely additive.
**For existing `LogHandler` implementations:** no changes required. Task-local loggers use
the same `LogHandler` interface; no new protocol requirements are added.
**Package platform minimums.** `Package.swift` intentionally does not gain a `platforms:`
clause. Each new symbol carries `@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)`
to match `@TaskLocal`'s runtime availability. Callers targeting older deployment versions
keep working; they just can't call the task-local API.
**ABI and resilience.** The `withLogger` overloads are `@inlinable`: their bodies are thin
glue — read `Logger.current`, copy-and-modify the logger, then bind it for the scope — so
inlining them removes a cross-module call at each scope entry. The internal
`withTaskLocalLogger` bridge over `TaskLocal.withValue` is `@usableFromInline` (not
`@inlinable`), letting the inlinable bodies reach it without exposing the `@TaskLocal`
storage. That storage, the bridge, and `Logger.current` all stay non-`@inlinable`, so the
genuinely evolvable state — how the task-local is stored and how the unbound default is
resolved — remains behind a resilient boundary and can change without breaking
already-compiled clients. Only the small, settled control flow of the wrappers is committed
to ABI.
**Source compatibility caveat.** The name `withLogger` is added at the top-level namespace.
Codebases that previously defined their own free `withLogger` function may need to
fully-qualify calls (`Logging.withLogger(...)`) or rename their own.
### Future directions
- **`Logger.withMetadata(merging:) -> Logger` and `Logger.withMetadata(replacing:) -> Logger`
value-level instance methods.** Construct a derived `Logger` value (not a scope) with
metadata layered onto or wholly replacing the receiver's metadata. The scope-level
equivalents (`withLogger(mergingMetadata:)` and `withLogger(metadata:)`) ship in this
proposal; the value-level forms are useful for per-statement metadata that should not
propagate via the task-local — for example, a library that wants to stamp a key on its
own log lines without pushing it onto `Logger.current` (avoiding leakage into downstream
callees).
### Alternatives considered
#### Task-local metadata dictionary instead of task-local logger
Make only the metadata dictionary task-local, so ad-hoc `Logger(label:)` calls automatically
merge it. Rejected because it changes default behavior for all existing logger creation
(breaking semantic change) and overlaps with `swift-distributed-tracing`'s
`ServiceContext`.
#### Static methods on `Logger` instead of free functions
`Logger.withCurrent(...)` instead of `withLogger(...)`. Rejected — inconsistent with
`withSpan(...)` from `swift-distributed-tracing` and `withMetricsFactory(...)` from
`swift-metrics`. Free functions follow the established ecosystem convention.
#### Use `ServiceContext` from swift-distributed-tracing instead of a new task-local
Store metadata in the existing `ServiceContext` — propagated by `swift-service-context`,
the leaf package already designed as a shared propagation primitive — rather than
introducing a second `@TaskLocal`. Rejected because the two propagation channels serve
different use cases: `ServiceContext` carries *distributed* correlation (trace/span IDs,
baggage) that flows across process boundaries, while `withLogger(mergingMetadata:)`
accumulates *local* per-scope logger configuration (log level, handler, and application
metadata like `request.id`) that is meaningful only within a single process. The
task-local logger also carries more than metadata — it holds the `LogHandler`, log
level, and label, none of which belong in a context intended for cross-process propagation.
The existing `MetadataProvider` already bridges the two systems at log-emission time:
handlers read trace/span IDs from `ServiceContext` without swift-log depending on it.
#### No closure parameter — require `Logger.current` inside the closure
`withLogger(logger) { ... }` without a parameter, reading `Logger.current` inside. Rejected
because passing the logger avoids repeated task-local lookups, follows the `withSpan`
convention, and makes it obvious at the call site which logger is in use.
#### Not propagating metadata across module boundaries by default
Expose a public `TaskLocal<Logger>` extension surface so that each module can declare
its own scoped logger and stay structurally isolated from other modules — pushes on one
module's task-local would be invisible to another's reads. Rejected for two reasons.
First, the public surface cost: `@TaskLocal`-declared task-locals require the `$logger`
projection syntax for the scope methods (`MyApp.$logger.withMetadata(merging: …) { … }`),
which is unfamiliar and easy to get wrong; alternatively, exposing `TaskLocal<Logger>`
typed properties would leak a stdlib type into the swift-log surface that we'd rather
keep internal. Hiding the task-local behind `Logger.current` and the `withLogger` free
functions trades isolation for a cleaner API.
Second, the leak case is disciplinable. The only way library code propagates its own
metadata downstream through `Logger.current` is by calling `withLogger(mergingMetadata:)`
or `withLogger(metadata:)`. The documented contract is that those overloads are
application-side APIs: libraries read `Logger.current` and use per-statement `metadata:`
or a local copy for their own context; they do not push. Per-module isolation would make
the leak impossible *by construction* even when discipline fails, but it would also
fragment cross-cutting metadata propagation (`request.id` accumulated at the application
layer would not appear on library log lines without an explicit bridge from one
task-local to another) — which is the propagation we most want by default.
If structural isolation turns out to matter for specific use cases, the public
`TaskLocal<Logger>` extension surface can be added as a non-breaking follow-up.
#### Use another third-party dependency management package
Swift packages ecosystem has packages for managing dependencies, one of those can
be used to handle a task-local `Logger` instance. Rejected because if a library
wants to benefit from a common logger without adding it to its API surface,
it would have to depend on that extra package, effectively imposing that choice on
the application. But the dependency mechanism is an application-level decision,
an app may prefer a different approach, which leads to fragmentation or extra solutions
to bridge them.
#### Let applications create their own task-local logger objects
Applications can declare their own task-local `Logger` instance and API explicitly,
or via another dependency mechanism package. Rejected because it leaves library
dependencies out of the picture and hurts discoverability and composability
of the solution.
@@ -0,0 +1,19 @@
# ``Logging/LogEvent``
## Topics
### Creating a log event
- ``init(level:message:metadata:source:file:function:line:)``
- ``init(level:message:error:metadata:source:file:function:line:)``
### Inspecting a log event
- ``level``
- ``message``
- ``error``
- ``metadata``
- ``source``
- ``file``
- ``function``
- ``line``
@@ -4,6 +4,8 @@
### Sending log messages
- ``log(event:)-7x67``
- ``log(event:)-17f2r``
- ``log(level:message:metadata:source:file:function:line:)-8kgt7``
- ``log(level:message:metadata:source:file:function:line:)-69pez``
- ``log(level:message:metadata:file:function:line:)-89rya``
@@ -9,3 +9,8 @@
- ``array(_:)``
- ``dictionary(_:)``
### Working with attributes
- ``attributed(_:attributes:)``
- ``attributes``
@@ -10,39 +10,63 @@
- ``init(label:factory:)-6iktu``
- ``MetadataProvider``
### Task-local logger
- ``current``
- ``withLogger(_:_:)-3dt06``
- ``withLogger(_:_:)-70nli``
- ``withLogger(mergingMetadata:_:)-2c7dy``
- ``withLogger(mergingMetadata:_:)-3eduo``
- ``withLogger(logLevel:handler:metadata:_:)-2pd9p``
- ``withLogger(logLevel:handler:metadata:_:)-5nmw6``
### Sending trace log messages
- ``trace(_:metadata:file:function:line:)``
- ``trace(_:metadata:source:file:function:line:)``
- ``trace(_:error:metadata:source:file:function:line:)``
### Sending debug log messages
- ``debug(_:metadata:file:function:line:)``
- ``debug(_:metadata:source:file:function:line:)``
- ``debug(_:error:metadata:source:file:function:line:)``
### Sending info log messages
- ``info(_:metadata:file:function:line:)``
- ``info(_:metadata:source:file:function:line:)``
- ``info(_:error:metadata:source:file:function:line:)``
### Sending notice log messages
- ``notice(_:metadata:file:function:line:)``
- ``notice(_:metadata:source:file:function:line:)``
- ``notice(_:error:metadata:source:file:function:line:)``
### Sending warning log messages
- ``warning(_:metadata:file:function:line:)``
- ``warning(_:metadata:source:file:function:line:)``
- ``warning(_:error:metadata:source:file:function:line:)``
### Sending error log messages
- ``error(_:metadata:file:function:line:)``
- ``error(_:metadata:source:file:function:line:)``
- ``error(_:error:metadata:source:file:function:line:)``
### Sending critical log messages
- ``critical(_:metadata:file:function:line:)``
- ``critical(_:metadata:source:file:function:line:)``
- ``critical(_:error:metadata:source:file:function:line:)``
### Sending general log messages
- ``log(level:_:metadata:file:function:line:)``
- ``log(level:_:metadata:source:file:function:line:)``
- ``log(level:_:error:metadata:source:file:function:line:)``
- ``Level``
- ``Message``
- ``Metadata``
@@ -52,6 +76,10 @@
- ``subscript(metadataKey:)``
- ``MetadataValue``
### Metadata attribute types
- ``MetadataValueAttributes``
### Inspecting a logger
- ``label``
Loaded 100 of 134 files, more files were not shown because too many files have changed in this diff. Show more