Compare commits

..
40 Commits
Author SHA1 Message Date
tomer doron 33c2b451c9 [DNM] test PR 2023-03-24 15:43:39 -07:00
Mahdi BahramiandKonrad `ktoso` Malawski f79ba6a75f Add DiscordBM/DiscordLogger to loggers list (#257)
* Add DiscordBM/DiscordLogger to loggers list

Adds [DiscordBM](https://github.com/MahdiBM/DiscordBM/blob/discord-logger/README.md#discord-logger) to the logger list.

The description is:

> a Discord package containing a standalone [DiscordLogger library](https://github.com/MahdiBM/DiscordBM/blob/discord-logger/README.md#discord-logger)

Please do tell if you think "standalone" is misleading 🤔 I'm just trying to imply that users don't need to depend on the full package just for Discord-logging.

Resolves #256

* Update README.md

---------

Co-authored-by: Konrad `ktoso` Malawski <konrad_malawski@apple.com>
2023-02-12 17:56:04 -08:00
Konrad `ktoso` Malawski 6763fd0b73 Remove leftover 5.0 Package.swift; not supported since 1.5.0 (#259) 2023-01-31 22:27:53 +09:00
Yim Lee 32e8d72446 Add CI for Swift 5.8 and update nightly to Ubuntu 22.04 (#255) 2023-01-24 10:41:01 +09:00
Konrad `ktoso` Malawski b2eff1c427 Handle providers properly in multiplex log handler (#254)
Co-authored-by: Moritz Lang <hi@slashmo.codes>
Resolves https://github.com/apple/swift-log/issues/253
2023-01-24 10:10:39 +09:00
Konrad `ktoso` Malawski ba2a9f5b93 Avoid logging warnings when handler does not support metadataproviders (#252) 2023-01-23 23:58:13 +09:00
Moritz LangandKonrad `ktoso` Malawski 3e3ef75109 Emit correct metadata from StreamLogHandler (#251)
Co-authored-by: Konrad `ktoso` Malawski <konrad_malawski@apple.com>
2023-01-19 05:41:36 +09:00
Konrad `ktoso` MalawskiandYim Lee bd4519f1c2 Allow passing explicit provider into the stream handlers (#250)
Co-authored-by: Yim Lee <yim_lee@apple.com>
2023-01-18 12:32:30 -08:00
e6ca651cbc Metadata Providers (e.g. for Distributed Tracing) in LogHandlers (#238)
Co-authored-by: Moritz Lang <hi@slashmo.codes>
Co-authored-by: Yim Lee <yim_lee@apple.com>
2023-01-18 16:23:37 +09:00
Timo Boll dc77805fdc Fixes link to Supabase repository (#245) 2023-01-05 16:32:24 -08:00
Yim Lee e979c6945c Add .spi.yml for Swift Package Index DocC support (#240) 2022-12-01 21:41:27 -08:00
Lukas d86803715f Fix build for wasm (#236)
Seems like a few places were missed in the locking refactor, which made the WASM build fail
2022-11-02 11:00:11 -07:00
Ruslan Kavetsky f7b7977065 Update README.md (#233) 2022-09-17 15:00:35 +09:00
Konrad `ktoso` Malawski ce09fe6dac Undo 5.7 package files, not needed yet (#232)
* Undo 5.7 package files, not needed yet

* no need for xcrun in docs preview script
2022-08-24 12:33:23 +09:00
Konrad `ktoso` Malawski a8e1148aa5 =docc Move to multiple Package.swift files (#231)
* +docc prepare for docc docs

* fix syntax in one of the package files

* ignore package.resolved
2022-08-23 18:29:56 +09:00
Konrad `ktoso` Malawski 483e2bbcdd =docc Make docs use symbol references (#230) 2022-08-23 17:11:11 +09:00
Konrad `ktoso` MalawskiandYim Lee d5bf59c6b2 [docs] Minimal docc setup and landing page (#226)
* [docs] Minimal docc setup and landing page

* move index file

* Update Sources/Logging/Logging.swift

Co-authored-by: Yim Lee <yim_lee@apple.com>

Co-authored-by: Yim Lee <yim_lee@apple.com>
2022-08-23 16:08:28 +09:00
Konrad `ktoso` Malawski 6fe203dc33 [sendable] MetadataValue conformance must be unchecked on 5.6 now 2022-08-15 09:19:49 +09:00
Konrad `ktoso` Malawski 6b0ccb1ca8 [sendable] Sendable conformance checks cause errors on 5.6 but warnings on 5.7 2022-08-15 09:19:49 +09:00
Joseph HeckandKonrad `ktoso` Malawski 8fc79cae9d minimal DocC markdown to order Logger.Levels (#225)
* minimal DocC markdown to order Logger.Levels

Motivation:

When viewed in documentation generated by DocC, the enumeration levels
are ordered alphabetically, removintg the implied ordering in the
source. The written overview of the enum relies on that ordering to make
sense.

Modifications:

Adding a single file that provides structure to Logging/Logger/Levels
within DocC generated documentation.

Result:

When imported into a project that leverages Swift 5.6 (such as Vapor),
the generated documentation for the levels provided by
Logging/Logger/Levels are displayed in the order intended/expected by
the documentation.

* Adding a Swift 5.6 version of Package.swift

Motivation:

Per DocC team, an updated version is required for the DocC changes
to be picked up and reflected in generated dcumentation, even for
upstream projects already using swift 5.6 or later.

Modifications:

Adding Package.Swift@5.6 with the swift version updated.

Result:

Hopefully, documentation updates in DocC generated content will be
reflected.

* Updating linuxmain test generation for <swift5.6

Motivation:

To appease CI, added #if statements into generated LinuxMain
content to handle conditional compilation with Swift 5.6 and later.

Modifications:

Added #if statements to test generating script and re-ran the script

Result:

CI will hopefully pass.

* also guard the LinuxMain file

* Force using test discovery on 5.6+ even though tools version is latest
but LinuxMain exists

* cleanup

* simplify docc links

* formatting revert

* ignore Package-swift5.6.swift from soundness license check

Co-authored-by: Konrad `ktoso` Malawski <konrad_malawski@apple.com>
2022-07-20 14:38:17 +09:00
tomer doron f2e8667d50 adopt sendable (#218)
motivation: adjust to swift 5.6

changes:
* define sendable shims for protocols and structs that may be used in async context
* adjust tests
* add a test to make sure no warning are emitted
2022-07-01 16:38:19 -07:00
tomer doron 9f3731aa55 better abstration for LoggingSystem state (#222)
motivation: prepare for sendable checks

changes:
* abstract the LoggingSystem state into a "boxed" class that handles the locking
* adjust call sites
2022-06-29 11:07:50 -07:00
Guilherme Souza 2bf6215b68 Add binaryscraping/swift-log-supabase to README (#221) 2022-05-10 11:39:59 -07:00
tomer doron 432a93204e ci update (#219)
motivation: 5.6 is out

changes:
* use release version of 5.6
* add docker setup for 5.7 (using nightly for now)
2022-03-16 21:04:07 -07:00
Cory Benfield dc6dd5caaa Add 5.6 nightly CI (#214)
The 5.6 nightly images are available, let's use them.
2022-01-18 10:03:36 -08:00
tomer doron 5db2bc495a update doc generation script (#213)
motivation: source-kitten has changed how its invoked

changes:
* invoke source-kitten with the correct flags
* make location of source-kitten source checkout more robust
2021-12-16 15:18:06 -08:00
Andriy Druk 4e75f88c6a Add Android support (#209) 2021-10-26 16:20:20 -07:00
tomer doron 77192b9e21 add docker setup for 5.5 (#211)
motivation: ci on 5.5

changes: add docker setup for 5.5
2021-10-18 15:15:28 -07:00
tomer doron b172d1ae3d fix jazzy issues on older versions of ubuntu (#210) 2021-10-18 15:03:31 -07:00
Shiva HuangandKonrad `ktoso` Malawski a7e6d7fef5 Add swift-log-SwiftyBeaver as a new logging backend to the Readme (#203)
Co-authored-by: Konrad `ktoso` Malawski <ktoso@apple.com>
2021-08-10 16:34:45 +09:00
Philipp, Zagar 9cdea8c2af Add swift-log-elk to Readme (#201) 2021-08-10 16:30:26 +09:00
Saleem Abdulrasool d8af258aec Tests: enable tests on Windows (#198)
This adds support for running the tests on Windows.  However, running
the tests on Windows requires SPM currently.  While it is possible to
enable executing tests with CMake, the expectation is that SPM builds
would be the most common and CMake is largely used for bootstrapping.
The changes here require alterations to remove the POSIX threading to
get the thread ID.  Additionally, pipes on Windows are not similar to
pipes on Unix platforms. Finally, we must add Windows to the platform
list, which is temporary (it would be better to use test discovery in
SPM).
2021-06-15 06:25:41 +09:00
Saleem Abdulrasool 02770d91fc Logging: avoid a deprecation warning on Windows (#199)
Windows recommends the safety extension usage which in this case
explicitly allow you to be informed of failures.  This just avoids an
annoying warning when using logging in projects.
2021-06-14 21:05:34 +09:00
Johannes Weiss 7ebe44cb03 adopt security guidelines (#197) 2021-06-09 10:18:03 +01:00
tomer doron 65a8e5e921 update 5.4 to release docker image (#196)
motivation: 5.4 is out!

changes: use release docker images instead of nightly
2021-05-06 18:07:14 -07:00
George Barnett 08ec50d7b1 Add SwiftLogNoOpLogHandler.init(_: String) (#194)
Motivation:

`LogHandler` facotories are given a label as input and return a
`LogHandler`. Since the no-op handler doesn't care about the label
callers must provide a thunk: `{ _ in SwiftLogNoOpLogHandler() }`.
That's fine but slightly more annoying to type than it needs to be.

Modifications:

- Add `SwiftLogNoOpLogHandler.init(_: String)`

Result:

Users can create a logger with the no-op handler with:

```swift
Logger(label: "foo", factory: SwiftLogNoOpLogHandler.init)
```

instead of:

```swift
Logger(label: "foo", factory: { _ in SwiftLogNoOpLogHandler() })
```
2021-05-05 19:02:50 +09:00
Johannes Weiss 3577a992d3 use #fileID for Swift 5.3+ (#187)
Motivation:

Right now, we use the full path (`#file`) for the logging as well as for
parsing out the module name (which goes into `source` by default).

This has two problems:

1. The file names contain the build server's full path, ie. aren't
   portable across different compiles (and are very long).
2. The module name parsing fails if we log from a file that's not in a
   directory named just like the module.

Modification:

Switch `#file` for `#fileID`. This changes a bunch of things:

- `source` is always the module name by default (great!)
- `file` changes from `/the/full/path/on/disk` to `ModuleName/FileBaseName.swift` (I think better, but it's a change)

Result:

`source` is more correct, `file` will be different.
2021-04-06 14:28:43 +01:00
felipejinliandJohannes Weiss b1d1c0372a Improve StdioOutputStream with fwrite (#180) (#188)
Replaced `fputs` with `fwrite`, added test and made spelling corrections

Motivation:

If a 0 byte is logged, `fputs` would not output the content after the 0 byte making it harder to debug (see #180). `fwrite` uses a count argument so content after 0 byte can be logged.

Modifications:

Replaced `fputs` with the correct call to `fwrite`.   Added helper internal func `contiguousUTF8(_ string: String) -> String.UTF8View`. Added `testStdioOutputStreamWrite()` to test ability to log content after 0 byte.

Result:

Improved debugging experience

Co-authored-by: Johannes Weiss <johannesweiss@apple.com>
2021-04-06 14:19:35 +01:00
Moritz Lang bc049d05d0 Include source in StreamLogHandler output (#189)
Motivation:

When using the same Logger across an application in combination
with the default StreamLogHandler, it may be difficult to differentiate
between logs produced by different modules. ServiceLifecycle works around
this by prepending the log message with [Lifecycle], which is what I'd like
to do StreamLogHandler by default, leveraging the source log parameter.

Modifications:

StreamLogHandler will include the source in brackets right before
the log message when writing a log.

Result:

Logs from different modules are easily differentiable when produced
using the same Logger instance.
2021-04-06 21:41:35 +09:00
Peter Steinberger bda2661797 Remove references to Swift 4 (#186)
I found https://github.com/apple/swift-log/releases/tag/0.0.0 however these are just shims.
Seems unlikely that this is still needed.
2021-03-05 08:32:41 +09:00
38 changed files with 2219 additions and 215 deletions

No files matched your search

+1
View File
@@ -1,4 +1,5 @@
.DS_Store
Package.resolved
/.build
/Packages
/*.xcodeproj
+4
View File
@@ -0,0 +1,4 @@
version: 1
builder:
configs:
- documentation_targets: [Logging]
+4 -1
View File
@@ -1,4 +1,4 @@
// swift-tools-version:5.0
// swift-tools-version:5.6
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
@@ -20,6 +20,9 @@ let package = Package(
products: [
.library(name: "Logging", targets: ["Logging"]),
],
dependencies: [
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
],
targets: [
.target(
name: "Logging",
+33
View File
@@ -0,0 +1,33 @@
// swift-tools-version:5.1
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
let package = Package(
name: "swift-log",
products: [
.library(name: "Logging", targets: ["Logging"]),
],
targets: [
.target(
name: "Logging",
dependencies: []
),
.testTarget(
name: "LoggingTests",
dependencies: ["Logging"]
),
]
)
+33
View File
@@ -0,0 +1,33 @@
// swift-tools-version:5.2
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
let package = Package(
name: "swift-log",
products: [
.library(name: "Logging", targets: ["Logging"]),
],
targets: [
.target(
name: "Logging",
dependencies: []
),
.testTarget(
name: "LoggingTests",
dependencies: ["Logging"]
),
]
)
+33
View File
@@ -0,0 +1,33 @@
// swift-tools-version:5.3
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
let package = Package(
name: "swift-log",
products: [
.library(name: "Logging", targets: ["Logging"]),
],
targets: [
.target(
name: "Logging",
dependencies: []
),
.testTarget(
name: "LoggingTests",
dependencies: ["Logging"]
),
]
)
+33
View File
@@ -0,0 +1,33 @@
// swift-tools-version:5.4
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
let package = Package(
name: "swift-log",
products: [
.library(name: "Logging", targets: ["Logging"]),
],
targets: [
.target(
name: "Logging",
dependencies: []
),
.testTarget(
name: "LoggingTests",
dependencies: ["Logging"]
),
]
)
+33
View File
@@ -0,0 +1,33 @@
// swift-tools-version:5.5
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import PackageDescription
let package = Package(
name: "swift-log",
products: [
.library(name: "Logging", targets: ["Logging"]),
],
targets: [
.target(
name: "Logging",
dependencies: []
),
.testTarget(
name: "LoggingTests",
dependencies: ["Logging"]
),
]
)
+12 -2
View File
@@ -10,7 +10,7 @@ If you have a server-side Swift application, or maybe a cross-platform (for exam
#### Adding the dependency
`SwiftLog` is designed for Swift 5, the `1.0.0` release requires Swift 5 (however we will soon tag a `0.x` version that will work with Swift 4 for the transition period). To depend on the logging API package, you need to declare your dependency in your `Package.swift`:
`SwiftLog` is designed for Swift 5. To depend on the logging API package, you need to declare your dependency in your `Package.swift`:
```swift
.package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"),
@@ -82,6 +82,10 @@ As the API has just launched, not many implementations exist yet. If you are int
| [crspybits/swift-log-file](https://github.com/crspybits/swift-log-file) | a simple local file logger (using `Foundation` `FileManager`) |
| [sushichop/Puppy](https://github.com/sushichop/Puppy) | a logging backend that supports multiple transports(console, file, syslog, etc.) and has the feature with formatting and file log rotation |
| [luoxiu/LogDog](https://github.com/luoxiu/LogDog) | user-friendly logging with sinks and appenders |
| [ShivaHuang/swift-log-SwiftyBeaver](https://github.com/ShivaHuang/swift-log-SwiftyBeaver) | a logging backend for printing colored logging to Xcode console / file, or sending encrypted logging to [SwiftyBeaver](https://swiftybeaver.com) platform. |
| [Apodini/swift-log-elk](https://github.com/Apodini/swift-log-elk) | a logging backend that formats, caches and sends log data to [elastic/logstash](https://github.com/elastic/logstash) |
| [binaryscraping/swift-log-supabase](https://github.com/binaryscraping/swift-log-supabase) | a logging backend that sends log entries to [Supabase](https://github.com/supabase/supabase). |
| [MahdiBM/DiscordBM](https://github.com/MahdiBM/DiscordBM) | a Discord client package containing a standalone [DiscordLogger library](https://github.com/MahdiBM/DiscordBM/blob/discord-logger/README.md#discord-logger) |
| Your library? | [Get in touch!](https://forums.swift.org/c/server) |
## What is an API package?
@@ -154,7 +158,7 @@ A `LogHandler` or logging backend implementation is anything that conforms to th
```swift
public protocol LogHandler {
func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)
func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)
subscript(metadataKey _: String) -> Logger.Metadata.Value? { get set }
@@ -202,6 +206,10 @@ around between libraries to preserve metadata and the like.
If you want to filter all log messages originating from a certain subsystem, filter by `source` which defaults to the module that is emitting the
log message.
## Security
Please see [SECURITY.md](SECURITY.md) for SwiftLog's security process.
## Design
This logging API was designed with the contributors to the Swift on Server community and approved by the [SSWG (Swift Server Work Group)](https://swift.org/server/) to the 'sandbox level' of the SSWG's [incubation process](https://github.com/swift-server/sswg/blob/master/process/incubation.md).
@@ -210,3 +218,5 @@ This logging API was designed with the contributors to the Swift on Server commu
- [log levels](https://forums.swift.org/t/logging-levels-for-swifts-server-side-logging-apis-and-new-os-log-apis/20365)
[api-docs]: https://apple.github.io/swift-log/docs/current/Logging/Structs/Logger.html
+43
View File
@@ -0,0 +1,43 @@
# 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://github.com/swift-server/sswg/blob/main/security/README.md
[swift-forums-sec]: https://forums.swift.org/c/server/security-updates/
[mitre]: https://cveform.mitre.org/
+13
View File
@@ -0,0 +1,13 @@
# ``Logging/Logger/Level``
## Topics
### Log levels
- ``trace``
- ``debug``
- ``info``
- ``notice``
- ``warning``
- ``error``
- ``critical``
+30
View File
@@ -0,0 +1,30 @@
# ``Logging``
A Logging API for Swift.
## Getting Started
If you have a server-side Swift application, or maybe a cross-platform (for example Linux & macOS) app/library, and you would like to log, we think targeting this logging API package is a great idea. Below you'll find all you need to know to get started.
### Log handler implementations
This package offers the common Logging API as well as a very simple stdout log handler.
In a real system or application, you will want to use one of the many community maintained log handler implementations.
Please refer to the [complete list of community maintained logging backend implementations](https://github.com/apple/swift-log#selecting-a-logging-backend-implementation-applications-only).
## Topics
### Logging API
- ``Logger``
- ``LoggingSystem``
### Log Handlers
- ``LogHandler``
- ``MultiplexLogHandler``
- ``StreamLogHandler``
- ``SwiftLogNoOpLogHandler``
+38 -17
View File
@@ -28,9 +28,7 @@
#if canImport(WASILibc)
// No locking on WASILibc
#else
#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS)
#elseif canImport(Darwin)
import Darwin
#elseif os(Windows)
import WinSDK
@@ -47,7 +45,9 @@ import Glibc
/// one used by NIO. On Windows, the lock is based on the substantially similar
/// `SRWLOCK` type.
internal final class Lock {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
fileprivate let mutex: UnsafeMutablePointer<SRWLOCK> =
UnsafeMutablePointer.allocate(capacity: 1)
#else
@@ -57,7 +57,9 @@ internal final class Lock {
/// Create a new lock.
public init() {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
InitializeSRWLock(self.mutex)
#else
var attr = pthread_mutexattr_t()
@@ -70,13 +72,16 @@ internal final class Lock {
}
deinit {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
// SRWLOCK does not need to be free'd
self.mutex.deallocate()
#else
let err = pthread_mutex_destroy(self.mutex)
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
#endif
self.mutex.deallocate()
#endif
}
/// Acquire the lock.
@@ -84,7 +89,9 @@ internal final class Lock {
/// Whenever possible, consider using `withLock` instead of this method and
/// `unlock`, to simplify lock handling.
public func lock() {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
AcquireSRWLockExclusive(self.mutex)
#else
let err = pthread_mutex_lock(self.mutex)
@@ -97,7 +104,9 @@ internal final class Lock {
/// Whenever possible, consider using `withLock` instead of this method and
/// `lock`, to simplify lock handling.
public func unlock() {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
ReleaseSRWLockExclusive(self.mutex)
#else
let err = pthread_mutex_unlock(self.mutex)
@@ -138,7 +147,9 @@ extension Lock {
/// one used by NIO. On Windows, the lock is based on the substantially similar
/// `SRWLOCK` type.
internal final class ReadWriteLock {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
fileprivate let rwlock: UnsafeMutablePointer<SRWLOCK> =
UnsafeMutablePointer.allocate(capacity: 1)
fileprivate var shared: Bool = true
@@ -149,7 +160,9 @@ internal final class ReadWriteLock {
/// Create a new lock.
public init() {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
InitializeSRWLock(self.rwlock)
#else
let err = pthread_rwlock_init(self.rwlock, nil)
@@ -158,13 +171,16 @@ internal final class ReadWriteLock {
}
deinit {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
// SRWLOCK does not need to be free'd
self.rwlock.deallocate()
#else
let err = pthread_rwlock_destroy(self.rwlock)
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
#endif
self.rwlock.deallocate()
#endif
}
/// Acquire a reader lock.
@@ -172,7 +188,9 @@ internal final class ReadWriteLock {
/// Whenever possible, consider using `withReaderLock` instead of this
/// method and `unlock`, to simplify lock handling.
public func lockRead() {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
AcquireSRWLockShared(self.rwlock)
self.shared = true
#else
@@ -186,7 +204,9 @@ internal final class ReadWriteLock {
/// Whenever possible, consider using `withWriterLock` instead of this
/// method and `unlock`, to simplify lock handling.
public func lockWrite() {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
AcquireSRWLockExclusive(self.rwlock)
self.shared = false
#else
@@ -201,7 +221,9 @@ internal final class ReadWriteLock {
/// instead of this method and `lockRead` and `lockWrite`, to simplify lock
/// handling.
public func unlock() {
#if os(Windows)
#if canImport(WASILibc)
// WASILibc is single threaded, provides no locks
#elseif os(Windows)
if self.shared {
ReleaseSRWLockShared(self.rwlock)
} else {
@@ -261,4 +283,3 @@ extension ReadWriteLock {
try self.withWriterLock(body)
}
}
#endif
+34 -3
View File
@@ -15,14 +15,14 @@
/// A `LogHandler` is an implementation of a logging backend.
///
/// This type is an implementation detail and should not normally be used, unless implementing your own logging backend.
/// To use the SwiftLog API, please refer to the documentation of `Logger`.
/// To use the SwiftLog API, please refer to the documentation of ``Logger``.
///
/// # Implementation requirements
///
/// To implement your own `LogHandler` you should respect a few requirements that are necessary so applications work
/// as expected regardless of the selected `LogHandler` implementation.
///
/// - The `LogHandler` must be a `struct`.
/// - The ``LogHandler`` must be a `struct`.
/// - The metadata and `logLevel` properties must be implemented so that setting them on a `Logger` does not affect
/// other `Logger`s.
///
@@ -113,7 +113,13 @@
/// Please note that the above `LogHandler` will still pass the 'log level is a value' test above it iff the global log
/// level has not been overridden. And most importantly it passes the requirement listed above: A change to the log
/// level on one `Logger` should not affect the log level of another `Logger` variable.
public protocol LogHandler {
public protocol LogHandler: _SwiftLogSendableLogHandler {
/// The metadata provider this `LogHandler` will use when a log statement is about to be emitted.
///
/// A ``Logger/MetadataProvider`` may add a constant set of metadata,
/// or use task-local values to pick up contextual metadata and add it to emitted logs.
var metadataProvider: Logger.MetadataProvider? { get set }
/// This method is called when a `LogHandler` 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.
@@ -163,6 +169,23 @@ public protocol LogHandler {
var logLevel: Logger.Level { get set }
}
extension LogHandler {
/// Default implementation for `metadataProvider` which defaults to `nil`.
/// This default exists in order to facilitate source-compatible introduction of the `metadataProvider` protocol requirement.
public var metadataProvider: Logger.MetadataProvider? {
get {
nil
}
set {
#if DEBUG
if LoggingSystem.warnOnceLogHandlerNotSupportedMetadataProvider(Self.self) {
self.log(level: .warning, message: "Attempted to set metadataProvider on \(Self.self) that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.", metadata: nil, source: "Logging", file: #file, function: #function, line: #line)
}
#endif
}
}
}
extension LogHandler {
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
public func log(level: Logger.Level,
@@ -186,3 +209,11 @@ extension LogHandler {
line: line)
}
}
// MARK: - Sendable support helpers
#if compiler(>=5.6)
@preconcurrency public protocol _SwiftLogSendableLogHandler: Sendable {}
#else
public protocol _SwiftLogSendableLogHandler {}
#endif
File diff suppressed because it is too large. Load diff
+113
View File
@@ -0,0 +1,113 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2018-2022 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS)
import Darwin
#elseif os(Windows)
import CRT
#elseif canImport(Glibc)
import Glibc
#elseif canImport(WASILibc)
import WASILibc
#else
#error("Unsupported runtime")
#endif
#if compiler(>=5.6)
@preconcurrency protocol _SwiftLogSendable: Sendable {}
#else
protocol _SwiftLogSendable {}
#endif
extension Logger {
/// A `MetadataProvider` is used to automatically inject runtime-generated metadata
/// to all logs emitted by a logger.
///
/// ### Example
/// A metadata provider may be used to automatically inject metadata such as
/// trace IDs:
///
/// ```swift
/// import Tracing // https://github.com/apple/swift-distributed-tracing
///
/// let metadataProvider = MetadataProvider {
/// guard let traceID = Baggage.current?.traceID else { return nil }
/// return ["traceID": "\(traceID)"]
/// }
/// let logger = Logger(label: "example", metadataProvider: metadataProvider)
/// var baggage = Baggage.topLevel
/// baggage.traceID = 42
/// Baggage.withValue(baggage) {
/// logger.info("hello") // automatically includes ["traceID": "42"] metadata
/// }
/// ```
///
/// We recommend referring to [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing)
/// for metadata providers which make use of its tracing and metadata propagation infrastructure. It is however
/// possible to make use of metadata providers independently of tracing and instruments provided by that library,
/// if necessary.
public struct MetadataProvider: _SwiftLogSendable {
/// Provide ``Logger.Metadata`` from current context.
#if swift(>=5.5) && canImport(_Concurrency) // we could instead typealias the function type, but it was requested that we avoid this for better developer experience
@usableFromInline
internal let _provideMetadata: @Sendable() -> Metadata
#else
@usableFromInline
internal let _provideMetadata: () -> Metadata
#endif
/// Create a new `MetadataProvider`.
///
/// - Parameter provideMetadata: A closure extracting metadata from the current execution context.
#if swift(>=5.5) && canImport(_Concurrency)
public init(_ provideMetadata: @escaping @Sendable() -> Metadata) {
self._provideMetadata = provideMetadata
}
#else
public init(_ provideMetadata: @escaping () -> Metadata) {
self._provideMetadata = provideMetadata
}
#endif
/// Invoke the metadata provider and return the generated contextual ``Logger/Metadata``.
public func get() -> Metadata {
return self._provideMetadata()
}
}
}
extension Logger.MetadataProvider {
/// A pseudo-`MetadataProvider` that can be used to merge metadata from multiple other `MetadataProvider`s.
///
/// ### Merging conflicting keys
///
/// `MetadataProvider`s are invoked left to right in the order specified in the `providers` argument.
/// In case multiple providers try to add a value for the same key, the last provider "wins" and its value is being used.
///
/// - Parameter providers: An array of `MetadataProvider`s to delegate to. The array must not be empty.
/// - Returns: A pseudo-`MetadataProvider` merging metadata from the given `MetadataProvider`s.
public static func multiplex(_ providers: [Logger.MetadataProvider]) -> Logger.MetadataProvider? {
assert(!providers.isEmpty, "providers MUST NOT be empty")
return Logger.MetadataProvider {
providers.reduce(into: [:]) { metadata, provider in
let providedMetadata = provider.get()
guard !providedMetadata.isEmpty else {
return
}
metadata.merge(providedMetadata, uniquingKeysWith: { _, rhs in rhs })
}
}
}
}
+2 -1
View File
@@ -22,7 +22,7 @@ import XCTest
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
///
#if os(Linux) || os(FreeBSD)
#if os(Linux) || os(FreeBSD) || os(Windows) || os(Android)
@testable import LoggingTests
XCTMain([
@@ -31,5 +31,6 @@ XCTMain([
testCase(LocalLoggerTest.allTests),
testCase(LoggingTest.allTests),
testCase(MDCTest.allTests),
testCase(MetadataProviderTest.allTests),
])
#endif
@@ -31,6 +31,8 @@ extension LoggingTest {
("testMultiplexLogHandlerNeedNotMaterializeValuesMultipleTimes", testMultiplexLogHandlerNeedNotMaterializeValuesMultipleTimes),
("testMultiplexLogHandlerMetadata_settingMetadataThroughToUnderlyingHandlers", testMultiplexLogHandlerMetadata_settingMetadataThroughToUnderlyingHandlers),
("testMultiplexLogHandlerMetadata_readingHandlerMetadata", testMultiplexLogHandlerMetadata_readingHandlerMetadata),
("testMultiplexMetadataProviderSet", testMultiplexMetadataProviderSet),
("testMultiplexMetadataProviderExtract", testMultiplexMetadataProviderExtract),
("testDictionaryMetadata", testDictionaryMetadata),
("testListMetadata", testListMetadata),
("testStringConvertibleMetadata", testStringConvertibleMetadata),
@@ -41,8 +43,13 @@ extension LoggingTest {
("testAllLogLevelsWork", testAllLogLevelsWork),
("testAllLogLevelByFunctionRefWithSource", testAllLogLevelByFunctionRefWithSource),
("testAllLogLevelByFunctionRefWithoutSource", testAllLogLevelByFunctionRefWithoutSource),
("testLogsEmittedFromSubdirectoryGetCorrectModuleInNewerSwifts", testLogsEmittedFromSubdirectoryGetCorrectModuleInNewerSwifts),
("testLogMessageWithStringInterpolation", testLogMessageWithStringInterpolation),
("testLoggingAString", testLoggingAString),
("testMultiplexMetadataProviderMergesInSpecifiedOrder", testMultiplexMetadataProviderMergesInSpecifiedOrder),
("testLoggerWithoutFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider", testLoggerWithoutFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider),
("testLoggerWithPredefinedLibraryMetadataProvider", testLoggerWithPredefinedLibraryMetadataProvider),
("testLoggerWithFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider", testLoggerWithFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider),
("testMultiplexerIsValue", testMultiplexerIsValue),
("testLoggerWithGlobalOverride", testLoggerWithGlobalOverride),
("testLogLevelCases", testLogLevelCases),
@@ -51,8 +58,11 @@ extension LoggingTest {
("testStreamLogHandlerOutputFormat", testStreamLogHandlerOutputFormat),
("testStreamLogHandlerOutputFormatWithMetaData", testStreamLogHandlerOutputFormatWithMetaData),
("testStreamLogHandlerOutputFormatWithOrderedMetadata", testStreamLogHandlerOutputFormatWithOrderedMetadata),
("testStreamLogHandlerWritesIncludeMetadataProviderMetadata", testStreamLogHandlerWritesIncludeMetadataProviderMetadata),
("testStdioOutputStreamWrite", testStdioOutputStreamWrite),
("testStdioOutputStreamFlush", testStdioOutputStreamFlush),
("testOverloadingError", testOverloadingError),
("testCompileInitializeStandardStreamLogHandlersWithMetadataProviders", testCompileInitializeStandardStreamLogHandlersWithMetadataProviders),
]
}
}
+299 -16
View File
@@ -16,6 +16,8 @@ import XCTest
#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS)
import Darwin
#elseif os(Windows)
import WinSDK
#else
import Glibc
#endif
@@ -218,7 +220,84 @@ class LoggingTest: XCTestCase {
XCTAssertEqual(multiplexLogger.handler.metadata, [
"one": "111",
"two": "222",
"in": "in-1",
"in": "in-2",
])
}
func testMultiplexMetadataProviderSet() {
let logging1 = TestLogging()
let logging2 = TestLogging()
var handler1 = logging1.make(label: "1")
handler1.metadata["one"] = "111"
handler1.metadata["in"] = "in-1"
handler1.metadataProvider = .constant([
"provider-1": "provided-111",
"provider-overlap": "provided-111",
])
var handler2 = logging2.make(label: "2")
handler2.metadata["two"] = "222"
handler2.metadata["in"] = "in-2"
handler2.metadataProvider = .constant([
"provider-2": "provided-222",
"provider-overlap": "provided-222",
])
LoggingSystem.bootstrapInternal { _ in
MultiplexLogHandler([handler1, handler2])
}
let multiplexLogger = Logger(label: "test")
XCTAssertEqual(multiplexLogger.handler.metadata, [
"one": "111",
"two": "222",
"in": "in-2",
"provider-1": "provided-111",
"provider-2": "provided-222",
"provider-overlap": "provided-222",
])
XCTAssertEqual(multiplexLogger.handler.metadataProvider?.get(), [
"provider-1": "provided-111",
"provider-2": "provided-222",
"provider-overlap": "provided-222",
])
}
func testMultiplexMetadataProviderExtract() {
let logging1 = TestLogging()
let logging2 = TestLogging()
var handler1 = logging1.make(label: "1")
handler1.metadataProvider = .constant([
"provider-1": "provided-111",
"provider-overlap": "provided-111",
])
var handler2 = logging2.make(label: "2")
handler2.metadata["two"] = "222"
handler2.metadata["in"] = "in-2"
handler2.metadataProvider = .constant([
"provider-2": "provided-222",
"provider-overlap": "provided-222",
])
LoggingSystem.bootstrapInternal({ _, metadataProvider in
MultiplexLogHandler(
[handler1, handler2],
metadataProvider: metadataProvider
)
}, metadataProvider: .constant([
"provider-overlap": "provided-outer",
]))
let multiplexLogger = Logger(label: "test")
let provider = multiplexLogger.metadataProvider!
XCTAssertEqual(provider.get(), [
"provider-1": "provided-111",
"provider-2": "provided-222",
"provider-overlap": "provided-outer",
])
}
@@ -260,7 +339,7 @@ class LoggingTest: XCTestCase {
// Example of custom "box" which may be used to implement "render at most once" semantics
// Not thread-safe, thus should not be shared across threads.
internal class LazyMetadataBox: CustomStringConvertible {
internal final class LazyMetadataBox: CustomStringConvertible {
private var makeValue: (() -> String)?
private var _value: String?
@@ -301,7 +380,7 @@ class LoggingTest: XCTestCase {
}
private func dontEvaluateThisString(file: StaticString = #file, line: UInt = #line) -> Logger.Message {
XCTFail("should not have been evaluated", file: (file), line: line)
XCTFail("should not have been evaluated", file: file, line: line)
return "should not have been evaluated"
}
@@ -455,6 +534,15 @@ class LoggingTest: XCTestCase {
let error = logger.error(_:metadata:file:function:line:)
let critical = logger.critical(_:metadata:file:function:line:)
#if compiler(>=5.3)
trace("yes: trace", [:], #fileID, #function, #line)
debug("yes: debug", [:], #fileID, #function, #line)
info("yes: info", [:], #fileID, #function, #line)
notice("yes: notice", [:], #fileID, #function, #line)
warning("yes: warning", [:], #fileID, #function, #line)
error("yes: error", [:], #fileID, #function, #line)
critical("yes: critical", [:], #fileID, #function, #line)
#else
trace("yes: trace", [:], #file, #function, #line)
debug("yes: debug", [:], #file, #function, #line)
info("yes: info", [:], #file, #function, #line)
@@ -462,6 +550,7 @@ class LoggingTest: XCTestCase {
warning("yes: warning", [:], #file, #function, #line)
error("yes: error", [:], #file, #function, #line)
critical("yes: critical", [:], #file, #function, #line)
#endif
testLogging.history.assertExist(level: .trace, message: "yes: trace")
testLogging.history.assertExist(level: .debug, message: "yes: debug")
@@ -472,6 +561,30 @@ class LoggingTest: XCTestCase {
testLogging.history.assertExist(level: .critical, message: "yes: critical")
}
func testLogsEmittedFromSubdirectoryGetCorrectModuleInNewerSwifts() {
let testLogging = TestLogging()
LoggingSystem.bootstrapInternal(testLogging.make)
var logger = Logger(label: "\(#function)")
logger.logLevel = .trace
emitLogMessage("hello", to: logger)
#if compiler(>=5.3)
let moduleName = "LoggingTests" // the actual name
#else
let moduleName = "SubDirectoryOfLoggingTests" // the last path component of `#file` showing the failure mode
#endif
testLogging.history.assertExist(level: .trace, message: "hello", source: moduleName)
testLogging.history.assertExist(level: .debug, message: "hello", source: moduleName)
testLogging.history.assertExist(level: .info, message: "hello", source: moduleName)
testLogging.history.assertExist(level: .notice, message: "hello", source: moduleName)
testLogging.history.assertExist(level: .warning, message: "hello", source: moduleName)
testLogging.history.assertExist(level: .error, message: "hello", source: moduleName)
testLogging.history.assertExist(level: .critical, message: "hello", source: moduleName)
}
func testLogMessageWithStringInterpolation() {
let testLogging = TestLogging()
LoggingSystem.bootstrapInternal(testLogging.make)
@@ -501,6 +614,69 @@ class LoggingTest: XCTestCase {
testLogging.history.assertExist(level: .debug, message: "hello world!")
}
func testMultiplexMetadataProviderMergesInSpecifiedOrder() {
let logging = TestLogging()
let providerA = Logger.MetadataProvider { ["provider": "a", "a": "foo"] }
let providerB = Logger.MetadataProvider { ["provider": "b", "b": "bar"] }
let logger = Logger(label: #function,
factory: { label in
logging.makeWithMetadataProvider(label: label, metadataProvider: .multiplex([providerA, providerB]))
})
logger.log(level: .info, "test", metadata: ["one-off": "42"])
logging.history.assertExist(level: .info,
message: "test",
metadata: ["provider": "b", "a": "foo", "b": "bar", "one-off": "42"])
}
func testLoggerWithoutFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider() {
let logging = TestLogging()
LoggingSystem.bootstrapInternal({ label, metadataProvider in
logging.makeWithMetadataProvider(label: label, metadataProvider: metadataProvider)
}, metadataProvider: .init { ["provider": "42"] })
let logger = Logger(label: #function)
logger.log(level: .info, "test", metadata: ["one-off": "42"])
logging.history.assertExist(level: .info,
message: "test",
metadata: ["provider": "42", "one-off": "42"])
}
func testLoggerWithPredefinedLibraryMetadataProvider() {
let logging = TestLogging()
LoggingSystem.bootstrapInternal(
logging.makeWithMetadataProvider,
metadataProvider: .exampleMetadataProvider
)
let logger = Logger(label: #function)
logger.log(level: .info, "test", metadata: ["one-off": "42"])
logging.history.assertExist(level: .info,
message: "test",
metadata: ["example": "example-value", "one-off": "42"])
}
func testLoggerWithFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider() {
let logging = TestLogging()
LoggingSystem.bootstrapInternal(logging.makeWithMetadataProvider, metadataProvider: .init { ["provider": "42"] })
let logger = Logger(label: #function, factory: { label in
logging.makeWithMetadataProvider(label: label, metadataProvider: LoggingSystem.metadataProvider)
})
logger.log(level: .info, "test", metadata: ["one-off": "42"])
logging.history.assertExist(level: .info,
message: "test",
metadata: ["provider": "42", "one-off": "42"])
}
func testMultiplexerIsValue() {
let multi = MultiplexLogHandler([StreamLogHandler.standardOutput(label: "x"), StreamLogHandler.standardOutput(label: "y")])
LoggingSystem.bootstrapInternal { _ in
@@ -666,15 +842,16 @@ class LoggingTest: XCTestCase {
func testStreamLogHandlerOutputFormat() {
let interceptStream = InterceptStream()
let label = "testLabel"
LoggingSystem.bootstrapInternal { _ in
LoggingSystem.bootstrapInternal { label in
StreamLogHandler(label: label, stream: interceptStream)
}
let source = "testSource"
let log = Logger(label: label)
let testString = "my message is better than yours"
log.critical("\(testString)")
log.critical("\(testString)", source: source)
let pattern = "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label)\\s:\\s\(testString)$"
let pattern = "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label)\\s:\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(of: pattern, options: .regularExpression) != nil
@@ -685,15 +862,16 @@ class LoggingTest: XCTestCase {
func testStreamLogHandlerOutputFormatWithMetaData() {
let interceptStream = InterceptStream()
let label = "testLabel"
LoggingSystem.bootstrapInternal { _ in
LoggingSystem.bootstrapInternal { label in
StreamLogHandler(label: label, stream: interceptStream)
}
let source = "testSource"
let log = Logger(label: label)
let testString = "my message is better than yours"
log.critical("\(testString)", metadata: ["test": "test"])
log.critical("\(testString)", metadata: ["test": "test"], source: source)
let pattern = "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label)\\s:\\stest=test\\s\(testString)$"
let pattern = "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\+|-)\\d{4}\\s\(Logger.Level.critical)\\s\(label)\\s:\\stest=test\\s\\[\(source)\\]\\s\(testString)$"
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).range(of: pattern, options: .regularExpression) != nil
@@ -704,7 +882,7 @@ class LoggingTest: XCTestCase {
func testStreamLogHandlerOutputFormatWithOrderedMetadata() {
let interceptStream = InterceptStream()
let label = "testLabel"
LoggingSystem.bootstrapInternal { _ in
LoggingSystem.bootstrapInternal { label in
StreamLogHandler(label: label, stream: interceptStream)
}
let log = Logger(label: label)
@@ -719,8 +897,42 @@ class LoggingTest: XCTestCase {
return
}
XCTAssert(interceptStream.strings[0].contains("a=a0 b=b0"))
XCTAssert(interceptStream.strings[1].contains("a=a1 b=b1"))
XCTAssert(interceptStream.strings[0].contains("a=a0 b=b0"), "LINES: \(interceptStream.strings[0])")
XCTAssert(interceptStream.strings[1].contains("a=a1 b=b1"), "LINES: \(interceptStream.strings[1])")
}
func testStreamLogHandlerWritesIncludeMetadataProviderMetadata() {
let interceptStream = InterceptStream()
LoggingSystem.bootstrapInternal({ _, metadataProvider in
StreamLogHandler(label: "test", stream: interceptStream, metadataProvider: metadataProvider)
}, metadataProvider: .exampleMetadataProvider)
let log = Logger(label: "test")
let testString = "my message is better than yours"
log.critical("\(testString)")
let messageSucceeded = interceptStream.interceptedText?.trimmingCharacters(in: .whitespacesAndNewlines).hasSuffix(testString)
XCTAssertTrue(messageSucceeded ?? false)
XCTAssertEqual(interceptStream.strings.count, 1)
let message = interceptStream.strings.first!
XCTAssertTrue(message.contains("example=example-value"), "message must contain metadata, was: \(message)")
}
func testStdioOutputStreamWrite() {
self.withWriteReadFDsAndReadBuffer { writeFD, readFD, readBuffer in
let logStream = StdioOutputStream(file: writeFD, flushMode: .always)
LoggingSystem.bootstrapInternal { StreamLogHandler(label: $0, stream: logStream) }
let log = Logger(label: "test")
let testString = "hello\u{0} world"
log.critical("\(testString)")
let size = read(readFD, readBuffer, 256)
let output = String(decoding: UnsafeRawBufferPointer(start: UnsafeRawPointer(readBuffer), count: numericCast(size)), as: UTF8.self)
let messageSucceeded = output.trimmingCharacters(in: .whitespacesAndNewlines).hasSuffix(testString)
XCTAssertTrue(messageSucceeded)
}
}
func testStdioOutputStreamFlush() {
@@ -752,12 +964,19 @@ class LoggingTest: XCTestCase {
}
}
func withWriteReadFDsAndReadBuffer(_ body: (UnsafeMutablePointer<FILE>, CInt, UnsafeMutablePointer<Int8>) -> Void) {
func withWriteReadFDsAndReadBuffer(_ body: (CFilePointer, CInt, UnsafeMutablePointer<Int8>) -> Void) {
var fds: [Int32] = [-1, -1]
#if os(Windows)
fds.withUnsafeMutableBufferPointer {
let err = _pipe($0.baseAddress, 256, _O_BINARY)
XCTAssertEqual(err, 0, "_pipe failed \(err)")
}
#else
fds.withUnsafeMutableBufferPointer { ptr in
let err = pipe(ptr.baseAddress!)
XCTAssertEqual(err, 0, "pipe faild \(err)")
XCTAssertEqual(err, 0, "pipe failed \(err)")
}
#endif
let writeFD = fdopen(fds[1], "w")
let writeBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
@@ -767,11 +986,20 @@ class LoggingTest: XCTestCase {
}
var err = setvbuf(writeFD, writeBuffer, _IOFBF, 256)
XCTAssertEqual(err, 0, "setvbuf faild \(err)")
XCTAssertEqual(err, 0, "setvbuf failed \(err)")
let readFD = fds[0]
#if os(Windows)
let hPipe: HANDLE = HANDLE(bitPattern: _get_osfhandle(readFD))!
XCTAssertFalse(hPipe == INVALID_HANDLE_VALUE)
var dwMode: DWORD = DWORD(PIPE_NOWAIT)
let bSucceeded = SetNamedPipeHandleState(hPipe, &dwMode, nil, nil)
XCTAssertTrue(bSucceeded)
#else
err = fcntl(readFD, F_SETFL, fcntl(readFD, F_GETFL) | O_NONBLOCK)
XCTAssertEqual(err, 0, "fcntl faild \(err)")
XCTAssertEqual(err, 0, "fcntl failed \(err)")
#endif
let readBuffer = UnsafeMutablePointer<Int8>.allocate(capacity: 256)
defer {
@@ -801,12 +1029,67 @@ class LoggingTest: XCTestCase {
logging.history.assertExist(level: .error, message: "errorDescription")
}
func testCompileInitializeStandardStreamLogHandlersWithMetadataProviders() {
// avoid "unreachable code" warnings
let dontExecute = Int.random(in: 100 ... 200) == 1
guard dontExecute else {
return
}
// default usage
LoggingSystem.bootstrap(StreamLogHandler.standardOutput)
LoggingSystem.bootstrap(StreamLogHandler.standardError)
// with metadata handler, explicitly, public api
LoggingSystem.bootstrap({ label, metadataProvider in
StreamLogHandler.standardOutput(label: label, metadataProvider: metadataProvider)
}, metadataProvider: .exampleMetadataProvider)
LoggingSystem.bootstrap({ label, metadataProvider in
StreamLogHandler.standardError(label: label, metadataProvider: metadataProvider)
}, metadataProvider: .exampleMetadataProvider)
// with metadata handler, still pretty
LoggingSystem.bootstrap(StreamLogHandler.standardOutput, metadataProvider: .exampleMetadataProvider)
LoggingSystem.bootstrap(StreamLogHandler.standardError, metadataProvider: .exampleMetadataProvider)
}
}
extension Logger {
#if compiler(>=5.3)
public func error(error: Error,
metadata: @autoclosure () -> Logger.Metadata? = nil,
file: String = #fileID, function: String = #function, line: UInt = #line) {
self.error("\(error.localizedDescription)", metadata: metadata(), file: file, function: function, line: line)
}
#else
public func error(error: Error,
metadata: @autoclosure () -> Logger.Metadata? = nil,
file: String = #file, function: String = #function, line: UInt = #line) {
self.error("\(error.localizedDescription)", metadata: metadata(), file: file, function: function, line: line)
}
#endif
}
extension Logger.MetadataProvider {
static var exampleMetadataProvider: Self {
.init { ["example": .string("example-value")] }
}
static func constant(_ metadata: Logger.Metadata) -> Self {
.init { metadata }
}
}
// Sendable
#if compiler(>=5.6)
// used to test logging metadata which requires Sendable conformance
// @unchecked Sendable since manages it own state
extension LoggingTest.LazyMetadataBox: @unchecked Sendable {}
// used to test logging stream which requires Sendable conformance
// @unchecked Sendable since manages it own state
extension LoggingTest.InterceptStream: @unchecked Sendable {}
#endif
@@ -0,0 +1,33 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//
// MetadataProviderTest+XCTest.swift
//
import XCTest
///
/// NOTE: This file was generated by generate_linux_tests.rb
///
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
///
extension MetadataProviderTest {
static var allTests: [(String, (MetadataProviderTest) -> () throws -> Void)] {
return [
("testLoggingMergesOneOffMetadataWithProvidedMetadataFromExplicitlyPassed", testLoggingMergesOneOffMetadataWithProvidedMetadataFromExplicitlyPassed),
("testLogHandlerThatDidNotImplementProvidersButSomeoneAttemptsToSetOneOnIt", testLogHandlerThatDidNotImplementProvidersButSomeoneAttemptsToSetOneOnIt),
("testLogHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt", testLogHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt),
]
}
}
@@ -0,0 +1,143 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
@testable import Logging
import XCTest
#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS)
import Darwin
#elseif os(Windows)
import WinSDK
#else
import Glibc
#endif
final class MetadataProviderTest: XCTestCase {
func testLoggingMergesOneOffMetadataWithProvidedMetadataFromExplicitlyPassed() throws {
let logging = TestLogging()
LoggingSystem.bootstrapInternal(logging.makeWithMetadataProvider,
metadataProvider: .init { ["common": "initial"]
})
let logger = Logger(label: #function, metadataProvider: .init {
[
"common": "provider",
"provider": "42",
]
})
logger.log(level: .info, "test", metadata: ["one-off": "42", "common": "one-off"])
logging.history.assertExist(level: .info,
message: "test",
metadata: ["common": "one-off", "one-off": "42", "provider": "42"])
}
func testLogHandlerThatDidNotImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
#if DEBUG
// we only emit these warnings in debug mode
let logging = TestLogging()
var handler = LogHandlerThatDidNotImplementMetadataProviders(testLogging: logging)
handler.metadataProvider = .simpleTestProvider
logging.history.assertExist(level: .warning, message: "Attempted to set metadataProvider on LogHandlerThatDidNotImplementMetadataProviders that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.", source: "Logging")
let countBefore = logging.history.entries.count
handler.metadataProvider = .simpleTestProvider
XCTAssertEqual(countBefore, logging.history.entries.count, "Should only log the warning once")
#endif
}
func testLogHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
#if DEBUG
// we only emit these warnings in debug mode
let logging = TestLogging()
var handler = LogHandlerThatDidImplementMetadataProviders(testLogging: logging)
handler.metadataProvider = .simpleTestProvider
logging.history.assertNotExist(level: .warning, message: "Attempted to set metadataProvider on LogHandlerThatDidImplementMetadataProviders that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.", source: "Logging")
#endif
}
}
extension Logger.MetadataProvider {
static var simpleTestProvider: Logger.MetadataProvider {
return Logger.MetadataProvider {
return ["test": "provided"]
}
}
}
public struct LogHandlerThatDidNotImplementMetadataProviders: LogHandler {
let testLogging: TestLogging
init(testLogging: TestLogging) {
self.testLogging = testLogging
}
public subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
get {
return nil
}
set(newValue) {
// ignore
}
}
public var metadata: Logging.Logger.Metadata = [:]
public var logLevel: Logging.Logger.Level = .trace
public func log(level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt) {
self.testLogging.make(label: "fake").log(level: level, message: message, metadata: metadata, source: source, file: file, function: function, line: line)
}
}
public struct LogHandlerThatDidImplementMetadataProviders: LogHandler {
let testLogging: TestLogging
init(testLogging: TestLogging) {
self.testLogging = testLogging
}
public subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
get {
return nil
}
set(newValue) {
// ignore
}
}
public var metadata: Logging.Logger.Metadata = [:]
public var logLevel: Logging.Logger.Level = .trace
public var metadataProvider: Logger.MetadataProvider?
public func log(level: Logger.Level,
message: Logger.Message,
metadata: Logger.Metadata?,
source: String,
file: String,
function: String,
line: UInt) {
self.testLogging.make(label: "fake").log(level: level, message: message, metadata: metadata, source: source, file: file, function: function, line: line)
}
}
@@ -0,0 +1,25 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift Logging API project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Logging
internal func emitLogMessage(_ message: Logger.Message, to logger: Logger) {
logger.trace(message)
logger.debug(message)
logger.info(message)
logger.notice(message)
logger.warning(message)
logger.error(message)
logger.critical(message)
}
+125 -23
View File
@@ -14,13 +14,30 @@
import Foundation
@testable import Logging
import XCTest
#if os(Windows)
import WinSDK
#endif
internal struct TestLogging {
private let _config = Config() // shared among loggers
private let recorder = Recorder() // shared among loggers
func make(label: String) -> LogHandler {
return TestLogHandler(label: label, config: self.config, recorder: self.recorder)
return TestLogHandler(
label: label,
config: self.config,
recorder: self.recorder,
metadataProvider: LoggingSystem.metadataProvider
)
}
func makeWithMetadataProvider(label: String, metadataProvider: Logger.MetadataProvider?) -> LogHandler {
return TestLogHandler(
label: label,
config: self.config,
recorder: self.recorder,
metadataProvider: metadataProvider
)
}
var config: Config { return self._config }
@@ -28,23 +45,48 @@ internal struct TestLogging {
}
internal struct TestLogHandler: LogHandler {
private let logLevelLock = NSLock()
private let metadataLock = NSLock()
private let recorder: Recorder
private let config: Config
private var logger: Logger // the actual logger
let label: String
public var metadataProvider: Logger.MetadataProvider?
init(label: String, config: Config, recorder: Recorder, metadataProvider: Logger.MetadataProvider?) {
self.label = label
self.config = config
self.recorder = recorder
self.logger = Logger(label: "test", StreamLogHandler.standardOutput(label: label))
self.logger.logLevel = .debug
self.metadataProvider = metadataProvider
}
init(label: String, config: Config, recorder: Recorder) {
self.label = label
self.config = config
self.recorder = recorder
self.logger = Logger(label: "test", StreamLogHandler.standardOutput(label: label))
self.logger.logLevel = .debug
self.metadataProvider = LoggingSystem.metadataProvider
}
func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt) {
let metadata = (self._metadataSet ? self.metadata : MDC.global.metadata).merging(metadata ?? [:], uniquingKeysWith: { _, new in new })
func log(level: Logger.Level,
message: Logger.Message,
metadata explicitMetadata: Logger.Metadata?,
source: String,
file: String, function: String, line: UInt) {
// baseline metadata, that was set on handler:
var metadata = self._metadataSet ? self.metadata : MDC.global.metadata
// contextual metadata, e.g. from task-locals:
let contextualMetadata = self.metadataProvider?.get() ?? [:]
if !contextualMetadata.isEmpty {
metadata.merge(contextualMetadata, uniquingKeysWith: { _, contextual in contextual })
}
// override using any explicit metadata passed for this log statement:
if let explicitMetadata = explicitMetadata {
metadata.merge(explicitMetadata, uniquingKeysWith: { _, explicit in explicit })
}
self.logger.log(level: level, message, metadata: metadata, source: source, file: file, function: function, line: line)
self.recorder.record(level: level, metadata: metadata, message: message, source: source)
}
@@ -53,10 +95,10 @@ internal struct TestLogHandler: LogHandler {
var logLevel: Logger.Level {
get {
// get from config unless set
return self.logLevelLock.withLock { self._logLevel } ?? self.config.get(key: self.label)
return self._logLevel ?? self.config.get(key: self.label)
}
set {
self.logLevelLock.withLock { self._logLevel = newValue }
self._logLevel = newValue
}
}
@@ -69,26 +111,20 @@ internal struct TestLogHandler: LogHandler {
public var metadata: Logger.Metadata {
get {
// return self.logger.metadata
return self.metadataLock.withLock { self._metadata }
return self._metadata
}
set {
// self.logger.metadata = newValue
self.metadataLock.withLock { self._metadata = newValue }
self._metadata = newValue
}
}
// TODO: would be nice to delegate to local copy of logger but StdoutLogger is a reference type. why?
subscript(metadataKey metadataKey: Logger.Metadata.Key) -> Logger.Metadata.Value? {
get {
// return self.logger[metadataKey: metadataKey]
return self.metadataLock.withLock { self._metadata[metadataKey] }
return self._metadata[metadataKey]
}
set {
// return logger[metadataKey: metadataKey] = newValue
self.metadataLock.withLock {
self._metadata[metadataKey] = newValue
}
self._metadata[metadataKey] = newValue
}
}
}
@@ -174,6 +210,34 @@ internal struct LogEntry {
}
extension History {
#if compiler(>=5.3)
func assertExist(level: Logger.Level,
message: String,
metadata: Logger.Metadata? = nil,
source: String? = nil,
file: StaticString = #file,
fileID: String = #fileID,
line: UInt = #line) {
let source = source ?? Logger.currentModule(fileID: "\(fileID)")
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
XCTAssertNotNil(entry, "entry not found: \(level), \(source), \(String(describing: metadata)), \(message)",
file: file, line: line)
}
func assertNotExist(level: Logger.Level,
message: String,
metadata: Logger.Metadata? = nil,
source: String? = nil,
file: StaticString = #file,
fileID: String = #file,
line: UInt = #line) {
let source = source ?? Logger.currentModule(fileID: "\(fileID)")
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
XCTAssertNil(entry, "entry was found: \(level), \(source), \(String(describing: metadata)), \(message)",
file: file, line: line)
}
#else
func assertExist(level: Logger.Level,
message: String,
metadata: Logger.Metadata? = nil,
@@ -183,7 +247,7 @@ extension History {
let source = source ?? Logger.currentModule(filePath: "\(file)")
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
XCTAssertNotNil(entry, "entry not found: \(level), \(source), \(String(describing: metadata)), \(message)",
file: (file), line: line)
file: file, line: line)
}
func assertNotExist(level: Logger.Level,
@@ -195,15 +259,42 @@ extension History {
let source = source ?? Logger.currentModule(filePath: "\(file)")
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
XCTAssertNil(entry, "entry was found: \(level), \(source), \(String(describing: metadata)), \(message)",
file: (file), line: line)
file: file, line: line)
}
#endif
func find(level: Logger.Level, message: String, metadata: Logger.Metadata? = nil, source: String) -> LogEntry? {
return self.entries.first { entry in
entry.level == level &&
entry.message == message &&
entry.metadata ?? [:] == metadata ?? [:] &&
entry.source == source
if entry.level != level {
return false
}
if entry.message != message {
return false
}
if let lhs = entry.metadata, let rhs = metadata {
if lhs.count != rhs.count {
return false
}
for lk in lhs.keys {
if lhs[lk] != rhs[lk] {
return false
}
}
for rk in rhs.keys {
if lhs[rk] != rhs[rk] {
return false
}
}
return true
}
if entry.source != source {
return false
}
return true
}
}
}
@@ -270,6 +361,8 @@ public class MDC {
private var threadId: Int {
#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS)
return Int(pthread_mach_thread_np(pthread_self()))
#elseif os(Windows)
return Int(GetCurrentThreadId())
#else
return Int(pthread_self())
#endif
@@ -308,3 +401,12 @@ internal struct TestLibrary {
}
}
}
// Sendable
#if compiler(>=5.6)
extension TestLogHandler: @unchecked Sendable {}
extension Recorder: @unchecked Sendable {}
extension Config: @unchecked Sendable {}
extension MDC: @unchecked Sendable {}
#endif
+43
View File
@@ -0,0 +1,43 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Logging API open source project
//
// Copyright (c) 2022 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 Dispatch
@testable import Logging
import XCTest
class SendableTest: XCTestCase {
#if compiler(>=5.6)
func testSendableLogger() async {
let testLogging = TestLogging()
LoggingSystem.bootstrapInternal(testLogging.make)
let logger = Logger(label: "test")
let message1 = Logger.Message(stringLiteral: "critical 1")
let message2 = Logger.Message(stringLiteral: "critical 2")
let metadata: Logger.Metadata = ["key": "value"]
let task = Task.detached {
logger.info("info")
logger.critical(message1)
logger.critical(message2)
logger.warning(.init(stringLiteral: "warning"), metadata: metadata)
}
await task.value
testLogging.history.assertExist(level: .info, message: "info", metadata: [:])
testLogging.history.assertExist(level: .critical, message: "critical 1", metadata: [:])
testLogging.history.assertExist(level: .critical, message: "critical 2", metadata: [:])
testLogging.history.assertExist(level: .warning, message: "warning", metadata: metadata)
}
#endif
}
+2 -3
View File
@@ -18,10 +18,9 @@ RUN apt-get update && apt-get install -y lsof dnsutils netcat-openbsd net-tools
# ruby and jazzy for docs generation
RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev build-essential
# switch of gem docs building
RUN echo "gem: --no-document" > ~/.gemrc
# jazzy no longer works on xenial as ruby is too old.
RUN if [ "${ubuntu_version}" != "xenial" ] ; then gem install jazzy; fi
RUN if [ "${ubuntu_version}" = "focal" ] ; then echo "gem: --no-document" > ~/.gemrc; fi
RUN if [ "${ubuntu_version}" = "focal" ] ; then gem install jazzy; fi
# tools
RUN mkdir -p $HOME/.tools
+2 -1
View File
@@ -6,7 +6,8 @@ services:
image: swift-log:20.04-5.4
build:
args:
base_image: "swiftlang/swift:nightly-5.4-focal"
ubuntu_version: "focal"
swift_version: "5.4"
test:
image: swift-log:20.04-5.4
+19
View File
@@ -0,0 +1,19 @@
version: "3"
services:
runtime-setup:
image: swift-log:20.04-5.5
build:
args:
ubuntu_version: "focal"
swift_version: "5.5"
test:
image: swift-log:20.04-5.5
environment:
- FORCE_TEST_DISCOVERY=--enable-test-discovery
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:20.04-5.5
+19
View File
@@ -0,0 +1,19 @@
version: "3"
services:
runtime-setup:
image: swift-log:20.04-5.6
build:
args:
ubuntu_version: "focal"
swift_version: "5.6"
test:
image: swift-log:20.04-5.6
environment:
- FORCE_TEST_DISCOVERY=--enable-test-discovery
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:20.04-5.6
+19
View File
@@ -0,0 +1,19 @@
version: "3"
services:
runtime-setup:
image: swift-log:20.04-5.7
build:
args:
ubuntu_version: "focal"
swift_version: "5.7"
test:
image: swift-log:20.04-5.7
environment:
- FORCE_TEST_DISCOVERY=--enable-test-discovery
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:20.04-5.7
+18
View File
@@ -0,0 +1,18 @@
version: "3"
services:
runtime-setup:
image: swift-log:20.04-5.8
build:
args:
base_image: "swiftlang/swift:nightly-5.8-focal"
test:
image: swift-log:20.04-5.8
environment:
- FORCE_TEST_DISCOVERY=--enable-test-discovery
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:20.04-5.8
-17
View File
@@ -1,17 +0,0 @@
version: "3"
services:
runtime-setup:
image: swift-log:20.04-main
build:
args:
base_image: "swiftlang/swift:nightly-main-focal"
test:
image: swift-log:20.04-main
environment: []
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:20.04-main
+18
View File
@@ -0,0 +1,18 @@
version: "3"
services:
runtime-setup:
image: swift-log:22.04-main
build:
args:
base_image: "swiftlang/swift:nightly-main-jammy"
test:
image: swift-log:22.04-main
environment:
- FORCE_TEST_DISCOVERY=--enable-test-discovery
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:22.04-main
+2 -2
View File
@@ -28,10 +28,10 @@ services:
test:
<<: *common
command: /bin/bash -xcl "swift test -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"
command: /bin/bash -xcl "swift test -Xswiftc -warnings-as-errors $${FORCE_TEST_DISCOVERY-} $${SANITIZER_ARG-}"
# util
shell:
<<: *common
entrypoint: /bin/bash
entrypoint: /bin/bash -l
+328
View File
@@ -0,0 +1,328 @@
# Metadata Providers
Authors: [Moritz Lang](https://github.com/slashmo), [Konrad 'ktoso' Malawski](https://github.com/ktoso)
## Introduction
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.
## 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.
Most notably, loggers should participate in tracing by including some trace metadata (such as e.g. a `trace-id`) when logging, as it transparently enables developers to benefit from log correlation using those IDs.
Today, the only supported way of providing such metadata is to pass them along to each log call explicitly:
```swift
logger.info("first this ...", metadata: ["trace-id": MyTracingLibrary.currentTraceID])
logger.info("... now this", metadata: ["trace-id": MyTracingLibrary.currentTraceID])
```
This comes with a couple of downsides:
### Error-prone and repetitive
It's easy to forget passing this metadata to _all_ log statements, resulting in an inconsistent debugging experience as these log statements cannot be found using correlation IDs.
The repetitiveness and verboseness of logging multiple metadata in-line quickly becomes annoying and vastly decreases the signal-to-noise ratio of Swift code trying to be a good citizen and making use of log correlation techniques such as distributed tracing.
### Impossible to implement for libraries
A large portion of logs are not generated by the end-user but by libraries such as AsyncHTTPClient, Vapor etc.
These libraries, by design, don't know about the specific metadata keys that should be included in the logs.
Those keys are after all runtime dependent, and may change depending on what tracing system is configured by the end user.
For example, a specific `Tracer` implementation would use a type representing a trace ID, and has a way of extracting
that trace ID from a [Swift Distributed Tracing Baggage](https://github.com/apple/swift-distributed-tracing-baggage). But other libraries can't know about this _specific_ trace ID and therefore would not be
able to pass such values along to their log statements.
## Proposed solution
To support this kind of runtime-generated metadata in `swift-log`, we need to extend the logging APIs in an open-ended way, to allow any kinds of metadata to be provided from the asynchronous context (i.e. task local values).
We also have a desire to keep `swift-log` a "zero dependencies" library, as it intends only to focus on describing a logging API, and not incur any additional dependencies, so it can be used in the most minimal of projects.
To solve this, we propose the extension of swift-log APIs with a new concept: _metadata providers_.
`MetadataProvider` is a struct nested in the `Logger` type, sitting alongside `MetadataValue` and the `Metadata`.
Its purpose is to _provide_ `Logger.Metadata` from the asynchronous context, by e.g. looking up various task-local values,
and converting them into `Logger.Metadata`. This is performed by calling the `get()` function, like so:
```swift
extension Logger {
public struct MetadataProvider: Sendable {
// ...
public init(_ provideMetadata: @escaping @Sendable () -> Metadata)
public get() -> Metadata
}
}
```
### Defining a `MetadataProvider`
While `MetadataProvider`s can be created in an ad-hoc fashion, the struct may be used as a namespace
to define providers in.
For example, a `MyTracer` implementation of swift-distributed-tracing would be expected to provide a metadata provider
that is aware of its own `Baggage` and specific keys it uses to carry the trace and span identifiers, like this:
```swift
import Tracing // swift-distributed-tracing
extension Logger.MetadataProvider {
static let myTracer = Logger.MetadataProvider {
guard let baggage = Baggage.current else {
return [:]
}
guard let spanContext = baggage.spanContext else {
return [:]
}
return [
"traceID": "\(spanContext.traceID)",
"spanID": "\(spanContext.spanID)",
]
}
}
```
### Using a `MetadataProvider`
A `MetadataProvider` can be set up either globally, on a boot-strapped logging system:
```swift
LoggingSystem.bootstrap(
metadataProvider: .myTracer,
StreamLogHandler.standardOutput
)
```
or, using the metadata provider specific bootstrap method:
```swift
LoggingSystem.bootstrapMetadataProvider(.myTracer)
```
It is also possible to configure a metadata provider on a per-logger basis, like this:
```swift
let logger = Logger(label: "example", metadataProvider: Logger.MetadataProvider {
guard let baggage = Baggage.current else {
return [:]
}
guard let operationID = baggage.operationID else {
return nil
}
return ["extra/opID": "\(opID)"]
})
```
which _overrides_ the default bootstrapped metadata provider.
> NOTE: Setting the metadata provider on the logger directly means the `LoggingSystem` metadata provider
> is skipped (if defined), following how an explicitly passed handler `factory`
> overrides the `LoggingSystem`s `factory`.
Once a metadata provider was set up, when a log statement is about to be emitted, the log handler implementation shall
invoke it whenever it is about to emit a log statement. This must be done from the same asynchronous context as the log statement
was made; I.e. if a log handler were to asynchronously–in a _detached_ task–create the actual log message, the invocation of
the metadata provider still _must_ be performed before passing the data over to the other detached task.
Usually, metadata providers will reach for the task's Swift Distributed Tracing [`Baggage`](https://github.com/apple/swift-distributed-tracing-baggage) which is the mechanism that swift-distributed-tracing
and instrumentation libraries use to propagate metadata across asynchronous, as well as process, boundaries. Handlers
may also inspect other task-local values, however they should not expect other libraries to be able to propagage those
as well as they will propagate `Baggage` values.
Those metadata will then be included in the log statement, e.g. like this:
```swift
var baggage = Baggage.topLevel
baggage.spanContext = SpanContext()
Baggage.withValue(baggage) {
test()
}
func test() {
log.info("Test", metadata: ["oneOff": "42"])
// info [traceID: abc, spanID: 123, onOff: 42] Test
}
```
### Multiple `MetadataProvider`s using `MetadataProvider.multiplex(_:)`
Borrowing the concept from log handlers, metadata providers also have a multiplexing implementation.
It is defined as an extension on `MetadataProvider` and is useful in cases where users want to utilize
more than one metadata provider at the same time:
```swift
extension Logger.MetadataProvider {
public static func multiplex(_ providers: [Logger.MetadataProvider]) -> Logger.MetadataProvider {
precondition(!providers.isEmpty, "providers MUST NOT be empty")
return Logger.MetadataProvider { baggage in
providers.reduce(into: nil) { metadata, provider in
if let providedMetadata = provider.metadata(baggage) {
if metadata != nil {
metadata!.merge(providedMetadata, uniquingKeysWith: { _, rhs in rhs })
} else {
metadata = providedMetadata
}
}
}
}
}
}
```
Metadata keys are unique, so in case multiple metadata providers return the same key,
the last provider in the array _wins_ and provides the value.
Note that it is possible to query the `LoggingSystem` for the configured, system-wide, metadata provider,
and combine it using a `multiplex` provider if the system-wide provider should not be replaced, but augmented
by additional providers.
### Understanding Swift Distributed Tracing `Baggage`
The `Baggage` type is more than just a fancy type-safe container for your values which are meant to be carried across
using a single, well-known, [task-local value](https://developer.apple.com/documentation/swift/tasklocal).
Values stored in `Baggage` are intended to be carried _across process boundaries_, and e.g. libraries such as HTTP clients,
or other RPC mechanisms, or even messaging systems implement distributed tracing [instruments](https://github.com/apple/swift-distributed-tracing/blob/main/Sources/Instrumentation/Instrument.swift)
which `inject` and `extract` baggage values into their respective carrier objects, e.g. an `HTTPRequest` in the case of an HTTP client.
In other words, whenever intending to propagate information _across processes_ utilize the `Baggage` type to carry it,
and ensure to provide an `Instrument` that is able to inject/extract the values of interest into the carrier types you are interested in.
To learn more about baggage and instrumentation, refer to the [Swift Distributed Tracing](https://github.com/apple/swift-distributed-tracing/) library documentation.
#### When to use `Baggage` vs. `Logger[metadataKey:]`
While `Baggage` is context-dependent and changes depending on where the log methods are being called from, the metadata set on a `Logger` is static and not context-dependent. E.g, if you wanted to add things like an instance ID or a subsystem name to a `Logger`, that could be seen as static information and set via `Logger[metadataKey:]`.
```swift
var logger = Logger(label: "org.swift.my-service")
logger[metadataKey: "instanceId"] = "123"
logger.info("Service started.")
// [instanceId: 123] Service started.
```
On the other hand, things like a trace ID are dynamic and context-dependent, therefore would be obtained via `Baggage`:
```swift
logger.info("Product fetched.")
// [traceId: 42] Product fetched.
```
Inline-metadata is suitable for one-offs such as a `productId` or a `paymentMethod` in an online store service, but are not enough to corralate the following log statements, i.e. tying them both to the same request:
```swift
logger.info("Product fetched.", metadata: ["productId": "42"])
logger.info("Product purchased.", metadata: ["paymentMethod": "apple-pay"])
// [productId: 42] Product fetched.
// [paymentMethod: apple-pay] Product fetched.
```
If there was a `Baggage` value with a trace ID surrounding these log statements, they would be automatically correlatable:
```swift
var baggage = Baggage.topLevel
baggage.traceID = 42
Baggage.$current.withValue(baggage) {
logger.info("Product fetched.", metadata: ["productId": "42"])
logger.info("Product purchased.", metadata: ["paymentMethod": "apple-pay"])
}
// [trace-id: 42, productId: 42] Product fetched.
// [trace-id: 42, paymentMethod: apple-pay] Product fetched.
```
## Alternatives considered
### MetadataProviders as a function of `Baggage -> Metadata`
This was considered and fully developed, however it would cause swift-log to have a dependency on the instrumentation type `Baggage`,
which was seen as in-conflict-with the interest of swift-log remaining a zero-dependency library.
`Baggage` _is_ the well known type that is intended to be used for any kind of distributed systems instrumentation and tracing,
however it adds additional complexity and confusion for users who are not interested in this domain. For example, developers
may be confused about why `Baggage` and `Logger.Metadata` look somewhat similar, but behave very differently. This complexity
is inherent to the two types actually being _very_ different, however we do not want to overwhelm newcomers or developers
who are only intending to use swift-log within process. Such developers do not need to care about the added complexities
of distributed systems.
The tradeoff we take here is that every metadata provider will have to perform its own task-local (and therefore also thread-local),
access in order to obtain the `Baggage` value, rather than the lookup being able to be performed _once_ and shared between
multiple providers when a multiplex provider was configured in the system. We view this tradeoff as worth taking, as the cost
of actually formatting the metadata usually strongly dominates the cost of the task-local lookup.
### Removing `LogHandler.Metadata` in favor of `Baggage`
Removing logger metadata is not a good option because it serves a slightly different style of metadata than the baggage.
Baggage is intended for contextual, task-local, metadata which is _carried across multiple libraries_. The values stored in baggage are well-typed, and must declare keys for accessing values in a baggage, this works well for multiple pieces of an application needing to reach for specific baggage items: everyone aware of the `traceID` key, is able to query the baggage for this key (`baggage.traceID`) and obtain a well-typed value. This comes with a higher cost on declaring keys though, as well as a global namespace for those - which is desirable for such kinds of metadata.
This is not the same usage pattern as emitting a plain structured log where we'd like to include the name of an item we just queried:
```swift
log.info("Obtained item! Hooray!", metadata: ["item": "\(item)"])
```
In this example, the key/value pair for `"item"` is pretty ad-hoc, and we never need to refer to it elsewhere in the program. It never is queried by other pieces of the application, nor would it be useful to set it in baggage metadata, as the only purpose of the `item` key here is to log, and forget about it.
### Explicitly passing `Baggage` always
Baggage is designed for use cases like distributed tracing, or similar instrumentation patterns where "all" participating code may need to reach for it.
Specifically in logging, this means that _every_ call site for _every_ log statement would have to pass it explicitly resulting in annoying noisy code:
```swift
class StoresRepository {
func store(byID id: String, eventLoop: EventLoop, logger: Logger, baggage: Baggage) async throws -> Store {
InstrumentationSystem.tracer.withSpan("Fetch Store") { span in
logger.info("Fetched store.", baggage: span.baggage)
}
}
}
try await storesRepository.store(
byID: storeID,
eventLoop: eventLoop,
logger: logger,
baggage: baggage
)
```
### Explicitly passing `Logger` always
Imagine we don't have metadata providers, we'd have to manually set trace IDs on loggers which doesn't really work as all libraries involved would need to know about the same specific trace ID. Even if we inverted the dependency to have `Tracing` depend on `Logging` so that we'd be able to define something like "Tracing, please populate this logger with metadata", we'd have to make sure this thing is called in all places to avoid dropping contextual metadata.
```swift
import Tracing
import Logging
let contextualLogger = InstrumentationSystem.tracer.populateTraceMetadata(logger)
contextualLogger.info("Request received.")
```
### Tracing providing extensions on Logger
Instead of having `swift-log` depend on `swift-distributed-tracing-baggage` we could also create extensions for `Logger` inside `swift-distributed-tracing` and have users call these new overloaded methods instead:
```swift
extension Logger {
func tinfo(_ message: ..., baggage: Baggage?) {
// ...
}
}
```
Such extensions could work like the currently-proposed APIs, but the risk of users calling the wrong methods is incredibly high and we cannot overload the existing methods' signatures because of ambiguity of call-sides without explicit Baggage being passed:
```swift
logger.info("Hello")
// we want this to pick up Baggage, but the signature would be ambiguous
```
Also, this extension-based contextual metadata would require basically everyone in Server-side Swift to adapt their usage of `Logging` to use these extensions instead. With the proposed APIs, we'd only need to modify `Logging` and any NIO-based libraries such as `AsyncHTTPClient`, `Vapor`, etc. and not every single log statement in every application.
+4 -4
View File
@@ -26,20 +26,20 @@ if [[ "$(uname -s)" == "Linux" ]]; then
swift build
fi
# setup source-kitten if required
source_kitten_source_path="$root_path/.SourceKitten"
mkdir -p "$root_path/.build/sourcekitten"
source_kitten_source_path="$root_path/.build/sourcekitten/source"
if [[ ! -d "$source_kitten_source_path" ]]; then
git clone https://github.com/jpsim/SourceKitten.git "$source_kitten_source_path"
fi
source_kitten_path="$source_kitten_source_path/.build/x86_64-unknown-linux/debug"
source_kitten_path="$source_kitten_source_path/.build/debug"
if [[ ! -d "$source_kitten_path" ]]; then
rm -rf "$source_kitten_source_path/.swift-version"
cd "$source_kitten_source_path" && swift build && cd "$root_path"
fi
# generate
mkdir -p "$root_path/.build/sourcekitten"
for module in "${modules[@]}"; do
if [[ ! -f "$root_path/.build/sourcekitten/$module.json" ]]; then
"$source_kitten_path/sourcekitten" doc --spm-module $module > "$root_path/.build/sourcekitten/$module.json"
"$source_kitten_path/sourcekitten" doc --spm --module-name $module > "$root_path/.build/sourcekitten/$module.json"
fi
done
fi
+1 -1
View File
@@ -94,7 +94,7 @@ def createLinuxMain(testsDirectory, allTestSubDirectories, files)
file.write header(fileName)
file.write "\n"
file.write "#if os(Linux) || os(FreeBSD)\n"
file.write "#if os(Linux) || os(FreeBSD) || os(Windows) || os(Android)\n"
for testSubDirectory in allTestSubDirectories.sort { |x, y| x <=> y }
file.write '@testable import ' + testSubDirectory + "\n"
end
+16
View File
@@ -0,0 +1,16 @@
#!/bin/bash
##===----------------------------------------------------------------------===##
##
## 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.md for the list of Swift Logging API project authors
##
## SPDX-License-Identifier: Apache-2.0
##
##===----------------------------------------------------------------------===##
swift package --disable-sandbox preview-documentation --target Logging
+2 -2
View File
@@ -32,7 +32,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
function replace_acceptable_years() {
# this needs to replace all acceptable forms with 'YEARS'
sed -e 's/20[12][78901]-20[12][8901]/YEARS/' -e 's/20[12][8901]/YEARS/'
sed -e 's/20[12][789012]-20[12][89012]/YEARS/' -e 's/20[12][89012]/YEARS/'
}
printf "=> Checking linux tests... "
@@ -86,7 +86,7 @@ for language in swift-or-c bash dtrace; do
matching_files=( -name '*' )
case "$language" in
swift-or-c)
exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h)
exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o name Package-swift5.6.swift -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h)
matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
cat > "$tmp" <<"EOF"
//===----------------------------------------------------------------------===//