mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
bc386b95f2 | ||
|
|
6856e42a3f | ||
|
|
cdaa5ac879 | ||
|
|
b1fa4ef41f | ||
|
|
63eaca6f4d | ||
|
|
f3a82f1119 | ||
|
|
6b380c9f4b | ||
|
|
ca538143e2 | ||
|
|
3612813963 | ||
|
|
95a70b954c | ||
|
|
dea0abb603 | ||
|
|
4121d24dbd | ||
|
|
a90a3d1c37 | ||
|
|
2a4139ef2a | ||
|
|
bd44c73045 | ||
|
|
45b82c6e24 | ||
|
|
1be2c17b80 | ||
|
|
21d132f1ca |
No files matched your search
@@ -1,5 +1,8 @@
|
||||
name: Main
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
@@ -11,27 +14,42 @@ jobs:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
linux_5_9_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_5_10_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_0_enabled: true
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
|
||||
benchmarks:
|
||||
name: Benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks"
|
||||
macos_xcode_16_4_enabled: true
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
static-sdk:
|
||||
name: Static SDK
|
||||
static-linux:
|
||||
name: Static Linux Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
|
||||
|
||||
@@ -40,4 +58,24 @@ jobs:
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
runner_pool: nightly
|
||||
build_scheme: swift-log
|
||||
build_scheme: swift-log-Package
|
||||
swift_test_enabled: true
|
||||
|
||||
wasm:
|
||||
name: Wasm Swift SDK
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
|
||||
android:
|
||||
name: Android Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/android_swift_sdk.yml@main
|
||||
|
||||
release-builds:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_0_enabled: true
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
@@ -1,5 +1,8 @@
|
||||
name: PR
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, reopened, synchronize]
|
||||
@@ -15,27 +18,43 @@ jobs:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
linux_5_9_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_5_10_arguments_override: "--explicit-target-dependency-import-check error"
|
||||
linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_0_enabled: true
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
windows_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
windows_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
|
||||
|
||||
benchmarks:
|
||||
name: Benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks"
|
||||
macos_runner_pool: general
|
||||
macos_xcode_16_4_enabled: true
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
static-sdk:
|
||||
name: Static SDK
|
||||
static-linux:
|
||||
name: Static Linux Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/static_sdk.yml@main
|
||||
|
||||
@@ -44,4 +63,24 @@ jobs:
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
runner_pool: general
|
||||
build_scheme: swift-log
|
||||
build_scheme: swift-log-Package
|
||||
swift_test_enabled: true
|
||||
|
||||
android:
|
||||
name: Android Swift SDK
|
||||
# Workaround https://github.com/nektos/act/issues/1875
|
||||
uses: apple/swift-nio/.github/workflows/android_swift_sdk.yml@main
|
||||
|
||||
release-builds:
|
||||
name: Release builds
|
||||
uses: apple/swift-nio/.github/workflows/release_builds.yml@main
|
||||
with:
|
||||
windows_6_0_enabled: true
|
||||
windows_6_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
|
||||
wasm:
|
||||
name: Wasm Swift SDK
|
||||
uses: apple/swift-nio/.github/workflows/wasm_swift_sdk.yml@main
|
||||
@@ -1,5 +1,8 @@
|
||||
name: PR label
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [labeled, unlabeled, opened, reopened, synchronize]
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
@@ -0,0 +1,78 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Logging
|
||||
|
||||
struct NoOpLogHandler: LogHandler {
|
||||
let label: String
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
init(label: String, metadataProvider: Logger.MetadataProvider?) {
|
||||
self.label = label
|
||||
self.metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
init(label: String) {
|
||||
self.label = label
|
||||
self.metadataProvider = LoggingSystem.metadataProvider
|
||||
}
|
||||
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata explicitMetadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
// Do nothing
|
||||
}
|
||||
|
||||
private var _logLevel: Logger.Level?
|
||||
var logLevel: Logger.Level {
|
||||
get {
|
||||
self._logLevel ?? .debug
|
||||
}
|
||||
set {
|
||||
self._logLevel = newValue
|
||||
}
|
||||
}
|
||||
|
||||
private var _metadataSet = false
|
||||
private var _metadata = Logger.Metadata() {
|
||||
didSet {
|
||||
self._metadataSet = true
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logger.Metadata {
|
||||
get {
|
||||
self._metadata
|
||||
}
|
||||
set {
|
||||
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 {
|
||||
self._metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
self._metadata[metadataKey] = newValue
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Benchmark
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
let benchmarks: @Sendable () -> Void = {
|
||||
let iterations = 1_000_000
|
||||
let metrics: [BenchmarkMetric] = [.instructions, .objectAllocCount]
|
||||
|
||||
// Take a pair of levels to cover all condition ranges between the active level and logged level.
|
||||
let logLevelParameterization: [Logger.Level] = [.debug, .error]
|
||||
for logLevel in logLevelParameterization {
|
||||
for logLevelUsed in logLevelParameterization {
|
||||
var logger = Logger(label: "BenchmarkRunner_\(logLevel)_\(logLevelUsed)")
|
||||
|
||||
// Use a NoOpLogHandler to avoid polluting the logs
|
||||
logger.handler = NoOpLogHandler(label: "NoOpLogHandler")
|
||||
logger.logLevel = logLevel
|
||||
|
||||
Benchmark(
|
||||
"\(logLevelUsed)_log_with_\(logLevel)_log_level",
|
||||
configuration: .init(
|
||||
metrics: metrics,
|
||||
maxIterations: iterations,
|
||||
thresholds: [
|
||||
.instructions: BenchmarkThresholds(
|
||||
relative: [
|
||||
.p90: 1.0 // we only record p90
|
||||
]
|
||||
),
|
||||
.objectAllocCount: BenchmarkThresholds(
|
||||
absolute: [
|
||||
.p90: 0 // we only record p90
|
||||
]
|
||||
),
|
||||
]
|
||||
)
|
||||
) { benchmark in
|
||||
// This is what we actually benchmark
|
||||
logger.log(level: logLevelUsed, "hello, benchmarking world")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
// swift-tools-version: 6.0
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "Benchmarks",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
dependencies: [
|
||||
.package(path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
]
|
||||
)
|
||||
|
||||
// Benchmark of SwiftLogBenchmarks
|
||||
package.targets += [
|
||||
.executableTarget(
|
||||
name: "SwiftLogBenchmarks",
|
||||
dependencies: [
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/SwiftLogBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 3279,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1126,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 3279,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 3279,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 3197,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1045,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 3197,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 3197,
|
||||
"objectAllocCount" : 1
|
||||
}
|
||||
+46
-22
@@ -47,6 +47,8 @@ My system has IPv6 disabled.
|
||||
|
||||
## Writing a Patch
|
||||
|
||||
For non-trivial changes that affect the public API, it is good practice to have a discussion phase before writing code. Please follow the [proposal process](Sources/Logging/Docs.docc/Proposals/Proposals.md) to gather feedback and align on the approach with other contributors.
|
||||
|
||||
A good SwiftLog patch is:
|
||||
|
||||
1. Concise, and contains as few changes as needed to achieve the end result.
|
||||
@@ -62,34 +64,56 @@ We require that your commit messages match our template. The easiest way to do t
|
||||
|
||||
### Make sure Tests work on Linux
|
||||
|
||||
SwiftLog uses XCTest to run tests on both macOS and Linux. While the macOS version of XCTest is able to use the Objective-C runtime to discover tests at execution time, the Linux version is not.
|
||||
For this reason, whenever you add new tests **you have to run a script** that generates the hooks needed to run those tests on Linux, or our CI will complain that the tests are not all present on Linux. To do this, merely execute `ruby ./scripts/generate_linux_tests.rb` at the root of the package and check the changes it made.
|
||||
SwiftLog uses Swift Testing to run tests on all supported platforms.
|
||||
|
||||
### Run `./scripts/soundness.sh`
|
||||
### Run CI checks locally
|
||||
|
||||
The scripts directory contains a [soundness.sh script](https://github.com/apple/swift-log/blob/main/scripts/soundness.sh)
|
||||
that enforces additional checks, like license headers and formatting style.
|
||||
You can run the Github Actions workflows locally using
|
||||
[act](https://github.com/nektos/act). To run all the jobs that run on a pull
|
||||
request, use the following command:
|
||||
|
||||
Please make sure to `./scripts/soundness.sh` before pushing a change upstream, otherwise it is likely the PR validation will fail
|
||||
on minor changes such as a missing `self.` or similar formatting issues.
|
||||
|
||||
> The script also executes the above mentioned `generate_linux_tests.rb`.
|
||||
|
||||
For frequent contributors, we recommend adding the script as a [git pre-push hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), which you can do via executing the following command in the project root directory:
|
||||
|
||||
```bash
|
||||
cat << EOF > .git/hooks/pre-push
|
||||
#!/bin/bash
|
||||
|
||||
if [[ -f "scripts/soundness.sh" ]]; then
|
||||
scripts/soundness.sh
|
||||
fi
|
||||
EOF
|
||||
```
|
||||
% act pull_request
|
||||
```
|
||||
|
||||
Which makes the script execute, and only allow the `git push` to complete if the check has passed.
|
||||
To run just a single job, use `workflow_call -j <job>`, and specify the inputs
|
||||
the job expects. For example, to run just shellcheck:
|
||||
|
||||
```
|
||||
% act workflow_call -j soundness --input shell_check_enabled=true
|
||||
```
|
||||
|
||||
To bind-mount the working directory to the container, rather than a copy, use
|
||||
`--bind`. For example, to run just the formatting, and have the results
|
||||
reflected in your working directory:
|
||||
|
||||
```
|
||||
% act --bind workflow_call -j soundness --input format_check_enabled=true
|
||||
```
|
||||
|
||||
If you'd like `act` to always run with certain flags, these can be be placed in
|
||||
an `.actrc` file either in the current working directory or your home
|
||||
directory, for example:
|
||||
|
||||
```
|
||||
--container-architecture=linux/amd64
|
||||
--remote-name upstream
|
||||
--action-offline-mode
|
||||
```
|
||||
|
||||
## Benchmarks
|
||||
|
||||
Benchmarks for `swift-log` are in a separate Swift Package in the `Benchmarks` subfolder of this repository.
|
||||
They use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin.
|
||||
Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `package-benchmark` to capture memory allocation statistics.
|
||||
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `package-benchmark`.
|
||||
Afterwards you can run the benchmarks from CLI by going to the `Benchmarks` subfolder (e.g. `cd Benchmarks`) and invoking:
|
||||
```
|
||||
swift package benchmark
|
||||
```
|
||||
|
||||
For more information please refer to `swift package benchmark --help` or the [documentation of `package-benchmark`](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark).
|
||||
|
||||
In the case of formatting issues, you can then `git add` the formatting changes, and attempt the push again.
|
||||
|
||||
## How to contribute your work
|
||||
|
||||
|
||||
@@ -26,15 +26,6 @@ components that this product depends on.
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
This product contains a derivation of the Tony Stone's 'process_test_files.rb'.
|
||||
|
||||
* LICENSE (Apache License 2.0):
|
||||
* https://www.apache.org/licenses/LICENSE-2.0
|
||||
* HOMEPAGE:
|
||||
* https://codegists.com/snippet/ruby/generate_xctest_linux_runnerrb_tonystone_ruby
|
||||
|
||||
---
|
||||
|
||||
This product contains a derivation of the lock implementation and various
|
||||
scripts from SwiftNIO.
|
||||
|
||||
|
||||
+11
-2
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version:5.9
|
||||
// swift-tools-version:6.0
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
@@ -18,17 +18,26 @@ import PackageDescription
|
||||
let package = Package(
|
||||
name: "swift-log",
|
||||
products: [
|
||||
.library(name: "Logging", targets: ["Logging"])
|
||||
.library(name: "Logging", targets: ["Logging"]),
|
||||
.library(name: "InMemoryLogging", targets: ["InMemoryLogging"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "Logging",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "InMemoryLogging",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "LoggingTests",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "InMemoryLoggingTests",
|
||||
dependencies: ["InMemoryLogging", "Logging"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
// Import the logging API
|
||||
import Logging
|
||||
|
||||
// Create a logger with a label
|
||||
let logger = Logger(label: "MyLogger")
|
||||
|
||||
// Use it to log messages
|
||||
logger.info("Hello World!")
|
||||
@@ -0,0 +1,132 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Logging
|
||||
|
||||
/// A custom log handler which just collects logs into memory.
|
||||
/// You can then retrieve an array of those log entries.
|
||||
/// Example use cases include testing and buffering.
|
||||
///
|
||||
/// # Usage
|
||||
/// ```swift
|
||||
/// let logHandler = InMemoryLogHandler()
|
||||
/// let logger = Logger(
|
||||
/// label: "MyApp",
|
||||
/// factory: { _ in
|
||||
/// logHandler
|
||||
/// }
|
||||
/// )
|
||||
/// // Use logger to emit some logs
|
||||
/// someFunction(logger: logger)
|
||||
///
|
||||
/// // Retrieve what was logged
|
||||
/// let logEntries = logger.entries
|
||||
/// ```
|
||||
///
|
||||
public struct InMemoryLogHandler: LogHandler {
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
public var logLevel: Logger.Level = .info
|
||||
private let logStore: LogStore
|
||||
|
||||
/// A struct representing a log entry.
|
||||
public struct Entry: Sendable, Equatable {
|
||||
/// The level we logged at.
|
||||
public var level: Logger.Level
|
||||
/// The message which was logged.
|
||||
public var message: Logger.Message
|
||||
/// The metadata which was logged.
|
||||
public var metadata: Logger.Metadata
|
||||
|
||||
public init(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata) {
|
||||
self.level = level
|
||||
self.message = message
|
||||
self.metadata = metadata
|
||||
}
|
||||
}
|
||||
|
||||
private final class LogStore: @unchecked Sendable {
|
||||
private var _entries: [Entry] = []
|
||||
private let lock = Lock()
|
||||
|
||||
fileprivate func append(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata) {
|
||||
self.lock.withLockVoid {
|
||||
self._entries.append(
|
||||
Entry(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
fileprivate func clear() {
|
||||
self.lock.withLockVoid {
|
||||
_entries.removeAll()
|
||||
}
|
||||
}
|
||||
|
||||
var entries: [Entry] {
|
||||
self.lock.withLock { self._entries }
|
||||
}
|
||||
}
|
||||
|
||||
private init(logStore: LogStore) {
|
||||
self.logStore = logStore
|
||||
}
|
||||
|
||||
/// Create a new ``InMemoryLogHandler``.
|
||||
public init() {
|
||||
self.init(logStore: .init())
|
||||
}
|
||||
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
// Start with the metadata provider..
|
||||
var mergedMetadata: Logger.Metadata = self.metadataProvider?.get() ?? [:]
|
||||
// ..merge in self.metadata, overwriting existing keys
|
||||
mergedMetadata = mergedMetadata.merging(self.metadata) { $1 }
|
||||
// ..merge in metadata from this log call, overwriting existing keys
|
||||
mergedMetadata = mergedMetadata.merging(metadata ?? [:]) { $1 }
|
||||
|
||||
self.logStore.append(level: level, message: message, metadata: mergedMetadata)
|
||||
}
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self.metadata[key]
|
||||
}
|
||||
set {
|
||||
self.metadata[key] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
/// All logs that have been collected.
|
||||
public var entries: [Entry] {
|
||||
self.logStore.entries
|
||||
}
|
||||
|
||||
/// Clear all entries.
|
||||
public func clear() {
|
||||
self.logStore.clear()
|
||||
}
|
||||
}
|
||||
@@ -1,7 +1,6 @@
|
||||
# 001: Choosing log levels
|
||||
|
||||
Best practice for selecting appropriate log levels in applications and
|
||||
libraries.
|
||||
Select appropriate log levels in applications and libraries.
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -39,29 +38,30 @@ its logging environment.
|
||||
|
||||
#### For libraries
|
||||
|
||||
Libraries should use **info level or lower** (info, debug, trace). Each level
|
||||
serves different purposes:
|
||||
Libraries should use **info level or less severe** (info, debug, trace).
|
||||
|
||||
Libraries **should not** log information on **warning or more severe levels**,
|
||||
unless it is a one-time (for example during startup) warning, that cannot lead
|
||||
to overwhelming log outputs.
|
||||
|
||||
Each level serves different purposes:
|
||||
|
||||
##### Trace Level
|
||||
- **Usage**: Log everything needed to diagnose hard-to-reproduce bugs
|
||||
- **Performance**: May impact performance; assume it won't be used in production
|
||||
- **Content**: Internal state, detailed operation flows, diagnostic information
|
||||
- **Usage**: Log everything needed to diagnose hard-to-reproduce bugs.
|
||||
- **Performance**: May impact performance; assume it won't be used in production.
|
||||
- **Content**: Internal state, detailed operation flows, diagnostic information.
|
||||
|
||||
##### Debug Level
|
||||
- **Usage**: May be enabled in some production deployments
|
||||
- **Performance**: Should not significantly undermine production performance
|
||||
- **Content**: High-level operation overview, connection events, major decisions
|
||||
- **Usage**: May be enabled in some production deployments.
|
||||
- **Performance**: Should not significantly undermine production performance.
|
||||
- **Content**: High-level operation overview, connection events, major decisions.
|
||||
|
||||
##### Info Level
|
||||
- **Usage**: Reserved for things that went wrong but can't be communicated
|
||||
through other means like throwing from a method
|
||||
through other means, like throwing from a method.
|
||||
- **Examples**: Connection retry attempts, fallback mechanisms, recoverable
|
||||
failures
|
||||
- **Guideline**: Use sparingly - not for normal successful operations
|
||||
failures.
|
||||
- **Guideline**: Use sparingly - Don't use for normal successful operations.
|
||||
|
||||
#### For applications
|
||||
|
||||
@@ -133,6 +133,6 @@ logger.info("Response sent")
|
||||
|
||||
// ✅ Good: Use appropriate levels instead
|
||||
logger.debug("Processing request", metadata: ["path": "\(path)"])
|
||||
logger.trace("Query", , metadata: ["path": "\(query)"])
|
||||
logger.trace("Query", metadata: ["sql": "\(query)"])
|
||||
logger.debug("Request completed", metadata: ["status": "\(status)"])
|
||||
```
|
||||
@@ -0,0 +1,96 @@
|
||||
# 002: Structured logging
|
||||
|
||||
Use metadata to create machine-readable, searchable log entries.
|
||||
|
||||
## Overview
|
||||
|
||||
Structured logging uses metadata to separate human-readable messages from
|
||||
machine-readable data. This practice makes logs easier to search, filter, and
|
||||
analyze programmatically while maintaining readability.
|
||||
|
||||
### Motivation
|
||||
|
||||
Traditional string-based logging embeds all information in the message text,
|
||||
making it more difficult for automated tools to parse and extract.
|
||||
Structured logging separates these concerns; messages provide human readable
|
||||
context while metadata provides structured data for tooling.
|
||||
|
||||
### Example
|
||||
|
||||
#### Recommended: Structured logging
|
||||
|
||||
```swift
|
||||
// ✅ Structured - message provides context, metadata provides data
|
||||
logger.info(
|
||||
"Accepted connection",
|
||||
metadata: [
|
||||
"connection.id": "\(id)",
|
||||
"connection.peer": "\(peer)",
|
||||
"connections.total": "\(count)"
|
||||
]
|
||||
)
|
||||
|
||||
logger.error(
|
||||
"Database query failed",
|
||||
metadata: [
|
||||
"query.retries": "\(retries)",
|
||||
"query.error": "\(error)",
|
||||
"query.duration": "\(duration)"
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Advanced: Nested metadata for complex data
|
||||
|
||||
```swift
|
||||
// ✅ Complex structured data
|
||||
logger.trace(
|
||||
"HTTP request started",
|
||||
metadata: [
|
||||
"request.id": "\(requestId)",
|
||||
"request.method": "GET",
|
||||
"request.path": "/api/users",
|
||||
"request.headers": [
|
||||
"user-agent": "\(userAgent)"
|
||||
],
|
||||
"client.ip": "\(clientIP)",
|
||||
"client.country": "\(country)"
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
#### Avoid: Unstructured logging
|
||||
|
||||
```swift
|
||||
// ❌ Not structured - hard to parse programmatically
|
||||
logger.info("Accepted connection \(id) from \(peer), total: \(count)")
|
||||
logger.error("Database query failed after \(retries) retries: \(error)")
|
||||
```
|
||||
|
||||
### Metadata key conventions
|
||||
|
||||
Use hierarchical dot-notation for related fields:
|
||||
|
||||
```swift
|
||||
// ✅ Good: Hierarchical keys
|
||||
logger.debug(
|
||||
"Database operation completed",
|
||||
metadata: [
|
||||
"db.operation": "SELECT",
|
||||
"db.table": "users",
|
||||
"db.duration": "\(duration)",
|
||||
"db.rows": "\(rowCount)"
|
||||
]
|
||||
)
|
||||
|
||||
// ✅ Good: Consistent prefixing
|
||||
logger.info(
|
||||
"HTTP response",
|
||||
metadata: [
|
||||
"http.method": "POST",
|
||||
"http.status": "201",
|
||||
"http.path": "/api/users",
|
||||
"http.duration": "\(duration)"
|
||||
]
|
||||
)
|
||||
```
|
||||
@@ -0,0 +1,100 @@
|
||||
# 003: Accepting loggers in libraries
|
||||
|
||||
Accept loggers through method parameters to ensure proper metadata propagation.
|
||||
|
||||
## Overview
|
||||
|
||||
Libraries should accept logger instances through method parameters rather than
|
||||
storing them as instance variables. This practice ensures metadata (such as
|
||||
correlation IDs) is properly propagated down the call stack, while giving
|
||||
applications control over logging configuration.
|
||||
|
||||
### Motivation
|
||||
|
||||
When libraries accept loggers as method parameters, they enable automatic
|
||||
propagation of contextual metadata attached to the logger instance. This is
|
||||
especially important for distributed systems where correlation IDs must flow
|
||||
through the entire request processing pipeline.
|
||||
|
||||
### Example
|
||||
|
||||
#### Recommended: Accept logger through method parameters
|
||||
|
||||
```swift
|
||||
// ✅ Good: Pass the logger through method parameters.
|
||||
struct RequestProcessor {
|
||||
func processRequest(_ request: HTTPRequest, logger: Logger) async throws -> HTTPResponse {
|
||||
// Add structured metadata that every log statement should contain.
|
||||
var logger = logger
|
||||
logger[metadataKey: "request.method"] = "\(request.method)"
|
||||
logger[metadataKey: "request.path"] = "\(request.path)"
|
||||
logger[metadataKey: "request.id"] = "\(request.id)"
|
||||
|
||||
logger.debug("Processing request")
|
||||
|
||||
// Pass the logger down to maintain metadata context.
|
||||
let validatedData = try validateRequest(request, logger: logger)
|
||||
let result = try await executeBusinessLogic(validatedData, logger: logger)
|
||||
|
||||
logger.debug("Request processed successfully")
|
||||
return result
|
||||
}
|
||||
|
||||
private func validateRequest(_ request: HTTPRequest, logger: Logger) throws -> ValidatedRequest {
|
||||
logger.debug("Validating request parameters")
|
||||
// Include validation logic that uses the same logger context.
|
||||
return ValidatedRequest(request)
|
||||
}
|
||||
|
||||
private func executeBusinessLogic(_ data: ValidatedRequest, logger: Logger) async throws -> HTTPResponse {
|
||||
logger.debug("Executing business logic")
|
||||
|
||||
// Further propagate the logger to other services.
|
||||
let dbResult = try await databaseService.query(data.query, logger: logger)
|
||||
|
||||
logger.debug("Business logic completed")
|
||||
return HTTPResponse(data: dbResult)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Alternative: Accept logger through initializer when appropriate
|
||||
|
||||
```swift
|
||||
// ✅ Acceptable: Logger through initializer for long-lived components
|
||||
final class BackgroundJobProcessor {
|
||||
private let logger: Logger
|
||||
|
||||
init(logger: Logger) {
|
||||
self.logger = logger
|
||||
}
|
||||
|
||||
func run() async {
|
||||
// Execute some long running work
|
||||
logger.debug("Update about long running work")
|
||||
// Execute some more long running work
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Avoid: Libraries creating their own loggers
|
||||
|
||||
Libraries might create their own loggers; however, this leads to two problems.
|
||||
First, users of the library can't inject their own loggers which means they have
|
||||
no control in customizing the log level or log handler. Secondly, it breaks the
|
||||
metadata propagation since users can't pass in a logger with already attached
|
||||
metadata.
|
||||
|
||||
```swift
|
||||
// ❌ Bad: Library creates its own logger
|
||||
final class MyLibrary {
|
||||
private let logger = Logger(label: "MyLibrary") // Loses all context
|
||||
}
|
||||
|
||||
// ✅ Good: Library accepts logger from caller
|
||||
final class MyLibrary {
|
||||
func operation(logger: Logger) {
|
||||
// Maintains caller's context and metadata
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,11 +1,10 @@
|
||||
# Implementing a log handler
|
||||
|
||||
Create a custom logging backend that provides logging services for your apps
|
||||
and libraries.
|
||||
Create a custom logging backend that provides logging services for your apps and libraries.
|
||||
|
||||
## Overview
|
||||
|
||||
To become a compatible logging backend that any `SwiftLog` consumer can use,
|
||||
To become a compatible logging backend that any SwiftLog consumer can use,
|
||||
you need to fulfill a few requirements, primarily conforming to the
|
||||
``LogHandler`` protocol.
|
||||
|
||||
|
||||
@@ -39,3 +39,5 @@ practice includes:
|
||||
## Topics
|
||||
|
||||
- <doc:001-ChoosingLogLevels>
|
||||
- <doc:002-StructuredLogging>
|
||||
- <doc:003-AcceptingLoggers>
|
||||
@@ -0,0 +1,38 @@
|
||||
# Proposals
|
||||
|
||||
Collaborate on API changes to SwiftLog by writing a proposal.
|
||||
|
||||
## Overview
|
||||
|
||||
For non-trivial changes that affect the public API, the SwiftLog project adopts a lightweight version of the [Swift Evolution](https://github.com/apple/swift-evolution/blob/main/process.md) process.
|
||||
|
||||
Writing a proposal first helps discuss multiple possible solutions early, apply useful feedback from other contributors, and avoid reimplementing the same feature multiple times.
|
||||
|
||||
While it's encouraged to get feedback by opening a pull request with a proposal early in the process, it's also important to consider the complexity of the implementation when evaluating different solutions. For example, this might mean including a link to a branch containing a prototype implementation of the feature in the pull request description.
|
||||
|
||||
> Note: The goal of this process is to help solicit feedback from the whole community around the project, and we will continue to refine the proposal process itself. Use your best judgement, and don't hesitate to propose changes to the proposal structure itself!
|
||||
|
||||
### Steps
|
||||
|
||||
1. Make sure there's a GitHub issue for the feature or change you would like to propose.
|
||||
2. Duplicate the `SLG-NNNN.md` document and replace `NNNN` with the next available proposal number.
|
||||
3. Link the GitHub issue from your proposal, and fill in the proposal.
|
||||
4. Open a pull request with your proposal and solicit feedback from other contributors.
|
||||
5. Once a maintainer confirms that the proposal is ready for review, the state is updated accordingly. The review period is 7 days, and ends when one of the maintainers marks the proposal as Ready for Implementation, or Deferred.
|
||||
6. Before the pull request is merged, there should be an implementation ready, either in the same pull request, or a separate one, linked from the proposal.
|
||||
7. The proposal is considered Approved once the implementation, proposal PRs have been merged, and, if originally disabled by a feature flag, feature flag enabled unconditionally.
|
||||
|
||||
If you have any questions, ask in an issue on GitHub.
|
||||
|
||||
### Possible review states
|
||||
|
||||
- Awaiting Review
|
||||
- In Review
|
||||
- Ready for Implementation
|
||||
- In Preview
|
||||
- Approved
|
||||
- Deferred
|
||||
|
||||
## Topics
|
||||
|
||||
- <doc:SLG-NNNN>
|
||||
+4
-4
@@ -1,11 +1,11 @@
|
||||
# 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.
|
||||
|
||||
## Authors
|
||||
|
||||
[Moritz Lang](https://github.com/slashmo), [Konrad 'ktoso' Malawski](https://github.com/ktoso)
|
||||
|
||||
## Motivation
|
||||
|
||||
To benefit from tools such as [Distributed Tracing](https://github.com/apple/swift-distributed-tracing) it is necessary for libraries to make use of the trace information.
|
||||
@@ -0,0 +1,173 @@
|
||||
# SLG-0002: Compile-time log level elimination using traits
|
||||
|
||||
Enable compile-time elimination of log levels to achieve zero runtime overhead for logs that will never be needed in production.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0002
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Ready for Implementation**
|
||||
- Issue: [apple/swift-log#378](https://github.com/apple/swift-log/issues/378)
|
||||
- Implementation:
|
||||
- [apple/swift-log#389](https://github.com/apple/swift-log/pull/389)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
Add Swift package traits to allow applications to compile out less severe log levels, completely eliminating their runtime overhead from the final binary.
|
||||
|
||||
### Motivation
|
||||
|
||||
In production deployments, applications often know in advance which log levels will never be needed. For example, a production service typically only needs warning and above, while trace and debug levels are exclusively useful during development. Currently, even with the log level set to `.warning` at runtime, the code for trace and debug statements still exists in the binary and incurs overhead.
|
||||
|
||||
For performance-critical applications or resource-constrained environments, this overhead is unacceptable. Applications need a way to completely remove unnecessary log levels at compile time, achieving zero runtime cost.
|
||||
|
||||
Before this proposal, the only workarounds were:
|
||||
- Manually wrapping log statements in `#if DEBUG` checks (error-prone and verbose)
|
||||
- Accepting the runtime overhead (unacceptable for many use cases)
|
||||
|
||||
### Proposed solution
|
||||
|
||||
This proposal introduces seven package traits that correspond to maximum log level thresholds. Applications specify a trait when declaring their dependency on SwiftLog, and all less severe log levels are completely compiled out.
|
||||
|
||||
In your `Package.swift`:
|
||||
|
||||
```swift
|
||||
dependencies: [
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["MaxLogLevelWarning"]
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
With `MaxLogLevelWarning` enabled:
|
||||
|
||||
```swift
|
||||
// These become no-ops (compiled out completely):
|
||||
logger.trace("This will not be in the binary")
|
||||
logger.debug("This will not be in the binary")
|
||||
logger.info("This will not be in the binary")
|
||||
logger.notice("This will not be in the binary")
|
||||
logger.log(level: .debug, "This will not log anything")
|
||||
|
||||
// These work normally:
|
||||
logger.warning("This still works")
|
||||
logger.error("This still works")
|
||||
logger.critical("This still works")
|
||||
logger.log(level: .error, "This still works")
|
||||
```
|
||||
|
||||
### Detailed design
|
||||
|
||||
The seven available traits, ordered from most permissive to most restrictive, are:
|
||||
|
||||
```swift
|
||||
traits: [
|
||||
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
|
||||
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
|
||||
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
|
||||
.trait(
|
||||
name: "MaxLogLevelWarning",
|
||||
description: "Warning and above available (compiles out trace, debug, info, notice)"
|
||||
),
|
||||
.trait(
|
||||
name: "MaxLogLevelError",
|
||||
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
|
||||
),
|
||||
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
|
||||
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
|
||||
|
||||
.default(enabledTraits: []),
|
||||
]
|
||||
```
|
||||
|
||||
By default (when no traits are specified), all log levels remain available.
|
||||
|
||||
Traits are additive: if multiple max level traits are specified in the dependency graph, the most restrictive one takes effect. This ensures that if any dependency requests stricter elimination, the entire build respects it.
|
||||
|
||||
> Important: Traits should only be set by applications, not libraries, as any trait defined in a transitive dependency will affect the entire dependency resolution tree.
|
||||
|
||||
For the generic `log(level:)` method, the implementation switches behavior based on whether any trait is enabled:
|
||||
|
||||
```swift
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
) {
|
||||
#if MaxLogLevelDebug || MaxLogLevelInfo || MaxLogLevelNotice || MaxLogLevelWarning || MaxLogLevelError || MaxLogLevelCritical || MaxLogLevelNone
|
||||
// When traits are enabled, dispatch to level-specific methods
|
||||
// to leverage their compile-time elimination
|
||||
switch level {
|
||||
case .trace:
|
||||
self.trace(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
|
||||
case .debug:
|
||||
self.debug(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
|
||||
// ... (all levels)
|
||||
}
|
||||
#else
|
||||
// When no traits are enabled, avoid the switch overhead
|
||||
self._log(
|
||||
level: level,
|
||||
message(),
|
||||
metadata: metadata(),
|
||||
source: source(),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
#endif
|
||||
}
|
||||
```
|
||||
|
||||
This approach adds a minimal switch statement overhead when traits are enabled, but allows the level-specific methods' compile-time elimination to work even when called through `log(level:)`. When no traits are enabled, the original zero-overhead path is preserved. Level-specific methods has no additional overhead.
|
||||
|
||||
### API stability
|
||||
|
||||
**For existing `Logger` users:**
|
||||
- When no traits are enabled (the default), behavior is identical to before
|
||||
- Users can opt in to traits at the application level without modifying any source code
|
||||
|
||||
**For existing `LogHandler` implementations:**
|
||||
- No changes are required to any `LogHandler` implementation
|
||||
|
||||
### Future directions
|
||||
|
||||
No future directions identified.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Per-log-level traits
|
||||
|
||||
An alternative approach would be to define one trait per log level that could be individually disabled:
|
||||
|
||||
```swift
|
||||
traits: [
|
||||
.trait(name: "DisableTraceLogs"),
|
||||
.trait(name: "DisableDebugLogs"),
|
||||
.trait(name: "DisableInfoLogs"),
|
||||
.trait(name: "DisableNoticeLogs"),
|
||||
.trait(name: "DisableWarningLogs"),
|
||||
.trait(name: "DisableErrorLogs"),
|
||||
.trait(name: "DisableCriticalLogs"),
|
||||
]
|
||||
```
|
||||
|
||||
Users would specify multiple traits to eliminate multiple levels:
|
||||
|
||||
```swift
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["DisableTraceLogs", "DisableDebugLogs", "DisableInfoLogs", "DisableNoticeLogs"]
|
||||
)
|
||||
```
|
||||
|
||||
This approach was rejected in favor of a `MaxLogLevel` semantics to make it less verbose to use the functionality and to be aligned with the similar functionality in logging packages in other languages users might already be familiar with.
|
||||
@@ -0,0 +1,49 @@
|
||||
# SLG-NNNN: Feature name
|
||||
|
||||
Feature abstract – a one sentence summary.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-NNNN
|
||||
- Author(s): [Author 1](https://github.com/swiftdev), [Author 2](https://github.com/swiftdev)
|
||||
- Status: **Awaiting Review**
|
||||
- Issue: [apple/swift-log#1](https://github.com/apple/swift-log/issues/1)
|
||||
- Implementation:
|
||||
- [apple/swift-log#1](https://github.com/apple/swift-log/pull/1)
|
||||
- Feature flag: `proposalNNNN`
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
A short, one-sentence overview of the feature or change.
|
||||
|
||||
### Motivation
|
||||
|
||||
Describe the problems that this proposal aims to address, and what workarounds adopters have to employ currently, if any.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds.
|
||||
|
||||
This section should focus on what will change for the _adopters_ of SwiftLog.
|
||||
|
||||
### Detailed design
|
||||
|
||||
Describe the implementation of the feature, a link to a prototype implementation is encouraged here.
|
||||
|
||||
This section should focus on what will change for the _contributors_ to SwiftLog.
|
||||
|
||||
### API stability
|
||||
|
||||
Discuss the API implications, making sure to considering all of:
|
||||
- existing ``Logger`` users,
|
||||
- existing ``LogHandler`` implementations.
|
||||
|
||||
### Future directions
|
||||
|
||||
Discuss any potential future improvements to the feature.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
Discuss the alternative solutions considered, even during the review process itself.
|
||||
@@ -0,0 +1,20 @@
|
||||
# ``Logging/LogHandler``
|
||||
|
||||
## Topics
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(level:message:metadata:source:file:function:line:)-8kgt7``
|
||||
- ``log(level:message:metadata:source:file:function:line:)-69pez``
|
||||
- ``log(level:message:metadata:file:function:line:)-89rya``
|
||||
- ``log(level:message:metadata:file:function:line:)-1xdau``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,13 @@
|
||||
# ``Logging/Logger/Level``
|
||||
|
||||
## Topics
|
||||
|
||||
### Log Levels
|
||||
|
||||
- ``trace``
|
||||
- ``debug``
|
||||
- ``info``
|
||||
- ``notice``
|
||||
- ``warning``
|
||||
- ``error``
|
||||
- ``critical``
|
||||
@@ -0,0 +1,12 @@
|
||||
# ``Logging/Logger/Message``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a log message
|
||||
|
||||
- ``init(stringLiteral:)``
|
||||
|
||||
### Inspecting a log message
|
||||
|
||||
- ``description``
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# ``Logging/Logger/MetadataProvider``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a metadata provider
|
||||
|
||||
- ``init(_:)``
|
||||
|
||||
### Invoking the provider
|
||||
|
||||
- ``get()``
|
||||
|
||||
### Merging metadata
|
||||
|
||||
- ``multiplex(_:)``
|
||||
@@ -0,0 +1,11 @@
|
||||
# ``Logging/Logger/MetadataValue``
|
||||
|
||||
## Topics
|
||||
|
||||
### Types of metadata values
|
||||
|
||||
- ``string(_:)``
|
||||
- ``stringConvertible(_:)``
|
||||
- ``array(_:)``
|
||||
- ``dictionary(_:)``
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# ``Logging/Logger``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating Loggers
|
||||
|
||||
- ``init(label:)``
|
||||
- ``init(label:metadataProvider:)``
|
||||
- ``init(label:factory:)-9uiy2``
|
||||
- ``init(label:factory:)-6iktu``
|
||||
- ``MetadataProvider``
|
||||
|
||||
### Sending trace log messages
|
||||
|
||||
- ``trace(_:metadata:file:function:line:)``
|
||||
- ``trace(_:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending debug log messages
|
||||
- ``debug(_:metadata:file:function:line:)``
|
||||
- ``debug(_:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending info log messages
|
||||
- ``info(_:metadata:file:function:line:)``
|
||||
- ``info(_:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending notice log messages
|
||||
- ``notice(_:metadata:file:function:line:)``
|
||||
- ``notice(_:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending warning log messages
|
||||
- ``warning(_:metadata:file:function:line:)``
|
||||
- ``warning(_:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending error log messages
|
||||
- ``error(_:metadata:file:function:line:)``
|
||||
- ``error(_:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending critical log messages
|
||||
- ``critical(_:metadata:file:function:line:)``
|
||||
- ``critical(_:metadata:source:file:function:line:)``
|
||||
|
||||
### Sending general log messages
|
||||
|
||||
- ``log(level:_:metadata:file:function:line:)``
|
||||
- ``log(level:_:metadata:source:file:function:line:)``
|
||||
- ``Level``
|
||||
- ``Message``
|
||||
- ``Metadata``
|
||||
|
||||
### Adjusting logger metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
- ``MetadataValue``
|
||||
|
||||
### Inspecting a logger
|
||||
|
||||
- ``label``
|
||||
- ``logLevel``
|
||||
- ``handler``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,13 @@
|
||||
# ``Logging/LoggingSystem``
|
||||
|
||||
## Topics
|
||||
|
||||
### Initializing the logging system
|
||||
|
||||
- ``bootstrap(_:)``
|
||||
- ``bootstrap(_:metadataProvider:)``
|
||||
|
||||
### Inspecting the logging system
|
||||
|
||||
- ``metadataProvider``
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# ``Logging/MultiplexLogHandler``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a multiplex log handler
|
||||
|
||||
- ``init(_:)``
|
||||
- ``init(_:metadataProvider:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,24 @@
|
||||
# ``Logging/StreamLogHandler``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a stream log handler
|
||||
|
||||
- ``standardOutput(label:)``
|
||||
- ``standardOutput(label:metadataProvider:)``
|
||||
- ``standardError(label:)``
|
||||
- ``standardError(label:metadataProvider:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,22 @@
|
||||
# ``Logging/SwiftLogNoOpLogHandler``
|
||||
|
||||
## Topics
|
||||
|
||||
### Creating a Swift Log no-op log handler
|
||||
|
||||
- ``init()``
|
||||
- ``init(_:)``
|
||||
|
||||
### Sending log messages
|
||||
|
||||
- ``log(level:message:metadata:source:file:function:line:)``
|
||||
|
||||
### Updating metadata
|
||||
|
||||
- ``subscript(metadataKey:)``
|
||||
|
||||
### Inspecting a log handler
|
||||
|
||||
- ``logLevel``
|
||||
- ``metadata``
|
||||
- ``metadataProvider``
|
||||
@@ -0,0 +1,86 @@
|
||||
# Understanding Loggers and Log Handlers
|
||||
|
||||
Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages.
|
||||
|
||||
## Overview
|
||||
|
||||
Create or retrieve a logger to get an instance for logging messages.
|
||||
Log messages have a level that you use to indicate the message's importance.
|
||||
|
||||
SwiftLog defines seven log levels, represented by ``Logger/Level``, ordered from least to
|
||||
most severe:
|
||||
|
||||
- ``Logger/Level/trace``
|
||||
- ``Logger/Level/debug``
|
||||
- ``Logger/Level/info``
|
||||
- ``Logger/Level/notice``
|
||||
- ``Logger/Level/warning``
|
||||
- ``Logger/Level/error``
|
||||
- ``Logger/Level/critical``
|
||||
|
||||
Once a message is sent to a logger, a log handler processes it.
|
||||
The app using the logger configures the handler, usually for the environment in which that app runs, processing messages appropriate to that environment.
|
||||
If the app doesn't provide its own log handler, SwiftLog defaults to using a ``StreamLogHandler`` that outputs log messages to `STDOUT`.
|
||||
|
||||
### Loggers
|
||||
|
||||
Loggers are used to emit log messages at different severity levels:
|
||||
|
||||
```swift
|
||||
// Informational message
|
||||
logger.info("Processing request")
|
||||
|
||||
// Something went wrong
|
||||
logger.error("Houston, we have a problem")
|
||||
```
|
||||
|
||||
``Logger`` is a value type with value semantics, meaning that when you modify a
|
||||
logger's configuration (like its log level or metadata), it only affects that
|
||||
specific logger instance:
|
||||
|
||||
```swift
|
||||
let baseLogger = Logger(label: "MyApp")
|
||||
|
||||
// Create a new logger with different configuration.
|
||||
var requestLogger = baseLogger
|
||||
requestLogger.logLevel = .debug
|
||||
requestLogger[metadataKey: "request-id"] = "\(UUID())"
|
||||
|
||||
// baseLogger is unchanged. It still has default log level and no metadata
|
||||
// requestLogger has debug level and request-id metadata.
|
||||
```
|
||||
|
||||
This value type behavior makes loggers safe to pass between functions and modify
|
||||
without unexpected side effects.
|
||||
|
||||
### Log Levels
|
||||
|
||||
Log levels can be changed per logger without affecting others:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "MyLogger")
|
||||
logger.logLevel = .debug
|
||||
```
|
||||
|
||||
For guidance on what level to use for a message, see <doc:001-ChoosingLogLevels>.
|
||||
|
||||
### Logging Metadata
|
||||
|
||||
Metadata provides contextual information crucial for debugging:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "com.example.server")
|
||||
logger[metadataKey: "request.id"] = "\(UUID())"
|
||||
logger.info("Processing request")
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request
|
||||
```
|
||||
|
||||
### Source vs Label
|
||||
|
||||
A ``Logger`` has an immutable `label` that identifies its creator, while each log
|
||||
message carries a `source` parameter that identifies where the message originated.
|
||||
Use `source` for filtering messages from specific subsystems.
|
||||
@@ -19,8 +19,8 @@ libraries.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Use this If you are writing a cross-platform application (for example, Linux and
|
||||
macOS) or library, target this logging API.
|
||||
Use this package if you're writing a cross-platform application (for example, Linux and
|
||||
macOS) or library, and want to target this logging API.
|
||||
|
||||
### Adding the Dependency
|
||||
|
||||
@@ -56,7 +56,7 @@ logger.info("Hello World!")
|
||||
|
||||
This outputs:
|
||||
```
|
||||
2019-03-13T15:46:38+0000 info: Hello World!
|
||||
2025-10-24T17:26:47-0700 info MyLogger: [your_app] Hello World!
|
||||
```
|
||||
|
||||
### Default Behavior
|
||||
@@ -72,83 +72,12 @@ LoggingSystem.bootstrap(StreamLogHandler.standardError)
|
||||
implement the ``LogHandler`` protocol directly or use a community-maintained
|
||||
backend.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Loggers
|
||||
|
||||
Loggers are used to emit log messages at different severity levels:
|
||||
|
||||
```swift
|
||||
// Informational message
|
||||
logger.info("Processing request")
|
||||
|
||||
// Something went wrong
|
||||
logger.error("Houston, we have a problem")
|
||||
```
|
||||
|
||||
``Logger`` is a value type with value semantics, meaning that when you modify a
|
||||
logger's configuration (like its log level or metadata), it only affects that
|
||||
specific logger instance:
|
||||
|
||||
```swift
|
||||
let baseLogger = Logger(label: "MyApp")
|
||||
|
||||
// Create a new logger with different configuration.
|
||||
var requestLogger = baseLogger
|
||||
requestLogger.logLevel = .debug
|
||||
requestLogger[metadataKey: "request-id"] = "\(UUID())"
|
||||
|
||||
// baseLogger is unchanged. It still has default log level and no metadata
|
||||
// requestLogger has debug level and request-id metadata.
|
||||
```
|
||||
|
||||
This value type behavior makes loggers safe to pass between functions and modify
|
||||
without unexpected side effects.
|
||||
|
||||
### Log Levels
|
||||
|
||||
SwiftLog supports seven log levels (from least to most severe):
|
||||
- ``Logger/Level/trace``
|
||||
- ``Logger/Level/debug``
|
||||
- ``Logger/Level/info``
|
||||
- ``Logger/Level/notice``
|
||||
- ``Logger/Level/warning``
|
||||
- ``Logger/Level/error``
|
||||
- ``Logger/Level/critical``
|
||||
|
||||
Log levels can be changed per logger without affecting others:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "MyLogger")
|
||||
logger.logLevel = .debug
|
||||
```
|
||||
|
||||
### Logging Metadata
|
||||
|
||||
Metadata provides contextual information crucial for debugging:
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "com.example.server")
|
||||
logger[metadataKey: "request-uuid"] = "\(UUID())"
|
||||
logger.info("Processing request")
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request
|
||||
```
|
||||
|
||||
### Source vs Label
|
||||
|
||||
A ``Logger`` has an immutable `label` identifying its creator, while each log
|
||||
message carries a `source` parameter identifying where the message originated.
|
||||
Use `source` for filtering messages from specific subsystems.
|
||||
|
||||
|
||||
## Topics
|
||||
|
||||
### Logging API
|
||||
|
||||
- <doc:UnderstandingLoggers>
|
||||
- ``Logger``
|
||||
- ``LoggingSystem``
|
||||
|
||||
@@ -162,5 +91,8 @@ Use `source` for filtering messages from specific subsystems.
|
||||
### Best Practices
|
||||
|
||||
- <doc:LoggingBestPractices>
|
||||
- <doc:001-ChoosingLogLevels>
|
||||
- <doc:ImplementingALogHandler>
|
||||
|
||||
### Contributing
|
||||
|
||||
- <doc:Proposals>
|
||||
@@ -48,7 +48,7 @@ import Musl
|
||||
/// of lock is safe to use with `libpthread`-based threading models, such as the
|
||||
/// one used by NIO. On Windows, the lock is based on the substantially similar
|
||||
/// `SRWLOCK` type.
|
||||
internal final class Lock: @unchecked Sendable {
|
||||
package final class Lock: @unchecked Sendable {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
@@ -60,7 +60,7 @@ internal final class Lock: @unchecked Sendable {
|
||||
#endif
|
||||
|
||||
/// Create a new lock.
|
||||
public init() {
|
||||
package init() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
@@ -92,7 +92,7 @@ internal final class Lock: @unchecked Sendable {
|
||||
///
|
||||
/// Whenever possible, consider using `withLock` instead of this method and
|
||||
/// `unlock`, to simplify lock handling.
|
||||
public func lock() {
|
||||
package func lock() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
@@ -107,7 +107,7 @@ internal final class Lock: @unchecked Sendable {
|
||||
///
|
||||
/// Whenever possible, consider using `withLock` instead of this method and
|
||||
/// `lock`, to simplify lock handling.
|
||||
public func unlock() {
|
||||
package func unlock() {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
@@ -129,7 +129,7 @@ extension Lock {
|
||||
/// - Parameter body: The block to execute while holding the lock.
|
||||
/// - Returns: The value returned by the block.
|
||||
@inlinable
|
||||
internal func withLock<T>(_ body: () throws -> T) rethrows -> T {
|
||||
package func withLock<T>(_ body: () throws -> T) rethrows -> T {
|
||||
self.lock()
|
||||
defer {
|
||||
self.unlock()
|
||||
@@ -139,7 +139,7 @@ extension Lock {
|
||||
|
||||
// specialise Void return (for performance)
|
||||
@inlinable
|
||||
internal func withLockVoid(_ body: () throws -> Void) rethrows {
|
||||
package func withLockVoid(_ body: () throws -> Void) rethrows {
|
||||
try self.withLock(body)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -12,19 +12,19 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A `LogHandler` is an implementation of a logging backend.
|
||||
/// A log handler provides an implementation of a logging backend.
|
||||
///
|
||||
/// This type is an implementation detail and should not normally be used, unless implementing your own logging backend.
|
||||
/// This type is an implementation detail and should not normally be used, unless you implement your own logging backend.
|
||||
/// 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.
|
||||
/// as expected, regardless of the selected `LogHandler` implementation.
|
||||
///
|
||||
/// - 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.
|
||||
/// other instances of `Logger`.
|
||||
///
|
||||
/// ### Treat log level & metadata as values
|
||||
///
|
||||
@@ -52,18 +52,21 @@
|
||||
///
|
||||
/// ### Special cases
|
||||
///
|
||||
/// In certain special cases, the log level behaving like a value on `Logger` might not be what you want. For example,
|
||||
/// you might want to set the log level across _all_ `Logger`s to `.debug` when say a signal (eg. `SIGUSR1`) is received
|
||||
/// to be able to debug special failures in production. This special case is acceptable but we urge you to create a
|
||||
/// solution specific to your `LogHandler` implementation to achieve that. Please find an example implementation of this
|
||||
/// behavior below, on reception of the signal you would call
|
||||
/// In certain special cases, the log level behaving like a value on `Logger` might not be what you want.
|
||||
/// For example, you might want to set the log level across _all_ `Logger`s to `.debug` when a signal
|
||||
/// (for example `SIGUSR1`) is received to be able to debug special failures in production.
|
||||
/// This special case is acceptable but please create a solution specific to your `LogHandler` implementation to achieve that.
|
||||
///
|
||||
/// The following code illustrates an example implementation of this behavior.
|
||||
/// On reception of the signal you would call
|
||||
/// `LogHandlerWithGlobalLogLevelOverride.overrideGlobalLogLevel = .debug`, for example.
|
||||
///
|
||||
/// ```swift
|
||||
/// import class Foundation.NSLock
|
||||
///
|
||||
/// public struct LogHandlerWithGlobalLogLevelOverride: LogHandler {
|
||||
/// // the static properties hold the globally overridden log level (if overridden)
|
||||
/// // The static properties hold the globally overridden
|
||||
/// // log level (if overridden).
|
||||
/// private static let overrideLock = NSLock()
|
||||
/// private static var overrideLogLevel: Logger.Level? = nil
|
||||
///
|
||||
@@ -78,21 +81,29 @@
|
||||
/// }
|
||||
///
|
||||
/// public var logLevel: Logger.Level {
|
||||
/// // when we get asked for the log level, we check if it was globally overridden or not
|
||||
/// // When asked for the log level, check
|
||||
/// // if it was globally overridden or not.
|
||||
/// get {
|
||||
/// LogHandlerWithGlobalLogLevelOverride.overrideLock.lock()
|
||||
/// defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() }
|
||||
/// return LogHandlerWithGlobalLogLevelOverride.overrideLogLevel ?? self._logLevel
|
||||
/// }
|
||||
/// // we set the log level whenever we're asked (note: this might not have an effect if globally
|
||||
/// // overridden)
|
||||
/// // Set the log level whenever asked
|
||||
/// // (note: this might not have an effect if globally
|
||||
/// // overridden).
|
||||
/// set {
|
||||
/// self._logLevel = newValue
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// public func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?,
|
||||
/// source: String, file: String, function: String, line: UInt) {
|
||||
/// public func log(
|
||||
/// level: Logger.Level,
|
||||
/// message: Logger.Message,
|
||||
/// metadata: Logger.Metadata?,
|
||||
/// source: String,
|
||||
/// file: String,
|
||||
/// function: String,
|
||||
/// line: UInt) {
|
||||
/// // [...]
|
||||
/// }
|
||||
///
|
||||
@@ -105,7 +116,8 @@
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// // this is the function to globally override the log level, it is not part of the `LogHandler` protocol
|
||||
/// // This is the function to globally override the log level,
|
||||
/// // it is not part of the `LogHandler` protocol.
|
||||
/// public static func overrideGlobalLogLevel(_ logLevel: Logger.Level) {
|
||||
/// LogHandlerWithGlobalLogLevelOverride.overrideLock.lock()
|
||||
/// defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() }
|
||||
@@ -114,28 +126,30 @@
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// 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.
|
||||
/// > Note: The above `LogHandler` still passes the 'log level is a value' test above it if the global log
|
||||
/// > level has not been overridden. 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: _SwiftLogSendableLogHandler {
|
||||
/// The metadata provider this `LogHandler` will use when a log statement is about to be emitted.
|
||||
/// The metadata provider this log handler uses 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
|
||||
/// The library calls this method when a log handler must emit a log message.
|
||||
///
|
||||
/// There is no need for the `LogHandler` to check if the `level` is above or
|
||||
/// below the configured `logLevel` as `Logger` already performed this check and
|
||||
/// determined that a message should be logged.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - level: The log level the message was logged at.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file the log message was emitted from.
|
||||
/// - function: The function the log line was emitted from.
|
||||
/// - line: The line the log message was emitted from.
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
@@ -146,8 +160,18 @@ public protocol LogHandler: _SwiftLogSendableLogHandler {
|
||||
line: UInt
|
||||
)
|
||||
|
||||
/// SwiftLog 1.0 compatibility method. Please do _not_ implement, implement
|
||||
/// `log(level:message:metadata:source:file:function:line:)` instead.
|
||||
/// SwiftLog 1.0 log compatibility method.
|
||||
///
|
||||
/// Please do _not_ implement this method when you create a LogHandler implementation.
|
||||
/// Implement `log(level:message:metadata:source:file:function:line:)` instead.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
|
||||
func log(
|
||||
level: Logging.Logger.Level,
|
||||
@@ -183,8 +207,9 @@ public protocol LogHandler: _SwiftLogSendableLogHandler {
|
||||
}
|
||||
|
||||
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.
|
||||
/// Default implementation for a metadata provider that defaults to nil.
|
||||
///
|
||||
/// This default exists in order to facilitate the source-compatible introduction of the `metadataProvider` protocol requirement.
|
||||
public var metadataProvider: Logger.MetadataProvider? {
|
||||
get {
|
||||
nil
|
||||
@@ -209,6 +234,15 @@ extension LogHandler {
|
||||
}
|
||||
|
||||
extension LogHandler {
|
||||
/// A default implementation for a log message handler that forwards the source location for the message.
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
@@ -222,6 +256,14 @@ extension LogHandler {
|
||||
self.log(level: level, message: message, metadata: metadata, file: file, function: function, line: line)
|
||||
}
|
||||
|
||||
/// A default implementation for a log message handler.
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
|
||||
public func log(
|
||||
level: Logging.Logger.Level,
|
||||
|
||||
+435
-250
File diff suppressed because it is too large.
Load diff
@@ -31,7 +31,7 @@ import WASILibc
|
||||
@preconcurrency protocol _SwiftLogSendable: Sendable {}
|
||||
|
||||
extension Logger {
|
||||
/// A `MetadataProvider` is used to automatically inject runtime-generated metadata
|
||||
/// A MetadataProvider automatically injects runtime-generated metadata
|
||||
/// to all logs emitted by a logger.
|
||||
///
|
||||
/// ### Example
|
||||
@@ -58,18 +58,18 @@ extension Logger {
|
||||
/// 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.
|
||||
/// Provide ``Logger.Metadata`` from the current context.
|
||||
@usableFromInline
|
||||
internal let _provideMetadata: @Sendable () -> Metadata
|
||||
|
||||
/// Create a new `MetadataProvider`.
|
||||
/// Creates a new metadata provider.
|
||||
///
|
||||
/// - Parameter provideMetadata: A closure extracting metadata from the current execution context.
|
||||
/// - Parameter provideMetadata: A closure that extracts metadata from the current execution context.
|
||||
public init(_ provideMetadata: @escaping @Sendable () -> Metadata) {
|
||||
self._provideMetadata = provideMetadata
|
||||
}
|
||||
|
||||
/// Invoke the metadata provider and return the generated contextual ``Logger/Metadata``.
|
||||
/// Invokes the metadata provider and returns the generated contextual metadata.
|
||||
public func get() -> Metadata {
|
||||
self._provideMetadata()
|
||||
}
|
||||
@@ -77,7 +77,7 @@ extension Logger {
|
||||
}
|
||||
|
||||
extension Logger.MetadataProvider {
|
||||
/// A pseudo-`MetadataProvider` that can be used to merge metadata from multiple other `MetadataProvider`s.
|
||||
/// A pseudo metadata provider that merges metadata from multiple other metadata providers.
|
||||
///
|
||||
/// ### Merging conflicting keys
|
||||
///
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct InMemoryLogHandlerTests {
|
||||
@Test
|
||||
func collectsLogs() {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: ["key1": "value1", "key2": ["a", "b", "c"]]
|
||||
)
|
||||
]
|
||||
)
|
||||
}
|
||||
|
||||
@Test
|
||||
func metadataFromLoggerEndsUpInEntry() {
|
||||
var (logHandler, logger) = self.makeTestLogger()
|
||||
logger[metadataKey: "test"] = "value"
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: ["key1": "value1", "key2": ["a", "b", "c"], "test": "value"]
|
||||
)
|
||||
]
|
||||
)
|
||||
// Metadata also sticks onto the logger
|
||||
#expect(logger[metadataKey: "test"] == "value")
|
||||
}
|
||||
|
||||
@Test
|
||||
func moreSpecificMetadataOverridesGlobal() {
|
||||
let testProvider = Logger.MetadataProvider {
|
||||
["a": "1", "b": "1", "c": "1"]
|
||||
}
|
||||
var (logHandler, logger) = self.makeTestLogger(metadataProvider: testProvider)
|
||||
logger[metadataKey: "b"] = "2"
|
||||
logger[metadataKey: "c"] = "2"
|
||||
logger.info("hello", metadata: ["c": "3"])
|
||||
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(level: .info, message: "hello", metadata: ["a": "1", "b": "2", "c": "3"])
|
||||
]
|
||||
)
|
||||
}
|
||||
|
||||
@Test
|
||||
func clear() {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", metadata: ["key1": "value1", "key2": ["a", "b", "c"]])
|
||||
logHandler.clear()
|
||||
logger.info("hello2")
|
||||
|
||||
// Only hello2 is here
|
||||
#expect(
|
||||
logHandler.entries == [
|
||||
InMemoryLogHandler.Entry(level: .info, message: "hello2", metadata: [:])
|
||||
]
|
||||
)
|
||||
}
|
||||
|
||||
private func makeTestLogger(metadataProvider: Logger.MetadataProvider? = nil) -> (InMemoryLogHandler, Logger) {
|
||||
var logHandler = InMemoryLogHandler()
|
||||
logHandler.metadataProvider = metadataProvider
|
||||
let logger = Logger(
|
||||
label: "MyApp",
|
||||
factory: { _ in
|
||||
logHandler
|
||||
}
|
||||
)
|
||||
return (logHandler, logger)
|
||||
}
|
||||
}
|
||||
@@ -14,11 +14,11 @@
|
||||
|
||||
// Not testable
|
||||
import Logging
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
final class CompatibilityTest: XCTestCase {
|
||||
struct CompatibilityTest {
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
func testAllLogLevelsWorkWithOldSchoolLogHandlerWorks() {
|
||||
@Test func allLogLevelsWorkWithOldSchoolLogHandlerWorks() {
|
||||
let testLogging = OldSchoolTestLogging()
|
||||
|
||||
var logger = Logger(label: "\(#function)", factory: { testLogging.make(label: $0) })
|
||||
|
||||
@@ -12,24 +12,22 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import Dispatch
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if compiler(>=6.0) || canImport(Darwin)
|
||||
import Dispatch
|
||||
#else
|
||||
@preconcurrency import Dispatch
|
||||
#endif
|
||||
|
||||
class GlobalLoggerTest: XCTestCase {
|
||||
func test1() throws {
|
||||
/// This is the only test suite allowed to use global LoggingSystem bootstrapping,
|
||||
/// tests in the suite are executed one by one
|
||||
@Suite(.serialized)
|
||||
struct GlobalLoggerTest {
|
||||
@Test func traceAndAbove() throws {
|
||||
// bootstrap with our test logging impl
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config to log traces and above
|
||||
logging.config.set(value: Logger.Level.debug)
|
||||
// change test logging config to log trace and above
|
||||
logging.config.set(value: Logger.Level.trace)
|
||||
// run our program
|
||||
Struct1().doSomething()
|
||||
// test results
|
||||
@@ -45,12 +43,16 @@ class GlobalLoggerTest: XCTestCase {
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::Local", metadata: ["baz": "qux"])
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::end")
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomething::end")
|
||||
logging.history.assertExist(level: .trace, message: "Struct3::doSomething::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
logging.history.assertExist(level: .trace, message: "Struct1::doSomething::end::lastLine")
|
||||
|
||||
}
|
||||
|
||||
func test2() throws {
|
||||
@Test func errorAndAbove() throws {
|
||||
// bootstrap with our test logging impl
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
@@ -80,12 +82,15 @@ class GlobalLoggerTest: XCTestCase {
|
||||
)
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomething::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct3::doSomething::end::lastLine")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct1::doSomething::end::lastLine")
|
||||
}
|
||||
|
||||
func test3() throws {
|
||||
@Test func warningAndAbove() throws {
|
||||
// bootstrap with our test logging impl
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
@@ -119,6 +124,96 @@ class GlobalLoggerTest: XCTestCase {
|
||||
}
|
||||
}
|
||||
|
||||
/// MetadataProvider tests relying on the global state
|
||||
extension GlobalLoggerTest {
|
||||
@Test func loggingMergesOneOffMetadataWithProvidedMetadataFromExplicitlyPassed() throws {
|
||||
let logging = TestLogging()
|
||||
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
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"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func loggerWithoutFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider() {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
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"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func loggerWithPredefinedLibraryMetadataProvider() {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
metadataProvider: .exampleProvider
|
||||
)
|
||||
|
||||
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"]
|
||||
)
|
||||
}
|
||||
|
||||
@Test func loggerWithFactoryOverrideDefaultsToUsingLoggingSystemMetadataProvider() {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
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"]
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
private struct Struct1 {
|
||||
private let logger = Logger(label: "GlobalLoggerTest::Struct1")
|
||||
|
||||
@@ -132,6 +227,7 @@ private struct Struct1 {
|
||||
self.logger.debug("Struct1::doSomethingElse")
|
||||
Struct2().doSomething()
|
||||
self.logger.debug("Struct1::doSomethingElse::end")
|
||||
self.logger.trace("Struct1::doSomething::end::lastLine")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -148,6 +244,7 @@ private struct Struct2 {
|
||||
self.logger.info("Struct2::doSomethingElse")
|
||||
Struct3().doSomething()
|
||||
self.logger.debug("Struct2::doSomethingElse::end")
|
||||
self.logger.trace("Struct2::doSomethingElse::end::lastLine")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -159,6 +256,7 @@ private struct Struct3 {
|
||||
self.logger.error("Struct3::doSomething")
|
||||
self.doSomethingElse()
|
||||
self.logger.debug("Struct3::doSomething::end")
|
||||
self.logger.trace("Struct3::doSomething::end::lastLine")
|
||||
}
|
||||
|
||||
private func doSomethingElse() {
|
||||
|
||||
@@ -12,26 +12,21 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import Dispatch
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if compiler(>=6.0) || canImport(Darwin)
|
||||
import Dispatch
|
||||
#else
|
||||
@preconcurrency import Dispatch
|
||||
#endif
|
||||
|
||||
class LocalLoggerTest: XCTestCase {
|
||||
func test1() throws {
|
||||
// bootstrap with our test logging impl
|
||||
struct LocalLoggerTest {
|
||||
@Test func traceAndAbove() throws {
|
||||
// create test logging impl, do not bootstrap global LoggingSystem
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config to log traces and above
|
||||
logging.config.set(value: Logger.Level.debug)
|
||||
// change global test logging config to log trace and above,
|
||||
// local logging context will be modified to debug
|
||||
logging.config.set(value: Logger.Level.trace)
|
||||
// run our program
|
||||
let context = Context()
|
||||
let context = Context { logging.make(label: $0) }
|
||||
Struct1().doSomething(context: context)
|
||||
// test results
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomething", source: "LoggingTests")
|
||||
@@ -41,29 +36,33 @@ class LocalLoggerTest: XCTestCase {
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomething", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomethingElse", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .warning, message: "Struct3::doSomethingElseAsync", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .info, message: "TestLibrary::doSomething")
|
||||
logging.history.assertExist(level: .info, message: "TestLibrary::doSomethingAsync")
|
||||
logging.history.assertExist(
|
||||
level: .debug,
|
||||
message: "Struct3::doSomethingElse::Local",
|
||||
metadata: ["bar": "baz", "baz": "qux"]
|
||||
)
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::end", metadata: ["bar": "baz"])
|
||||
logging.history.assertNotExist(
|
||||
level: .trace,
|
||||
message: "Struct3::doSomethingElse::end::lastLine",
|
||||
metadata: ["bar": "baz"]
|
||||
)
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomething::end", metadata: ["bar": "baz"])
|
||||
logging.history.assertExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct1::doSomethingElse::end::lastLine")
|
||||
logging.history.assertExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
}
|
||||
|
||||
func test2() throws {
|
||||
// bootstrap with our test logging impl
|
||||
@Test func errorAndAbove() throws {
|
||||
// create test logging impl, do not bootstrap global LoggingSystem
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config to log errors and above
|
||||
logging.config.set(value: Logger.Level.error)
|
||||
// run our program
|
||||
let context = Context()
|
||||
let context = Context { logging.make(label: $0) }
|
||||
Struct1().doSomething(context: context)
|
||||
// test results
|
||||
// global context
|
||||
@@ -84,20 +83,27 @@ class LocalLoggerTest: XCTestCase {
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomething")
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomethingAsync")
|
||||
// hyper local context
|
||||
// hyper local .debug context
|
||||
logging.history.assertExist(
|
||||
level: .debug,
|
||||
message: "Struct3::doSomethingElse::Local",
|
||||
metadata: ["bar": "baz", "baz": "qux"]
|
||||
)
|
||||
// local context
|
||||
// local .debug context
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::end", metadata: ["bar": "baz"])
|
||||
// local context
|
||||
logging.history.assertNotExist(
|
||||
level: .trace,
|
||||
message: "Struct3::doSomethingElse::end::lastLine",
|
||||
metadata: ["bar": "baz"]
|
||||
)
|
||||
// local .debug context
|
||||
logging.history.assertExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct2::doSomethingElse::end::lastLine")
|
||||
// local context
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomething::end", metadata: ["bar": "baz"])
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .trace, message: "Struct1::doSomethingElse::end::lastLine")
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomething::end")
|
||||
}
|
||||
@@ -105,7 +111,11 @@ class LocalLoggerTest: XCTestCase {
|
||||
|
||||
// systems that follow the context pattern need to implement something like this
|
||||
private struct Context {
|
||||
var logger = Logger(label: "LocalLoggerTest::ContextLogger")
|
||||
var logger: Logger
|
||||
|
||||
init(_ factory: (String) -> any LogHandler) {
|
||||
self.logger = Logger(label: "LocalLoggerTest::ContextLogger", factory: factory)
|
||||
}
|
||||
|
||||
// since logger is a value type, we can reuse our copy to manage logLevel
|
||||
var logLevel: Logger.Level {
|
||||
@@ -152,6 +162,7 @@ private struct Struct2 {
|
||||
c.logger.info("Struct2::doSomethingElse")
|
||||
Struct3().doSomething(context: c)
|
||||
c.logger.debug("Struct2::doSomethingElse::end")
|
||||
c.logger.trace("Struct2::doSomethingElse::end::lastLine")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -164,6 +175,7 @@ private struct Struct3 {
|
||||
c.logger.error("Struct3::doSomething")
|
||||
self.doSomethingElse(context: c)
|
||||
c.logger.debug("Struct3::doSomething::end")
|
||||
c.logger.trace("Struct3::doSomething::end::lastLine")
|
||||
}
|
||||
|
||||
private func doSomethingElse(context: Context) {
|
||||
@@ -184,5 +196,6 @@ private struct Struct3 {
|
||||
l[metadataKey: "baz"] = "qux"
|
||||
l.debug("Struct3::doSomethingElse::Local")
|
||||
context.logger.debug("Struct3::doSomethingElse::end")
|
||||
context.logger.trace("Struct3::doSomethingElse::end::lastLine")
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -12,16 +12,12 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
import Dispatch
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
class MDCTest: XCTestCase {
|
||||
func test1() throws {
|
||||
// bootstrap with our test logger
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
struct MDCTest {
|
||||
@Test func test() throws {
|
||||
// run the program
|
||||
MDC.global["foo"] = "bar"
|
||||
let group = DispatchGroup()
|
||||
@@ -36,20 +32,20 @@ class MDCTest: XCTestCase {
|
||||
for i in 0...remove {
|
||||
MDC.global["key-\(i)"] = nil
|
||||
}
|
||||
XCTAssertEqual(add - remove, MDC.global.metadata.count, "expected number of entries to match")
|
||||
#expect((add - remove) == MDC.global.metadata.count, "expected number of entries to match")
|
||||
for i in remove + 1...add {
|
||||
XCTAssertNotNil(MDC.global["key-\(i)"], "expecting value for key-\(i)")
|
||||
#expect(MDC.global["key-\(i)"] != nil, "expecting value for key-\(i)")
|
||||
}
|
||||
for i in 0...remove {
|
||||
XCTAssertNil(MDC.global["key-\(i)"], "not expecting value for key-\(i)")
|
||||
#expect(MDC.global["key-\(i)"] == nil, "not expecting value for key-\(i)")
|
||||
}
|
||||
MDC.global.clear()
|
||||
group.leave()
|
||||
}
|
||||
}
|
||||
group.wait()
|
||||
XCTAssertEqual(MDC.global["foo"], "bar", "expecting to find top items")
|
||||
#expect(MDC.global["foo"] == "bar", "expecting to find top items")
|
||||
MDC.global["foo"] = nil
|
||||
XCTAssertTrue(MDC.global.metadata.isEmpty, "MDC should be empty")
|
||||
#expect(MDC.global.metadata.isEmpty, "MDC should be empty")
|
||||
}
|
||||
}
|
||||
@@ -12,7 +12,7 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
@@ -26,36 +26,8 @@ import Android
|
||||
import Glibc
|
||||
#endif
|
||||
|
||||
final class MetadataProviderTest: XCTestCase {
|
||||
func testLoggingMergesOneOffMetadataWithProvidedMetadataFromExplicitlyPassed() throws {
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(
|
||||
{ logging.makeWithMetadataProvider(label: $0, metadataProvider: $1) },
|
||||
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() {
|
||||
struct MetadataProviderTest {
|
||||
@Test func logHandlerThatDidNotImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
#if DEBUG
|
||||
// we only emit these warnings in debug mode
|
||||
let logging = TestLogging()
|
||||
@@ -72,11 +44,11 @@ final class MetadataProviderTest: XCTestCase {
|
||||
|
||||
let countBefore = logging.history.entries.count
|
||||
handler.metadataProvider = .simpleTestProvider
|
||||
XCTAssertEqual(countBefore, logging.history.entries.count, "Should only log the warning once")
|
||||
#expect(countBefore == logging.history.entries.count, "Should only log the warning once")
|
||||
#endif
|
||||
}
|
||||
|
||||
func testLogHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
@Test func logHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
#if DEBUG
|
||||
// we only emit these warnings in debug mode
|
||||
let logging = TestLogging()
|
||||
|
||||
@@ -12,21 +12,17 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Dispatch
|
||||
import Foundation
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if os(Windows)
|
||||
import WinSDK
|
||||
#endif
|
||||
#if compiler(>=6.0) || canImport(Darwin)
|
||||
import Dispatch
|
||||
#else
|
||||
@preconcurrency import Dispatch
|
||||
#endif
|
||||
|
||||
internal struct TestLogging {
|
||||
struct TestLogging {
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
|
||||
@@ -237,17 +233,17 @@ extension History {
|
||||
message: String,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #filePath,
|
||||
file: String = #filePath,
|
||||
fileID: String = #fileID,
|
||||
line: UInt = #line
|
||||
line: Int = #line,
|
||||
column: Int = #column
|
||||
) {
|
||||
let source = source ?? Logger.currentModule(fileID: "\(fileID)")
|
||||
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
|
||||
XCTAssertNotNil(
|
||||
entry,
|
||||
#expect(
|
||||
entry != nil,
|
||||
"entry not found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file,
|
||||
line: line
|
||||
sourceLocation: SourceLocation(fileID: fileID, filePath: file, line: line, column: column)
|
||||
)
|
||||
}
|
||||
|
||||
@@ -256,17 +252,17 @@ extension History {
|
||||
message: String,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #filePath,
|
||||
file: String = #filePath,
|
||||
fileID: String = #file,
|
||||
line: UInt = #line
|
||||
line: Int = #line,
|
||||
column: Int = #column
|
||||
) {
|
||||
let source = source ?? Logger.currentModule(fileID: "\(fileID)")
|
||||
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
|
||||
XCTAssertNil(
|
||||
entry,
|
||||
#expect(
|
||||
entry == nil,
|
||||
"entry was found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file,
|
||||
line: line
|
||||
sourceLocation: SourceLocation(fileID: fileID, filePath: file, line: line, column: column)
|
||||
)
|
||||
}
|
||||
|
||||
@@ -306,6 +302,7 @@ extension History {
|
||||
}
|
||||
}
|
||||
|
||||
/// MDC stands for Mapped Diagnostic Context
|
||||
public class MDC {
|
||||
private let lock = NSLock()
|
||||
private var storage = [Int: Logger.Metadata]()
|
||||
@@ -384,16 +381,6 @@ public class MDC {
|
||||
}
|
||||
}
|
||||
|
||||
extension NSLock {
|
||||
func withLock<T>(_ body: () -> T) -> T {
|
||||
self.lock()
|
||||
defer {
|
||||
self.unlock()
|
||||
}
|
||||
return body()
|
||||
}
|
||||
}
|
||||
|
||||
internal struct TestLibrary: Sendable {
|
||||
private let logger = Logger(label: "TestLibrary")
|
||||
private let queue = DispatchQueue(label: "TestLibrary")
|
||||
|
||||
@@ -12,16 +12,20 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
class SendableTest: XCTestCase {
|
||||
func testSendableLogger() async {
|
||||
struct SendableTest {
|
||||
@Test func sendableLogger() async {
|
||||
let testLogging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal { testLogging.make(label: $0) }
|
||||
|
||||
let logger = Logger(label: "test")
|
||||
let logger = Logger(
|
||||
label: "test",
|
||||
factory: {
|
||||
testLogging.make(label: $0)
|
||||
}
|
||||
)
|
||||
let message1 = Logger.Message(stringLiteral: "critical 1")
|
||||
let message2 = Logger.Message(stringLiteral: "critical 2")
|
||||
let metadata: Logger.Metadata = ["key": "value"]
|
||||
|
||||
Reference in new issue
Block a user