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
### 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.
_[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
_[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
### 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.
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?
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>
### 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.
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>
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>
### 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
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
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>
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.
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.
### 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.
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.
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.
Add simple benchmarks measuring instructions count and allocations when
logging with various log levels.
### Motivation:
Establish the baseline and have automated checks before approaching
performance improvements.
### Modifications:
- Dependency on https://github.com/ordo-one/package-benchmark added
- A new `Benchmarks` sub-package is added
- CI workflows now run benchmarks
### Result:
- CI workflows are running benchmarks on Linux and macOS
- Thresholds are recorded and verified only on macOS
An example of a benchmark failing with a **better** results than
expected:
https://github.com/apple/swift-log/actions/runs/19540944353/job/55950355442
An example of a benchmark failing with a **worse** results than
expected:
https://github.com/apple/swift-log/actions/runs/19569105729/job/56038101552