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>
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>
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.
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
Add an InMemoryLogHandler
### Motivation:
Library maintainers should be able to test that their libraries log what
they expect
### Modifications:
Create a new InMemoryLogging product, which contains an
InMemoryLogHandler
This log handler can be used to make a logger, pass the logger into some
function, and then assert that logs were emitted.
See the tests for example usage
### Future:
For now i have left this very bare-bones. We could in future add
convenience functions. For example
- a function to assert that a particular log message was logged
- a static function to create a logger with this handler
---------
Co-authored-by: Franz Busch <privat@franz-busch.de>