mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
Compare commits
138
Commits
tomerd-patch-1
...
1.12.0
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
5073617dac | ||
|
|
6f3fbace66 | ||
|
|
41f6c72707 | ||
|
|
bffceaf778 | ||
|
|
6558438e46 | ||
|
|
7c04f86fba | ||
|
|
8c0f217f01 | ||
|
|
f4f84c9f26 | ||
|
|
1f38a59922 | ||
|
|
39e14910f6 | ||
|
|
63ee499927 | ||
|
|
c9ceb519e7 | ||
|
|
154acdf7d4 | ||
|
|
b93451412b | ||
|
|
c5f42781c4 | ||
|
|
4f1022c5cd | ||
|
|
f22537f94d | ||
|
|
185a56a488 | ||
|
|
bbd81b6725 | ||
|
|
8fb4e7147d | ||
|
|
d5dbc04d53 | ||
|
|
47ef0ec6a4 | ||
|
|
7d6d55f9ed | ||
|
|
8f634e4e68 | ||
|
|
2778fd4e5a | ||
|
|
0d9c9ae808 | ||
|
|
a92ccc626c | ||
|
|
7ee16e4656 | ||
|
|
1ccd2c5a27 | ||
|
|
477fab4170 | ||
|
|
bc386b95f2 | ||
|
|
6856e42a3f | ||
|
|
cdaa5ac879 | ||
|
|
b1fa4ef41f | ||
|
|
63eaca6f4d | ||
|
|
f3a82f1119 | ||
|
|
6b380c9f4b | ||
|
|
ca538143e2 | ||
|
|
3612813963 | ||
|
|
95a70b954c | ||
|
|
dea0abb603 | ||
|
|
4121d24dbd | ||
|
|
a90a3d1c37 | ||
|
|
2a4139ef2a | ||
|
|
bd44c73045 | ||
|
|
45b82c6e24 | ||
|
|
1be2c17b80 | ||
|
|
21d132f1ca | ||
|
|
ce592ae52f | ||
|
|
e1600be8ec | ||
|
|
cbd28c274b | ||
|
|
c05d67286c | ||
|
|
2281e43060 | ||
|
|
81d3d07f14 | ||
|
|
09c99dd25a | ||
|
|
748d1eb5d9 | ||
|
|
765db8bc47 | ||
|
|
222bf1b48b | ||
|
|
3d8596ed08 | ||
|
|
3a9d8c908f | ||
|
|
2dd04b00f4 | ||
|
|
770059c51d | ||
|
|
f82ce9631f | ||
|
|
9576fd5710 | ||
|
|
8f746b0f16 | ||
|
|
6efb781a29 | ||
|
|
9e1494a076 | ||
|
|
960b23e33f | ||
|
|
18cc7907d6 | ||
|
|
9bc47c93fa | ||
|
|
96a2f8a0fa | ||
|
|
0e75c43ee4 | ||
|
|
5f816304f9 | ||
|
|
1efe6f8129 | ||
|
|
ee1bfd3f47 | ||
|
|
da3fdd167f | ||
|
|
d03205626d | ||
|
|
2cb03fa60e | ||
|
|
db86ac725b | ||
|
|
9cb486020e | ||
|
|
b3a6373077 | ||
|
|
4bcd3dfb11 | ||
|
|
7adcf9aa15 | ||
|
|
f5312694b3 | ||
|
|
6553ef5893 | ||
|
|
11e749ea6d | ||
|
|
d16e216341 | ||
|
|
0f170b4764 | ||
|
|
23517234d5 | ||
|
|
c7dcb55fb9 | ||
|
|
ebb05e0317 | ||
|
|
b1617b3c0c | ||
|
|
c1ff8be7bc | ||
|
|
e97a6fcb1a | ||
|
|
4587ac512c | ||
|
|
f447991bd2 | ||
|
|
86ee8ef09e | ||
|
|
cb28750240 | ||
|
|
532d8b5295 | ||
|
|
f8ce47d3b0 | ||
|
|
1ef0345e1e | ||
|
|
5996c7a1b4 | ||
|
|
1aacf8affa | ||
|
|
bd5ff0d8e4 | ||
|
|
f79ba6a75f | ||
|
|
6763fd0b73 | ||
|
|
32e8d72446 | ||
|
|
b2eff1c427 | ||
|
|
ba2a9f5b93 | ||
|
|
3e3ef75109 | ||
|
|
bd4519f1c2 | ||
|
|
e6ca651cbc | ||
|
|
dc77805fdc | ||
|
|
e979c6945c | ||
|
|
d86803715f | ||
|
|
f7b7977065 | ||
|
|
ce09fe6dac | ||
|
|
a8e1148aa5 | ||
|
|
483e2bbcdd | ||
|
|
d5bf59c6b2 | ||
|
|
6fe203dc33 | ||
|
|
6b0ccb1ca8 | ||
|
|
8fc79cae9d | ||
|
|
f2e8667d50 | ||
|
|
9f3731aa55 | ||
|
|
2bf6215b68 | ||
|
|
432a93204e | ||
|
|
dc6dd5caaa | ||
|
|
5db2bc495a | ||
|
|
4e75f88c6a | ||
|
|
77192b9e21 | ||
|
|
b172d1ae3d | ||
|
|
a7e6d7fef5 | ||
|
|
9cdea8c2af | ||
|
|
d8af258aec | ||
|
|
02770d91fc | ||
|
|
7ebe44cb03 | ||
|
|
65a8e5e921 |
No files matched your search
@@ -0,0 +1,8 @@
|
||||
root = true
|
||||
|
||||
[*]
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
@@ -0,0 +1,6 @@
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
@@ -0,0 +1,14 @@
|
||||
changelog:
|
||||
categories:
|
||||
- title: SemVer Major
|
||||
labels:
|
||||
- ⚠️ semver/major
|
||||
- title: SemVer Minor
|
||||
labels:
|
||||
- 🆕 semver/minor
|
||||
- title: SemVer Patch
|
||||
labels:
|
||||
- 🔨 semver/patch
|
||||
- title: Other Changes
|
||||
labels:
|
||||
- semver/none
|
||||
@@ -0,0 +1,12 @@
|
||||
name: Auto Release
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: read
|
||||
|
||||
jobs:
|
||||
auto-release:
|
||||
uses: apple/swift-temporal-sdk/.github/workflows/auto-release.yml@main
|
||||
@@ -0,0 +1,96 @@
|
||||
name: Main
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
schedule:
|
||||
- cron: "0 8,20 * * *"
|
||||
|
||||
jobs:
|
||||
unit-tests:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
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_6_3_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_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
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_6_3_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"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks (NoTraits)
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/NoTraits"
|
||||
macos_xcode_16_4_enabled: true
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
macos-benchmarks-MaxLogLevelWarningBenchmarks-trait:
|
||||
name: macOS benchmarks (MaxLogLevelWarning)
|
||||
needs: macos-benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
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
|
||||
|
||||
macos-tests:
|
||||
name: macOS tests
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
runner_pool: nightly
|
||||
build_scheme: swift-log-Package
|
||||
debug_output_enabled: true
|
||||
xcode_16_3_enabled: false
|
||||
xcode_16_4_enabled: false
|
||||
xcode_26_0_enabled: false
|
||||
xcode_26_1_enabled: false
|
||||
xcode_26_2_enabled: false
|
||||
swift_6_1_enabled: true
|
||||
swift_6_2_enabled: true
|
||||
swift_6_3_enabled: true
|
||||
macos_xcode_test_enabled: false
|
||||
ios_xcode_test_enabled: false
|
||||
watchos_xcode_test_enabled: false
|
||||
tvos_xcode_test_enabled: false
|
||||
visionos_xcode_test_enabled: false
|
||||
|
||||
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_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
@@ -0,0 +1,90 @@
|
||||
name: PR
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, reopened, synchronize]
|
||||
|
||||
jobs:
|
||||
soundness:
|
||||
name: Soundness
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.9
|
||||
with:
|
||||
license_header_check_project_name: "Swift Logging API"
|
||||
|
||||
unit-tests:
|
||||
name: Unit tests
|
||||
uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
|
||||
with:
|
||||
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_6_3_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_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_enabled: true
|
||||
windows_nightly_next_enabled: true
|
||||
windows_nightly_main_enabled: true
|
||||
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_6_3_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"
|
||||
|
||||
macos-benchmarks:
|
||||
name: macOS benchmarks (NoTraits)
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/NoTraits"
|
||||
macos_runner_pool: general
|
||||
macos_xcode_16_4_enabled: true
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
macos-benchmarks-MaxLogLevelWarningBenchmarks-trait:
|
||||
name: macOS benchmarks (MaxLogLevelWarning)
|
||||
# Workaround for reusing the same benchmarks.yml workflow
|
||||
needs: macos-benchmarks
|
||||
uses: apple/swift-nio/.github/workflows/macos_benchmarks.yml@main
|
||||
with:
|
||||
benchmark_package_path: "Benchmarks/MaxLogLevelWarning"
|
||||
macos_runner_pool: general
|
||||
macos_xcode_26_1_enabled: true
|
||||
|
||||
cxx-interop:
|
||||
name: Cxx interop
|
||||
uses: apple/swift-nio/.github/workflows/cxx_interop.yml@main
|
||||
|
||||
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
|
||||
|
||||
macos-tests:
|
||||
name: macOS tests
|
||||
uses: apple/swift-nio/.github/workflows/macos_tests.yml@main
|
||||
with:
|
||||
runner_pool: general
|
||||
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_1_enabled: true
|
||||
windows_6_2_enabled: true
|
||||
windows_6_3_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
|
||||
@@ -0,0 +1,21 @@
|
||||
name: PR label
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [labeled, unlabeled, opened, reopened, synchronize]
|
||||
|
||||
jobs:
|
||||
semver-label-check:
|
||||
name: Semantic version label check
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 1
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v6
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Check for Semantic Version label
|
||||
uses: apple/swift-nio/.github/actions/pull_request_semver_label_checker@main
|
||||
@@ -1,4 +1,5 @@
|
||||
.DS_Store
|
||||
Package.resolved
|
||||
/.build
|
||||
/Packages
|
||||
/*.xcodeproj
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
.gitignore
|
||||
**/.gitignore
|
||||
.licenseignore
|
||||
.unacceptablelanguageignore
|
||||
.gitattributes
|
||||
.git-blame-ignore-revs
|
||||
.mailfilter
|
||||
.mailmap
|
||||
.spi.yml
|
||||
.swift-format
|
||||
.editorconfig
|
||||
.github/*
|
||||
*.md
|
||||
*.txt
|
||||
*.yml
|
||||
*.yaml
|
||||
*.json
|
||||
Package.swift
|
||||
**/Package.swift
|
||||
Package@-*.swift
|
||||
**/Package@-*.swift
|
||||
Package@swift-*.swift
|
||||
**/Package@swift-*.swift
|
||||
Package.resolved
|
||||
**/Package.resolved
|
||||
Makefile
|
||||
*.modulemap
|
||||
**/*.modulemap
|
||||
**/*.docc/*
|
||||
*.xcprivacy
|
||||
**/*.xcprivacy
|
||||
*.symlink
|
||||
**/*.symlink
|
||||
Dockerfile
|
||||
**/Dockerfile
|
||||
Snippets/*
|
||||
dev/git.commit.template
|
||||
dev/update-benchmark-thresholds
|
||||
*.crt
|
||||
**/*.crt
|
||||
*.pem
|
||||
**/*.pem
|
||||
*.der
|
||||
**/*.der
|
||||
@@ -0,0 +1,4 @@
|
||||
version: 1
|
||||
builder:
|
||||
configs:
|
||||
- documentation_targets: [Logging]
|
||||
@@ -0,0 +1,62 @@
|
||||
{
|
||||
"version" : 1,
|
||||
"indentation" : {
|
||||
"spaces" : 4
|
||||
},
|
||||
"tabWidth" : 4,
|
||||
"fileScopedDeclarationPrivacy" : {
|
||||
"accessLevel" : "private"
|
||||
},
|
||||
"spacesAroundRangeFormationOperators" : false,
|
||||
"indentConditionalCompilationBlocks" : false,
|
||||
"indentSwitchCaseLabels" : false,
|
||||
"lineBreakAroundMultilineExpressionChainComponents" : false,
|
||||
"lineBreakBeforeControlFlowKeywords" : false,
|
||||
"lineBreakBeforeEachArgument" : true,
|
||||
"lineBreakBeforeEachGenericRequirement" : true,
|
||||
"lineLength" : 120,
|
||||
"maximumBlankLines" : 1,
|
||||
"respectsExistingLineBreaks" : true,
|
||||
"prioritizeKeepingFunctionOutputTogether" : true,
|
||||
"rules" : {
|
||||
"AllPublicDeclarationsHaveDocumentation" : false,
|
||||
"AlwaysUseLiteralForEmptyCollectionInit" : false,
|
||||
"AlwaysUseLowerCamelCase" : false,
|
||||
"AmbiguousTrailingClosureOverload" : true,
|
||||
"BeginDocumentationCommentWithOneLineSummary" : false,
|
||||
"DoNotUseSemicolons" : true,
|
||||
"DontRepeatTypeInStaticProperties" : true,
|
||||
"FileScopedDeclarationPrivacy" : true,
|
||||
"FullyIndirectEnum" : true,
|
||||
"GroupNumericLiterals" : true,
|
||||
"IdentifiersMustBeASCII" : true,
|
||||
"NeverForceUnwrap" : false,
|
||||
"NeverUseForceTry" : false,
|
||||
"NeverUseImplicitlyUnwrappedOptionals" : false,
|
||||
"NoAccessLevelOnExtensionDeclaration" : true,
|
||||
"NoAssignmentInExpressions" : true,
|
||||
"NoBlockComments" : true,
|
||||
"NoCasesWithOnlyFallthrough" : true,
|
||||
"NoEmptyTrailingClosureParentheses" : true,
|
||||
"NoLabelsInCasePatterns" : true,
|
||||
"NoLeadingUnderscores" : false,
|
||||
"NoParensAroundConditions" : true,
|
||||
"NoVoidReturnOnFunctionSignature" : true,
|
||||
"OmitExplicitReturns" : true,
|
||||
"OneCasePerLine" : true,
|
||||
"OneVariableDeclarationPerLine" : true,
|
||||
"OnlyOneTrailingClosureArgument" : true,
|
||||
"OrderedImports" : true,
|
||||
"ReplaceForEachWithForLoop" : true,
|
||||
"ReturnVoidInsteadOfEmptyTuple" : true,
|
||||
"UseEarlyExits" : false,
|
||||
"UseExplicitNilCheckInConditions" : false,
|
||||
"UseLetInEveryBoundCaseVariable" : false,
|
||||
"UseShorthandTypeNames" : true,
|
||||
"UseSingleLinePropertyGetter" : false,
|
||||
"UseSynthesizedInitializer" : false,
|
||||
"UseTripleSlashForDocumentationComments" : true,
|
||||
"UseWhereClausesInForLoops" : false,
|
||||
"ValidateDocumentationComments" : false
|
||||
}
|
||||
}
|
||||
@@ -1,15 +0,0 @@
|
||||
# file options
|
||||
|
||||
--swiftversion 5.0
|
||||
--exclude .build
|
||||
|
||||
# format options
|
||||
|
||||
--self insert
|
||||
--patternlet inline
|
||||
--stripunusedargs unnamed-only
|
||||
--ifdef no-indent
|
||||
|
||||
# rules
|
||||
|
||||
--disable redundantParens # https://github.com/nicklockwood/SwiftFormat/issues/638
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Benchmark
|
||||
import BenchmarksFactory
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public let benchmarks: @Sendable () -> Void = {
|
||||
makeBenchmark(loggerLevel: .notice, logLevel: .notice) { logger in
|
||||
logger.notice("hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .notice, logLevel: .notice, "_generic") { logger in
|
||||
logger.log(level: .notice, "hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .warning, logLevel: .warning) { logger in
|
||||
logger.warning("hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .warning, logLevel: .warning, "_generic") { logger in
|
||||
logger.log(level: .warning, "hello, benchmarking world")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
// swift-tools-version: 6.1
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "MaxLogLevelWarning",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
products: [
|
||||
.executable(name: "MaxLogLevelWarning", targets: ["MaxLogLevelWarning"])
|
||||
],
|
||||
dependencies: [
|
||||
// swift-log
|
||||
.package(
|
||||
path: "../../",
|
||||
traits: ["MaxLogLevelWarning"]
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "MaxLogLevelWarning",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/MaxLogLevelWarningBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 619,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 619,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1651,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1651,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/configuration/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
@@ -0,0 +1,27 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Benchmark
|
||||
import BenchmarksFactory
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public let benchmarks: @Sendable () -> Void = {
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .error, "_generic") { logger in
|
||||
logger.log(level: .error, "hello, benchmarking world")
|
||||
}
|
||||
makeBenchmark(loggerLevel: .error, logLevel: .debug, "_generic") { logger in
|
||||
logger.log(level: .debug, "hello, benchmarking world")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
// swift-tools-version:6.1
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "NoTraits",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
products: [
|
||||
.executable(name: "NoTraits", targets: ["NoTraits"])
|
||||
],
|
||||
dependencies: [
|
||||
// swift-log
|
||||
.package(
|
||||
path: "../../"
|
||||
),
|
||||
// Parent Benchmarks
|
||||
.package(name: "Benchmarks", path: "../"),
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
],
|
||||
targets: [
|
||||
.executableTarget(
|
||||
name: "NoTraits",
|
||||
dependencies: [
|
||||
.product(name: "BenchmarksFactory", package: "Benchmarks"),
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
],
|
||||
path: "Benchmarks/NoTraitsBenchmarks",
|
||||
plugins: [
|
||||
.plugin(name: "BenchmarkPlugin", package: "package-benchmark")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 984,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1368,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 893,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"instructions" : 1649,
|
||||
"objectAllocCount" : 0
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
// swift-tools-version:6.1
|
||||
// The swift-tools-version declares the minimum version of Swift required to build this package.
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "BenchmarksFactory",
|
||||
platforms: [
|
||||
.macOS(.v13)
|
||||
],
|
||||
products: [
|
||||
.library(name: "BenchmarksFactory", targets: ["BenchmarksFactory"])
|
||||
],
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/ordo-one/package-benchmark.git", from: "1.29.6"),
|
||||
.package(path: "../"), // swift-log
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "BenchmarksFactory",
|
||||
dependencies: [
|
||||
.product(name: "Benchmark", package: "package-benchmark"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
@@ -0,0 +1,55 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2025 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Benchmark
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public func makeBenchmark(
|
||||
loggerLevel: Logger.Level,
|
||||
logLevel: Logger.Level,
|
||||
_ suffix: String = "",
|
||||
_ body: @escaping (Logger) -> Void
|
||||
) {
|
||||
let iterations = 1_000_000
|
||||
let metrics: [BenchmarkMetric] = [.instructions, .objectAllocCount]
|
||||
|
||||
var logger = Logger(label: "BenchmarkRunner_\(loggerLevel)_\(logLevel)")
|
||||
|
||||
// Use a NoOpLogHandler to avoid polluting the logs
|
||||
logger.handler = NoOpLogHandler(label: "NoOpLogHandler")
|
||||
logger.logLevel = loggerLevel
|
||||
|
||||
Benchmark(
|
||||
"\(logLevel)_log_with_\(loggerLevel)_log_level\(suffix)",
|
||||
configuration: .init(
|
||||
metrics: metrics,
|
||||
maxIterations: iterations,
|
||||
thresholds: [
|
||||
.instructions: BenchmarkThresholds(
|
||||
relative: [
|
||||
.p90: 1.0 // we only record p90
|
||||
]
|
||||
),
|
||||
.objectAllocCount: BenchmarkThresholds(
|
||||
absolute: [
|
||||
.p90: 0 // we only record p90
|
||||
]
|
||||
),
|
||||
]
|
||||
)
|
||||
) { _ in
|
||||
body(logger)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(
|
||||
event: LogEvent
|
||||
) {
|
||||
// Do nothing
|
||||
}
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
+1
-53
@@ -1,55 +1,3 @@
|
||||
# Code of Conduct
|
||||
To be a truly great community, SwiftLog needs to welcome developers from all walks of life,
|
||||
with different backgrounds, and with a wide range of experience. A diverse and friendly
|
||||
community will have more great ideas, more unique perspectives, and produce more great
|
||||
code. We will work diligently to make the SwiftLog community welcoming to everyone.
|
||||
|
||||
To give clarity of what is expected of our members, SwiftLog has adopted the code of conduct
|
||||
defined by [contributor-covenant.org](https://www.contributor-covenant.org). This document is used across many open source
|
||||
communities, and we think it articulates our values well. The full text is copied below:
|
||||
|
||||
### Contributor Code of Conduct v1.3
|
||||
As contributors and maintainers of this project, and in the interest of fostering an open and
|
||||
welcoming community, we pledge to respect all people who contribute through reporting
|
||||
issues, posting feature requests, updating documentation, submitting pull requests or patches,
|
||||
and other activities.
|
||||
|
||||
We are committed to making participation in this project a harassment-free experience for
|
||||
everyone, regardless of level of experience, gender, gender identity and expression, sexual
|
||||
orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or
|
||||
nationality.
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
- The use of sexualized language or imagery
|
||||
- Personal attacks
|
||||
- Trolling or insulting/derogatory comments
|
||||
- Public or private harassment
|
||||
- Publishing other’s private information, such as physical or electronic addresses, without explicit permission
|
||||
- Other unethical or unprofessional conduct
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments,
|
||||
commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of
|
||||
Conduct, or to ban temporarily or permanently any contributor for other behaviors that they
|
||||
deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
By adopting this Code of Conduct, project maintainers commit themselves to fairly and
|
||||
consistently applying these principles to every aspect of managing this project. Project
|
||||
maintainers who do not follow or enforce the Code of Conduct may be permanently removed
|
||||
from the project team.
|
||||
|
||||
This code of conduct applies both within project spaces and in public spaces when an
|
||||
individual is representing the project or its community.
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by
|
||||
contacting a project maintainer at [swift-log-conduct@group.apple.com](mailto:swift-log-conduct@group.apple.com). All complaints will be reviewed and
|
||||
investigated and will result in a response that is deemed necessary and appropriate to the
|
||||
circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter
|
||||
of an incident.
|
||||
|
||||
*This policy is adapted from the Contributor Code of Conduct [version 1.3.0](https://contributor-covenant.org/version/1/3/0/).*
|
||||
|
||||
### Reporting
|
||||
A working group of community members is committed to promptly addressing any [reported issues](mailto:swift-server-conduct@group.apple.com).
|
||||
Working group members are volunteers appointed by the project lead, with a
|
||||
preference for individuals with varied backgrounds and perspectives. Membership is expected
|
||||
to change regularly, and may grow or shrink.
|
||||
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
|
||||
+51
-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,35 +64,62 @@ 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
|
||||
|
||||
Please open a pull request at https://github.com/apple/swift-log. Make sure the CI passes, and then wait for code review.
|
||||
|
||||
|
||||
## Automated release process
|
||||
|
||||
This repository uses automated releases based on semantic versioning labels. See the [Auto Release Workflow documentation](https://github.com/apple/swift-temporal-sdk/blob/main/.github/workflows/README.md) for details.
|
||||
@@ -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.
|
||||
|
||||
|
||||
+53
-1
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version:5.0
|
||||
// swift-tools-version:6.2
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
@@ -19,15 +19,67 @@ let package = Package(
|
||||
name: "swift-log",
|
||||
products: [
|
||||
.library(name: "Logging", targets: ["Logging"]),
|
||||
.library(name: "InMemoryLogging", targets: ["InMemoryLogging"]),
|
||||
],
|
||||
traits: [
|
||||
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
|
||||
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
|
||||
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
|
||||
.trait(
|
||||
name: "MaxLogLevelWarning",
|
||||
description: "Warning and above available (compiles out trace, debug, info, notice)"
|
||||
),
|
||||
.trait(
|
||||
name: "MaxLogLevelError",
|
||||
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
|
||||
),
|
||||
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
|
||||
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
|
||||
|
||||
// By default, no traits are enabled (all log levels available)
|
||||
.default(enabledTraits: []),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "Logging",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "InMemoryLogging",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "LoggingTests",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "InMemoryLoggingTests",
|
||||
dependencies: ["InMemoryLogging", "Logging"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
for target in package.targets
|
||||
where [.executable, .test, .regular].contains(
|
||||
target.type
|
||||
) {
|
||||
var settings = target.swiftSettings ?? []
|
||||
|
||||
// https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md
|
||||
// Require `any` for existential types.
|
||||
settings.append(.enableUpcomingFeature("ExistentialAny"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
|
||||
settings.append(.enableUpcomingFeature("MemberImportVisibility"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
|
||||
settings.append(.enableUpcomingFeature("InternalImportsByDefault"))
|
||||
|
||||
// https://docs.swift.org/compiler/documentation/diagnostics/nonisolated-nonsending-by-default/
|
||||
settings.append(.enableUpcomingFeature("NonisolatedNonsendingByDefault"))
|
||||
|
||||
// Ensure all public types are explicitly annotated as Sendable or not Sendable.
|
||||
settings.append(.unsafeFlags(["-Xfrontend", "-require-explicit-sendable"]))
|
||||
|
||||
target.swiftSettings = settings
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
// swift-tools-version:6.1
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-log",
|
||||
products: [
|
||||
.library(name: "Logging", targets: ["Logging"]),
|
||||
.library(name: "InMemoryLogging", targets: ["InMemoryLogging"]),
|
||||
],
|
||||
traits: [
|
||||
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
|
||||
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
|
||||
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
|
||||
.trait(
|
||||
name: "MaxLogLevelWarning",
|
||||
description: "Warning and above available (compiles out trace, debug, info, notice)"
|
||||
),
|
||||
.trait(
|
||||
name: "MaxLogLevelError",
|
||||
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
|
||||
),
|
||||
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
|
||||
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
|
||||
|
||||
// By default, no traits are enabled (all log levels available)
|
||||
.default(enabledTraits: []),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "Logging",
|
||||
dependencies: []
|
||||
),
|
||||
.target(
|
||||
name: "InMemoryLogging",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "LoggingTests",
|
||||
dependencies: ["Logging"]
|
||||
),
|
||||
.testTarget(
|
||||
name: "InMemoryLoggingTests",
|
||||
dependencies: ["InMemoryLogging", "Logging"]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
for target in package.targets
|
||||
where [.executable, .test, .regular].contains(
|
||||
target.type
|
||||
) {
|
||||
var settings = target.swiftSettings ?? []
|
||||
|
||||
// https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md
|
||||
// Require `any` for existential types.
|
||||
settings.append(.enableUpcomingFeature("ExistentialAny"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md
|
||||
settings.append(.enableUpcomingFeature("MemberImportVisibility"))
|
||||
|
||||
// https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
|
||||
settings.append(.enableUpcomingFeature("InternalImportsByDefault"))
|
||||
|
||||
target.swiftSettings = settings
|
||||
}
|
||||
@@ -1,212 +1,64 @@
|
||||
# SwiftLog
|
||||
|
||||
First things first: This is the beginning of a community-driven open-source project actively seeking contributions, be it code, documentation, or ideas. Apart from contributing to `SwiftLog` itself, there's another huge gap at the moment: `SwiftLog` is an _API package_ which tries to establish a common API the ecosystem can use. To make logging really work for real-world workloads, we need `SwiftLog`-compatible _logging backends_ which then either persist the log messages in files, render them in nicer colors on the terminal, or send them over to Splunk or ELK.
|
||||
This repository contains a logging API implementation for Swift.
|
||||
SwiftLog provides a unified, performant, and ergonomic logging API that can be
|
||||
adopted by libraries and applications across the Swift ecosystem.
|
||||
|
||||
What `SwiftLog` provides today can be found in the [API docs][api-docs].
|
||||
- 📚 **Documentation** and **tutorials** are available on the [Swift Package Index](https://swiftpackageindex.com/apple/swift-log)
|
||||
- 🚀 **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- 🪪 **License** is Apache 2.0, repeated in [LICENSE.txt](LICENSE.txt)
|
||||
- 🔒 **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md)
|
||||
- 🔀 **Available Logging Backends**: SwiftLog is an API package - you'll want to
|
||||
choose from the many
|
||||
[community-maintained logging backends](#available-log-handler-backends) for production use
|
||||
|
||||
## Getting started
|
||||
## Quick Start
|
||||
|
||||
If you have a server-side Swift application, or maybe a cross-platform (for example Linux & macOS) app/library, and you would like to log, we think targeting this logging API package is a great idea. Below you'll find all you need to know to get started.
|
||||
|
||||
#### Adding the dependency
|
||||
|
||||
`SwiftLog` is designed for Swift 5. To depend on the logging API package, you need to declare your dependency in your `Package.swift`:
|
||||
The following snippet shows how to add SwiftLog to your Swift Package:
|
||||
|
||||
```swift
|
||||
.package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"),
|
||||
// swift-tools-version: 6.1
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "YourApp",
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/apple/swift-log", from: "1.6.0")
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "YourApp",
|
||||
dependencies: [
|
||||
.product(name: "Logging", package: "swift-log")
|
||||
]
|
||||
)
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
and to your application/library target, add `"Logging"` to your `dependencies`, e.g. like this:
|
||||
Then start logging:
|
||||
|
||||
```swift
|
||||
// Target syntax for Swift up to version 5.1
|
||||
.target(name: "BestExampleApp", dependencies: ["Logging"]),
|
||||
|
||||
// Target for Swift 5.2
|
||||
.target(name: "BestExampleApp", dependencies: [
|
||||
.product(name: "Logging", package: "swift-log")
|
||||
],
|
||||
```
|
||||
|
||||
|
||||
#### Let's log
|
||||
|
||||
```swift
|
||||
// 1) let's import the logging API package
|
||||
import Logging
|
||||
|
||||
// 2) we need to create a logger, the label works similarly to a DispatchQueue label
|
||||
let logger = Logger(label: "com.example.BestExampleApp.main")
|
||||
// Create a logger
|
||||
let logger = Logger(label: "com.example.YourApp")
|
||||
|
||||
// 3) we're now ready to use it
|
||||
logger.info("Hello World!")
|
||||
// Log at different levels
|
||||
logger.info("Application started")
|
||||
logger.warning("This is a warning")
|
||||
logger.error("Something went wrong", metadata: ["error": "\(error)"])
|
||||
|
||||
// Add metadata for context
|
||||
var requestLogger = logger
|
||||
requestLogger[metadataKey: "request-id"] = "\(UUID())"
|
||||
requestLogger.info("Processing request")
|
||||
```
|
||||
|
||||
#### Output
|
||||
## Available log handler backends
|
||||
|
||||
```
|
||||
2019-03-13T15:46:38+0000 info: Hello World!
|
||||
```
|
||||
The community has built numerous specialized logging backends.
|
||||
|
||||
#### Default `Logger` behavior
|
||||
|
||||
`SwiftLog` provides for very basic console logging out-of-the-box by way of `StreamLogHandler`. It is possible to switch the default output to `stderr` like so:
|
||||
```swift
|
||||
LoggingSystem.bootstrap(StreamLogHandler.standardError)
|
||||
```
|
||||
|
||||
`StreamLogHandler` is primarily a convenience only and does not provide any substantial customization. Library maintainers who aim to build their own logging backends for integration and consumption should implement the `LogHandler` protocol directly as laid out in [the "On the implementation of a logging backend" section](#on-the-implementation-of-a-logging-backend-a-loghandler).
|
||||
|
||||
For further information, please check the [API documentation][api-docs].
|
||||
|
||||
<a name="backends"></a>
|
||||
#### Selecting a logging backend implementation (applications only)
|
||||
|
||||
As the API has just launched, not many implementations exist yet. If you are interested in implementing one see the "Implementation considerations" section below explaining how to do so. List of existing SwiftLog API compatible libraries:
|
||||
|
||||
| Repository | Handler Description|
|
||||
| ----------- | ----------- |
|
||||
| [Kitura/HeliumLogger](https://github.com/Kitura/HeliumLogger) |a logging backend widely used in the Kitura ecosystem |
|
||||
| [ianpartridge/swift-log-**syslog**](https://github.com/ianpartridge/swift-log-syslog) | a [syslog](https://en.wikipedia.org/wiki/Syslog) backend|
|
||||
| [Adorkable/swift-log-**format-and-pipe**](https://github.com/Adorkable/swift-log-format-and-pipe) | a backend that allows customization of the output format and the resulting destination |
|
||||
| [chrisaljoudi/swift-log-**oslog**](https://github.com/chrisaljoudi/swift-log-oslog) | an OSLog [Unified Logging](https://developer.apple.com/documentation/os/logging) backend for use on Apple platforms. **Important Note:** we recommend using os_log directly as decribed [here](https://developer.apple.com/documentation/os/logging). Using os_log through swift-log using this backend will be less efficient and will also prevent specifying the privacy of the message. The backend always uses `%{public}@` as the format string and eagerly converts all string interpolations to strings. This has two drawbacks: 1. the static components of the string interpolation would be eagerly copied by the unified logging system, which will result in loss of performance. 2. It makes all messages public, which changes the default privacy policy of os_log, and doesn't allow specifying fine-grained privacy of sections of the message. In a separate on-going work, Swift APIs for os_log are being improved and made to align closely with swift-log APIs. References: [Unifying Logging Levels](https://forums.swift.org/t/custom-string-interpolation-and-compile-time-interpretation-applied-to-logging/18799), [Making os_log accept string interpolations using compile-time interpretation](https://forums.swift.org/t/logging-levels-for-swifts-server-side-logging-apis-and-new-os-log-apis/20365). |
|
||||
| [Brainfinance/StackdriverLogging](https://github.com/Brainfinance/StackdriverLogging) | a structured JSON logging backend for use on Google Cloud Platform with the [Stackdriver logging agent](https://cloud.google.com/logging/docs/agent) |
|
||||
| [DnV1eX/GoogleCloudLogging](https://github.com/DnV1eX/GoogleCloudLogging) | a client-side library for logging application events in [Google Cloud](https://console.cloud.google.com/logs) via REST API v2. |
|
||||
| [vapor/console-kit](https://github.com/vapor/console-kit/) | print log messages to a terminal with stylized ([ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code)) output |
|
||||
| [neallester/swift-log-testing](https://github.com/neallester/swift-log-testing) | provides access to log messages for use in assertions (within test targets) |
|
||||
| [wlisac/swift-log-slack](https://github.com/wlisac/swift-log-slack) | a logging backend that sends critical log messages to Slack |
|
||||
| [NSHipster/swift-log-github-actions](https://github.com/NSHipster/swift-log-github-actions) | a logging backend that translates logging messages into [workflow commands for GitHub Actions](https://help.github.com/en/actions/reference/workflow-commands-for-github-actions). |
|
||||
| [stevapple/swift-log-telegram](https://github.com/stevapple/swift-log-telegram) | a logging backend that sends log messages to any Telegram chat (Inspired by and forked from [wlisac/swift-log-slack](https://github.com/wlisac/swift-log-slack)) |
|
||||
| [jagreenwood/swift-log-datadog](https://github.com/jagreenwood/swift-log-datadog) | a logging backend which sends log messages to the [Datadog](https://www.datadoghq.com/log-management/) log management service |
|
||||
| [google/SwiftLogFireCloud](https://github.com/google/swiftlogfirecloud) | a logging backend for time series logging which pushes logs as flat files to Firebase Cloud Storage. |
|
||||
| [crspybits/swift-log-file](https://github.com/crspybits/swift-log-file) | a simple local file logger (using `Foundation` `FileManager`) |
|
||||
| [sushichop/Puppy](https://github.com/sushichop/Puppy) | a logging backend that supports multiple transports(console, file, syslog, etc.) and has the feature with formatting and file log rotation |
|
||||
| [luoxiu/LogDog](https://github.com/luoxiu/LogDog) | user-friendly logging with sinks and appenders |
|
||||
| Your library? | [Get in touch!](https://forums.swift.org/c/server) |
|
||||
|
||||
## What is an API package?
|
||||
|
||||
Glad you asked. We believe that for the Swift on Server ecosystem, it's crucial to have a logging API that can be adopted by anybody so a multitude of libraries from different parties can all log to a shared destination. More concretely this means that we believe all the log messages from all libraries end up in the same file, database, Elastic Stack/Splunk instance, or whatever you may choose.
|
||||
|
||||
In the real-world however, there are so many opinions over how exactly a logging system should behave, what a log message should be formatted like, and where/how it should be persisted. We think it's not feasible to wait for one logging package to support everything that a specific deployment needs whilst still being easy enough to use and remain performant. That's why we decided to cut the problem in half:
|
||||
|
||||
1. a logging API
|
||||
2. a logging backend implementation
|
||||
|
||||
This package only provides the logging API itself and therefore `SwiftLog` is a 'logging API package'. `SwiftLog` (using `LoggingSystem.bootstrap`) can be configured to choose any compatible logging backend implementation. This way packages can adopt the API and the _application_ can choose any compatible logging backend implementation without requiring any changes from any of the libraries.
|
||||
|
||||
Just for completeness sake: This API package does actually include an overly simplistic and non-configurable logging backend implementation which simply writes all log messages to `stdout`. The reason to include this overly simplistic logging backend implementation is to improve the first-time usage experience. Let's assume you start a project and try out `SwiftLog` for the first time, it's just a whole lot better to see something you logged appear on `stdout` in a simplistic format rather than nothing happening at all. For any real-world application, we advise configuring another logging backend implementation that logs in the style you like.
|
||||
|
||||
## The core concepts
|
||||
|
||||
### Loggers
|
||||
|
||||
`Logger`s are used to emit log messages and therefore the most important type in `SwiftLog`, so their use should be as simple as possible. Most commonly, they are used to emit log messages in a certain log level. For example:
|
||||
|
||||
```swift
|
||||
// logging an informational message
|
||||
logger.info("Hello World!")
|
||||
|
||||
// ouch, something went wrong
|
||||
logger.error("Houston, we have a problem: \(problem)")
|
||||
```
|
||||
|
||||
### Log levels
|
||||
|
||||
The following log levels are supported:
|
||||
|
||||
- `trace`
|
||||
- `debug`
|
||||
- `info`
|
||||
- `notice`
|
||||
- `warning`
|
||||
- `error`
|
||||
- `critical`
|
||||
|
||||
The log level of a given logger can be changed, but the change will only affect the specific logger you changed it on. You could say the `Logger` is a _value type_ regarding the log level.
|
||||
|
||||
|
||||
### Logging metadata
|
||||
|
||||
Logging metadata is metadata that can be attached to loggers to add information that is crucial when debugging a problem. In servers, the usual example is attaching a request UUID to a logger that will then be present on all log messages logged with that logger. Example:
|
||||
|
||||
```swift
|
||||
var logger = logger
|
||||
logger[metadataKey: "request-uuid"] = "\(UUID())"
|
||||
logger.info("hello world")
|
||||
```
|
||||
|
||||
will print
|
||||
|
||||
```
|
||||
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED hello world
|
||||
```
|
||||
|
||||
with the default logging backend implementation that ships with `SwiftLog`. Needless to say, the format is fully defined by the logging backend you choose.
|
||||
|
||||
## On the implementation of a logging backend (a `LogHandler`)
|
||||
|
||||
Note: If you don't want to implement a custom logging backend, everything in this section is probably not very relevant, so please feel free to skip.
|
||||
|
||||
To become a compatible logging backend that all `SwiftLog` consumers can use, you need to do two things: 1) Implement a type (usually a `struct`) that implements `LogHandler`, a protocol provided by `SwiftLog` and 2) instruct `SwiftLog` to use your logging backend implementation.
|
||||
|
||||
A `LogHandler` or logging backend implementation is anything that conforms to the following protocol
|
||||
|
||||
```swift
|
||||
public protocol LogHandler {
|
||||
func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)
|
||||
|
||||
subscript(metadataKey _: String) -> Logger.Metadata.Value? { get set }
|
||||
|
||||
var metadata: Logger.Metadata { get set }
|
||||
|
||||
var logLevel: Logger.Level { get set }
|
||||
}
|
||||
```
|
||||
|
||||
Instructing `SwiftLog` to use your logging backend as the one the whole application (including all libraries) should use is very simple:
|
||||
|
||||
LoggingSystem.bootstrap(MyLogHandler.init)
|
||||
|
||||
### Implementation considerations
|
||||
|
||||
`LogHandler`s control most parts of the logging system:
|
||||
|
||||
#### Under control of a `LogHandler`
|
||||
|
||||
##### Configuration
|
||||
|
||||
`LogHandler`s control the two crucial pieces of `Logger` configuration, namely:
|
||||
|
||||
- log level (`logger.logLevel` property)
|
||||
- logging metadata (`logger[metadataKey:]` and `logger.metadata`)
|
||||
|
||||
For the system to work, however, it is important that `LogHandler` treat the configuration as _value types_. This means that `LogHandler`s should be `struct`s and a change in log level or logging metadata should only affect the very `LogHandler` it was changed on.
|
||||
|
||||
However, in special cases, it is acceptable that a `LogHandler` provides some global log level override that may affect all `LogHandler`s created.
|
||||
|
||||
##### Emitting
|
||||
- emitting the log message itself
|
||||
|
||||
### Not under control of `LogHandler`s
|
||||
|
||||
`LogHandler`s do not control if a message should be logged or not. `Logger` will only invoke the `log` function of a `LogHandler` if `Logger` determines that a log message should be emitted given the configured log level.
|
||||
|
||||
## Source vs Label
|
||||
|
||||
A `Logger` carries an (immutable) `label` and each log message carries a `source` parameter (since SwiftLog 1.3.0). The `Logger`'s label
|
||||
identifies the creator of the `Logger`. If you are using structured logging by preserving metadata across multiple modules, the `Logger`'s
|
||||
`label` is not a good way to identify where a log message originated from as it identifies the creator of a `Logger` which is often passed
|
||||
around between libraries to preserve metadata and the like.
|
||||
|
||||
If you want to filter all log messages originating from a certain subsystem, filter by `source` which defaults to the module that is emitting the
|
||||
log message.
|
||||
|
||||
## Design
|
||||
|
||||
This logging API was designed with the contributors to the Swift on Server community and approved by the [SSWG (Swift Server Work Group)](https://swift.org/server/) to the 'sandbox level' of the SSWG's [incubation process](https://github.com/swift-server/sswg/blob/master/process/incubation.md).
|
||||
|
||||
- [pitch](https://forums.swift.org/t/logging/16027), [discussion](https://forums.swift.org/t/discussion-server-logging-api/18834), [feedback](https://forums.swift.org/t/feedback-server-logging-api-with-revisions/19375)
|
||||
- [log levels](https://forums.swift.org/t/logging-levels-for-swifts-server-side-logging-apis-and-new-os-log-apis/20365)
|
||||
|
||||
[api-docs]: https://apple.github.io/swift-log/docs/current/Logging/Structs/Logger.html
|
||||
A great way to discover available log backend implementations is searching the
|
||||
[Swift Package Index](https://swiftpackageindex.com/search?query=swift-log)
|
||||
for the `swift-log` keyword.
|
||||
@@ -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,180 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
public 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 error which was logged.
|
||||
public var error: (any Error)?
|
||||
/// 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
|
||||
}
|
||||
|
||||
public init(level: Logger.Level, message: Logger.Message, error: (any Error)?, metadata: Logger.Metadata) {
|
||||
self.level = level
|
||||
self.message = message
|
||||
self.error = error
|
||||
self.metadata = metadata
|
||||
}
|
||||
|
||||
public static func == (lhs: InMemoryLogHandler.Entry, rhs: InMemoryLogHandler.Entry) -> Bool {
|
||||
lhs.level == rhs.level
|
||||
&& lhs.message == rhs.message
|
||||
&& errorsEqual(lhs.error, rhs.error)
|
||||
&& lhs.metadata == rhs.metadata
|
||||
}
|
||||
|
||||
private static func errorsEqual(_ lhs: (any Error)?, _ rhs: (any Error)?) -> Bool {
|
||||
switch (lhs, rhs) {
|
||||
case (nil, nil):
|
||||
return true
|
||||
case let (l?, r?):
|
||||
return "\(l)" == "\(r)" && String(reflecting: type(of: l)) == String(reflecting: type(of: r))
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private final class LogStore: @unchecked Sendable {
|
||||
private var _entries: [Entry] = []
|
||||
private let lock = Lock()
|
||||
|
||||
fileprivate func append(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata
|
||||
) {
|
||||
self.lock.withLockVoid {
|
||||
self._entries.append(
|
||||
Entry(
|
||||
level: level,
|
||||
message: message,
|
||||
error: error,
|
||||
metadata: metadata
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
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(event: LogEvent) {
|
||||
// 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(event.metadata ?? [:]) { $1 }
|
||||
|
||||
self.logStore.append(level: event.level, message: event.message, error: event.error, metadata: mergedMetadata)
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
event: LogEvent(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
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()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,138 @@
|
||||
# 001: Choosing log levels
|
||||
|
||||
Select appropriate log levels in applications and libraries.
|
||||
|
||||
## Overview
|
||||
|
||||
SwiftLog defines seven log levels, and choosing the right level is crucial for
|
||||
creating well-behaved libraries that don't overwhelm logging systems or misuse
|
||||
severity levels. This practice provides clear guidance on when to use each
|
||||
level.
|
||||
|
||||
### Motivation
|
||||
|
||||
Libraries must be well-behaved across various use cases and cannot assume
|
||||
specific logging backend configurations. Using inappropriate log levels can
|
||||
flood production logs, trigger false alerts, or make debugging more difficult.
|
||||
Following consistent log level guidelines ensures your library integrates well
|
||||
with diverse application environments.
|
||||
|
||||
### Log levels
|
||||
|
||||
SwiftLog defines seven log levels via ``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``
|
||||
|
||||
### Level guidelines
|
||||
|
||||
How you use log levels depends in large part if you are developing a library, or
|
||||
an application which bootstraps its logging system and is in full control over
|
||||
its logging environment.
|
||||
|
||||
#### For libraries
|
||||
|
||||
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.
|
||||
|
||||
##### 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.
|
||||
|
||||
##### Info Level
|
||||
- **Usage**: Reserved for things that went wrong but can't be communicated
|
||||
through other means, like throwing from a method.
|
||||
- **Examples**: Connection retry attempts, fallback mechanisms, recoverable
|
||||
failures.
|
||||
- **Guideline**: Use sparingly - Don't use for normal successful operations.
|
||||
|
||||
#### For applications
|
||||
|
||||
Applications can use **any level** depending on the context and what they want
|
||||
to achieve. Applications have full control over their logging strategy.
|
||||
|
||||
#### Configuring logger log levels
|
||||
|
||||
It depends on the use-case of your application which log level your logger
|
||||
should use. For **console and other end-user-visible displays**: Consider using
|
||||
**notice level** as the minimum visible level to avoid overwhelming users with
|
||||
technical details.
|
||||
|
||||
### Example
|
||||
|
||||
#### Recommended: Libraries should use info level or lower
|
||||
|
||||
```swift
|
||||
// ✅ Good: Trace level for detailed diagnostics
|
||||
logger.trace("Connection pool state", metadata: [
|
||||
"active": "\(activeConnections)",
|
||||
"idle": "\(idleConnections)",
|
||||
"pending": "\(pendingRequests)"
|
||||
])
|
||||
|
||||
// ✅ Good: Debug level for high-value operational info
|
||||
logger.debug("Database connection established", metadata: [
|
||||
"host": "\(host)",
|
||||
"database": "\(database)",
|
||||
"connectionTime": "\(duration)"
|
||||
])
|
||||
|
||||
// ✅ Good: Info level for issues that can't be communicated through other means
|
||||
logger.info("Connection failed, retrying", metadata: [
|
||||
"attempt": "\(attemptNumber)",
|
||||
"maxRetries": "\(maxRetries)",
|
||||
"host": "\(host)"
|
||||
])
|
||||
```
|
||||
|
||||
#### Use sparingly: Warning and error levels
|
||||
|
||||
```swift
|
||||
// ✅ Good: One-time startup warning or error
|
||||
logger.warning("Deprecated TLS version detected. Consider upgrading to TLS 1.3")
|
||||
```
|
||||
|
||||
#### Avoid: Logging potentially intentional failures at info level
|
||||
|
||||
Some failures may be completely intentional from the high-level perspective of a
|
||||
developer or system using your library. For example: failure to resolve a
|
||||
domain, failure to make a request, or failure to complete some task;
|
||||
|
||||
Instead, log at debug or trace levels and offer alternative ways to observe
|
||||
these behaviors, for example using `swift-metrics` to emit counts.
|
||||
|
||||
```swift
|
||||
// ❌ Bad: Normal operations at info level flood production logs
|
||||
logger.info("Request failed")
|
||||
```
|
||||
|
||||
#### Avoid: Normal operations at info level
|
||||
|
||||
```swift
|
||||
// ❌ Bad: Normal operations at info level flood production logs
|
||||
logger.info("HTTP request received")
|
||||
logger.info("Database query executed")
|
||||
logger.info("Response sent")
|
||||
|
||||
// ✅ Good: Use appropriate levels instead
|
||||
logger.debug("Processing request", metadata: ["path": "\(path)"])
|
||||
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
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,73 @@
|
||||
# Disable log levels during compilation
|
||||
|
||||
SwiftLog provides compile-time traits to eliminate less severe log levels from
|
||||
your binary reducing the runtime overhead.
|
||||
|
||||
## Motivation
|
||||
|
||||
When deploying applications to production, you often know in advance which log
|
||||
levels will never be needed. For example, a production service might only need
|
||||
warning and above, while trace and debug levels are only useful during
|
||||
development. By using traits, you can completely remove these unnecessary log
|
||||
levels at compile time, achieving zero runtime overhead.
|
||||
|
||||
## Available traits
|
||||
|
||||
SwiftLog defines seven maximum log level traits, ordered from most permissive
|
||||
to most restrictive:
|
||||
|
||||
- `MaxLogLevelDebug`: Debug and above available (compiles out trace)
|
||||
- `MaxLogLevelInfo`: Info and above available (compiles out trace, debug)
|
||||
- `MaxLogLevelNotice`: Notice and above available (compiles out trace, debug,
|
||||
info)
|
||||
- `MaxLogLevelWarning`: Warning and above available (compiles out trace, debug,
|
||||
info, notice)
|
||||
- `MaxLogLevelError`: Error and above available (compiles out trace, debug,
|
||||
info, notice, warning)
|
||||
- `MaxLogLevelCritical`: Only critical available (compiles out all except
|
||||
critical)
|
||||
- `MaxLogLevelNone`: All logging compiled out (no log levels available)
|
||||
|
||||
By default (when no traits are specified), all log levels are available.
|
||||
|
||||
When you specify a maximum log level trait, all less severe levels are
|
||||
completely removed from your binary at compile time. This applies to both
|
||||
level-specific methods (e.g., `logger.debug()`) and calls to the generic
|
||||
`logger.log(level:)` method. Traits are additive. If multiple max level traits
|
||||
are specified, the most restrictive one takes effect.
|
||||
|
||||
> Note: Traits should only be set by the applications and not libraries as
|
||||
> any traits defined in a transitive dependency will affect the whole resolution tree.
|
||||
|
||||
## Example
|
||||
|
||||
To enable a trait, specify it when declaring your package dependency:
|
||||
|
||||
```swift
|
||||
// In your Package.swift:
|
||||
dependencies: [
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["MaxLogLevelWarning"]
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
With `MaxLogLevelWarning` enabled, all trace, debug, info, and notice log
|
||||
statements are compiled out:
|
||||
|
||||
```swift
|
||||
// These become no-ops (compiled out completely):
|
||||
logger.trace("This will not be in the binary")
|
||||
logger.debug("This will not be in the binary")
|
||||
logger.info("This will not be in the binary")
|
||||
logger.notice("This will not be in the binary")
|
||||
logger.log(level: .debug, "This will not log anything")
|
||||
|
||||
// These work normally:
|
||||
logger.warning("This still works")
|
||||
logger.error("This still works")
|
||||
logger.critical("This still works")
|
||||
logger.log(level: .error, "This still works")
|
||||
```
|
||||
@@ -0,0 +1,212 @@
|
||||
# Implementing a log handler
|
||||
|
||||
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,
|
||||
you need to fulfill a few requirements, primarily conforming to the
|
||||
``LogHandler`` protocol.
|
||||
|
||||
### Implement with value type semantics
|
||||
|
||||
Your log handler **must be a `struct`** and exhibit value semantics. This
|
||||
ensures that changes to one logger don't affect others.
|
||||
|
||||
To verify that your handler reflects value semantics ensure that it passes this
|
||||
test:
|
||||
|
||||
```swift
|
||||
@Test
|
||||
func logHandlerValueSemantics() {
|
||||
LoggingSystem.bootstrap(MyLogHandler.init)
|
||||
var logger1 = Logger(label: "first logger")
|
||||
logger1.logLevel = .debug
|
||||
logger1[metadataKey: "only-on"] = "first"
|
||||
|
||||
var logger2 = logger1
|
||||
logger2.logLevel = .error // Must not affect logger1
|
||||
logger2[metadataKey: "only-on"] = "second" // Must not affect logger1
|
||||
|
||||
// These expectations must pass
|
||||
#expect(logger1.logLevel == .debug)
|
||||
#expect(logger2.logLevel == .error)
|
||||
#expect(logger1[metadataKey: "only-on"] == "first")
|
||||
#expect(logger2[metadataKey: "only-on"] == "second")
|
||||
}
|
||||
```
|
||||
|
||||
> Note: In special cases, it is acceptable for a log handler to provide
|
||||
> global log level overrides that may affect all log handlers created.
|
||||
|
||||
### Example implementation
|
||||
|
||||
Here's a complete example of a simple print-based log handler:
|
||||
|
||||
```swift
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public struct PrintLogHandler: LogHandler {
|
||||
private let label: String
|
||||
public var logLevel: Logger.Level = .info
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
|
||||
public init(label: String) {
|
||||
self.label = label
|
||||
}
|
||||
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
let timestamp = ISO8601DateFormatter().string(from: Date())
|
||||
let levelString = level.rawValue.uppercased()
|
||||
|
||||
// Merge handler metadata with message metadata
|
||||
let combinedMetadata = Self.prepareMetadata(
|
||||
base: self.metadata
|
||||
explicit: metadata
|
||||
)
|
||||
|
||||
// Format metadata
|
||||
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
|
||||
|
||||
// Create log line and print to console
|
||||
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
|
||||
print(logLine)
|
||||
}
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
return self.metadata[key]
|
||||
}
|
||||
set {
|
||||
self.metadata[key] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
static func prepareMetadata(
|
||||
base: Logger.Metadata,
|
||||
explicit: Logger.Metadata?
|
||||
) -> Logger.Metadata? {
|
||||
var metadata = base
|
||||
|
||||
guard let explicit else {
|
||||
// all per-log-statement values are empty
|
||||
return metadata
|
||||
}
|
||||
|
||||
metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
|
||||
|
||||
return metadata
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Advanced features
|
||||
|
||||
#### Metadata providers
|
||||
|
||||
Metadata providers allow you to dynamically add contextual information to all
|
||||
log messages without explicitly passing it each time. Common use cases include
|
||||
request IDs, user sessions, or trace contexts that should be included in logs
|
||||
throughout a request's lifecycle.
|
||||
|
||||
```swift
|
||||
import Foundation
|
||||
import Logging
|
||||
|
||||
public struct PrintLogHandler: LogHandler {
|
||||
private let label: String
|
||||
public var logLevel: Logger.Level = .info
|
||||
public var metadata: Logger.Metadata = [:]
|
||||
public var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
public init(label: String) {
|
||||
self.label = label
|
||||
}
|
||||
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
let timestamp = ISO8601DateFormatter().string(from: Date())
|
||||
let levelString = level.rawValue.uppercased()
|
||||
|
||||
// Get provider metadata
|
||||
let providerMetadata = metadataProvider?.get() ?? [:]
|
||||
|
||||
// Merge handler metadata with message metadata
|
||||
let combinedMetadata = Self.prepareMetadata(
|
||||
base: self.metadata,
|
||||
provider: self.metadataProvider,
|
||||
explicit: metadata
|
||||
)
|
||||
|
||||
// Format metadata
|
||||
let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",")
|
||||
|
||||
// Create log line and print to console
|
||||
let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)"
|
||||
print(logLine)
|
||||
}
|
||||
|
||||
public subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
return self.metadata[key]
|
||||
}
|
||||
set {
|
||||
self.metadata[key] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
static func prepareMetadata(
|
||||
base: Logger.Metadata,
|
||||
provider: Logger.MetadataProvider?,
|
||||
explicit: Logger.Metadata?
|
||||
) -> Logger.Metadata? {
|
||||
var metadata = base
|
||||
|
||||
let provided = provider?.get() ?? [:]
|
||||
|
||||
guard !provided.isEmpty || !((explicit ?? [:]).isEmpty) else {
|
||||
// all per-log-statement values are empty
|
||||
return metadata
|
||||
}
|
||||
|
||||
if !provided.isEmpty {
|
||||
metadata.merge(provided, uniquingKeysWith: { _, provided in provided })
|
||||
}
|
||||
|
||||
if let explicit = explicit, !explicit.isEmpty {
|
||||
metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit })
|
||||
}
|
||||
|
||||
return metadata
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance considerations
|
||||
|
||||
1. **Avoid blocking**: Don't block the calling thread for I/O operations.
|
||||
2. **Lazy evaluation**: Remember that messages and metadata are autoclosures.
|
||||
3. **Memory efficiency**: Don't hold onto large amounts of messages.
|
||||
|
||||
## See Also
|
||||
|
||||
- ``LogHandler``
|
||||
- ``StreamLogHandler``
|
||||
- ``MultiplexLogHandler``
|
||||
@@ -0,0 +1,43 @@
|
||||
# Logging best practices
|
||||
|
||||
Best practices for effective logging with SwiftLog.
|
||||
|
||||
## Overview
|
||||
|
||||
This collection of best practices helps library authors and application
|
||||
developers create effective, maintainable logging that works well across diverse
|
||||
environments. Each practice is designed to ensure your logs are useful for
|
||||
debugging while being respectful of system resources and operational
|
||||
requirements.
|
||||
|
||||
### Who Should Use These Practices
|
||||
|
||||
- **Library Authors**: Creating reusable components that log appropriately.
|
||||
- **Application Developers**: Implementing logging strategies in applications.
|
||||
|
||||
### Philosophy
|
||||
|
||||
Good logging strikes a balance between providing useful information and avoiding
|
||||
system overhead. These practices are based on real-world experience with
|
||||
production systems and emphasize:
|
||||
|
||||
- **Predictable behavior** across different environments.
|
||||
- **Performance consciousness** to avoid impacting application speed.
|
||||
- **Operational awareness** to support production debugging and monitoring.
|
||||
- **Developer experience** to make debugging efficient and pleasant.
|
||||
|
||||
### Contributing to these practices
|
||||
|
||||
These best practices evolve based on community experience and are maintained by
|
||||
the Swift Server Working Group ([SSWG](https://www.swift.org/sswg/)). Each
|
||||
practice includes:
|
||||
|
||||
- **Clear motivation** explaining why the practice matters
|
||||
- **Concrete examples** showing good and bad patterns
|
||||
- **Alternatives considered** documenting trade-offs and rejected approaches
|
||||
|
||||
## 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>
|
||||
@@ -0,0 +1,328 @@
|
||||
# SLG-0001: Metadata Providers
|
||||
|
||||
While global metadata attributes may be manually set on a `LogHandler` level, there's currently no way of reliably providing contextual, automatically propagated, metadata when logging with swift-log.
|
||||
|
||||
## Authors
|
||||
|
||||
[Moritz Lang](https://github.com/slashmo), [Konrad 'ktoso' Malawski](https://github.com/ktoso)
|
||||
|
||||
## Motivation
|
||||
|
||||
To benefit from tools such as [Distributed Tracing](https://github.com/apple/swift-distributed-tracing) it is necessary for libraries to make use of the trace information.
|
||||
|
||||
Most notably, loggers should participate in tracing by including some trace metadata (such as e.g. a `trace-id`) when logging, as it transparently enables developers to benefit from log correlation using those IDs.
|
||||
|
||||
Today, the only supported way of providing such metadata is to pass them along to each log call explicitly:
|
||||
|
||||
```swift
|
||||
logger.info("first this ...", metadata: ["trace-id": MyTracingLibrary.currentTraceID])
|
||||
logger.info("... now this", metadata: ["trace-id": MyTracingLibrary.currentTraceID])
|
||||
```
|
||||
|
||||
This comes with a couple of downsides:
|
||||
|
||||
### Error-prone and repetitive
|
||||
|
||||
It's easy to forget passing this metadata to _all_ log statements, resulting in an inconsistent debugging experience as these log statements cannot be found using correlation IDs.
|
||||
|
||||
The repetitiveness and verboseness of logging multiple metadata in-line quickly becomes annoying and vastly decreases the signal-to-noise ratio of Swift code trying to be a good citizen and making use of log correlation techniques such as distributed tracing.
|
||||
|
||||
### Impossible to implement for libraries
|
||||
|
||||
A large portion of logs are not generated by the end-user but by libraries such as AsyncHTTPClient, Vapor etc.
|
||||
These libraries, by design, don't know about the specific metadata keys that should be included in the logs.
|
||||
Those keys are after all runtime dependent, and may change depending on what tracing system is configured by the end user.
|
||||
|
||||
For example, a specific `Tracer` implementation would use a type representing a trace ID, and has a way of extracting
|
||||
that trace ID from a [Swift Distributed Tracing Baggage](https://github.com/apple/swift-distributed-tracing-baggage). But other libraries can't know about this _specific_ trace ID and therefore would not be
|
||||
able to pass such values along to their log statements.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
To support this kind of runtime-generated metadata in `swift-log`, we need to extend the logging APIs in an open-ended way, to allow any kinds of metadata to be provided from the asynchronous context (i.e. task local values).
|
||||
|
||||
We also have a desire to keep `swift-log` a "zero dependencies" library, as it intends only to focus on describing a logging API, and not incur any additional dependencies, so it can be used in the most minimal of projects.
|
||||
|
||||
To solve this, we propose the extension of swift-log APIs with a new concept: _metadata providers_.
|
||||
|
||||
`MetadataProvider` is a struct nested in the `Logger` type, sitting alongside `MetadataValue` and the `Metadata`.
|
||||
Its purpose is to _provide_ `Logger.Metadata` from the asynchronous context, by e.g. looking up various task-local values,
|
||||
and converting them into `Logger.Metadata`. This is performed by calling the `get()` function, like so:
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
public struct MetadataProvider: Sendable {
|
||||
// ...
|
||||
public init(_ provideMetadata: @escaping @Sendable () -> Metadata)
|
||||
|
||||
public get() -> Metadata
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Defining a `MetadataProvider`
|
||||
|
||||
While `MetadataProvider`s can be created in an ad-hoc fashion, the struct may be used as a namespace
|
||||
to define providers in.
|
||||
|
||||
For example, a `MyTracer` implementation of swift-distributed-tracing would be expected to provide a metadata provider
|
||||
that is aware of its own `Baggage` and specific keys it uses to carry the trace and span identifiers, like this:
|
||||
|
||||
```swift
|
||||
import Tracing // swift-distributed-tracing
|
||||
|
||||
extension Logger.MetadataProvider {
|
||||
static let myTracer = Logger.MetadataProvider {
|
||||
guard let baggage = Baggage.current else {
|
||||
return [:]
|
||||
}
|
||||
guard let spanContext = baggage.spanContext else {
|
||||
return [:]
|
||||
}
|
||||
|
||||
return [
|
||||
"traceID": "\(spanContext.traceID)",
|
||||
"spanID": "\(spanContext.spanID)",
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using a `MetadataProvider`
|
||||
|
||||
A `MetadataProvider` can be set up either globally, on a boot-strapped logging system:
|
||||
|
||||
```swift
|
||||
LoggingSystem.bootstrap(
|
||||
metadataProvider: .myTracer,
|
||||
StreamLogHandler.standardOutput
|
||||
)
|
||||
```
|
||||
|
||||
or, using the metadata provider specific bootstrap method:
|
||||
|
||||
```swift
|
||||
LoggingSystem.bootstrapMetadataProvider(.myTracer)
|
||||
```
|
||||
|
||||
It is also possible to configure a metadata provider on a per-logger basis, like this:
|
||||
|
||||
```swift
|
||||
let logger = Logger(label: "example", metadataProvider: Logger.MetadataProvider {
|
||||
guard let baggage = Baggage.current else {
|
||||
return [:]
|
||||
}
|
||||
guard let operationID = baggage.operationID else {
|
||||
return nil
|
||||
}
|
||||
return ["extra/opID": "\(opID)"]
|
||||
})
|
||||
```
|
||||
|
||||
which _overrides_ the default bootstrapped metadata provider.
|
||||
|
||||
> NOTE: Setting the metadata provider on the logger directly means the `LoggingSystem` metadata provider
|
||||
> is skipped (if defined), following how an explicitly passed handler `factory`
|
||||
> overrides the `LoggingSystem`s `factory`.
|
||||
|
||||
Once a metadata provider was set up, when a log statement is about to be emitted, the log handler implementation shall
|
||||
invoke it whenever it is about to emit a log statement. This must be done from the same asynchronous context as the log statement
|
||||
was made; I.e. if a log handler were to asynchronously–in a _detached_ task–create the actual log message, the invocation of
|
||||
the metadata provider still _must_ be performed before passing the data over to the other detached task.
|
||||
|
||||
Usually, metadata providers will reach for the task's Swift Distributed Tracing [`Baggage`](https://github.com/apple/swift-distributed-tracing-baggage) which is the mechanism that swift-distributed-tracing
|
||||
and instrumentation libraries use to propagate metadata across asynchronous, as well as process, boundaries. Handlers
|
||||
may also inspect other task-local values, however they should not expect other libraries to be able to propagage those
|
||||
as well as they will propagate `Baggage` values.
|
||||
|
||||
Those metadata will then be included in the log statement, e.g. like this:
|
||||
|
||||
```swift
|
||||
var baggage = Baggage.topLevel
|
||||
baggage.spanContext = SpanContext()
|
||||
Baggage.withValue(baggage) {
|
||||
test()
|
||||
}
|
||||
|
||||
func test() {
|
||||
log.info("Test", metadata: ["oneOff": "42"])
|
||||
// info [traceID: abc, spanID: 123, onOff: 42] Test
|
||||
}
|
||||
```
|
||||
|
||||
### Multiple `MetadataProvider`s using `MetadataProvider.multiplex(_:)`
|
||||
|
||||
Borrowing the concept from log handlers, metadata providers also have a multiplexing implementation.
|
||||
It is defined as an extension on `MetadataProvider` and is useful in cases where users want to utilize
|
||||
more than one metadata provider at the same time:
|
||||
|
||||
```swift
|
||||
extension Logger.MetadataProvider {
|
||||
public static func multiplex(_ providers: [Logger.MetadataProvider]) -> Logger.MetadataProvider {
|
||||
precondition(!providers.isEmpty, "providers MUST NOT be empty")
|
||||
return Logger.MetadataProvider { baggage in
|
||||
providers.reduce(into: nil) { metadata, provider in
|
||||
if let providedMetadata = provider.metadata(baggage) {
|
||||
if metadata != nil {
|
||||
metadata!.merge(providedMetadata, uniquingKeysWith: { _, rhs in rhs })
|
||||
} else {
|
||||
metadata = providedMetadata
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Metadata keys are unique, so in case multiple metadata providers return the same key,
|
||||
the last provider in the array _wins_ and provides the value.
|
||||
|
||||
Note that it is possible to query the `LoggingSystem` for the configured, system-wide, metadata provider,
|
||||
and combine it using a `multiplex` provider if the system-wide provider should not be replaced, but augmented
|
||||
by additional providers.
|
||||
|
||||
### Understanding Swift Distributed Tracing `Baggage`
|
||||
|
||||
The `Baggage` type is more than just a fancy type-safe container for your values which are meant to be carried across
|
||||
using a single, well-known, [task-local value](https://developer.apple.com/documentation/swift/tasklocal).
|
||||
|
||||
Values stored in `Baggage` are intended to be carried _across process boundaries_, and e.g. libraries such as HTTP clients,
|
||||
or other RPC mechanisms, or even messaging systems implement distributed tracing [instruments](https://github.com/apple/swift-distributed-tracing/blob/main/Sources/Instrumentation/Instrument.swift)
|
||||
which `inject` and `extract` baggage values into their respective carrier objects, e.g. an `HTTPRequest` in the case of an HTTP client.
|
||||
|
||||
In other words, whenever intending to propagate information _across processes_ utilize the `Baggage` type to carry it,
|
||||
and ensure to provide an `Instrument` that is able to inject/extract the values of interest into the carrier types you are interested in.
|
||||
To learn more about baggage and instrumentation, refer to the [Swift Distributed Tracing](https://github.com/apple/swift-distributed-tracing/) library documentation.
|
||||
|
||||
#### When to use `Baggage` vs. `Logger[metadataKey:]`
|
||||
|
||||
While `Baggage` is context-dependent and changes depending on where the log methods are being called from, the metadata set on a `Logger` is static and not context-dependent. E.g, if you wanted to add things like an instance ID or a subsystem name to a `Logger`, that could be seen as static information and set via `Logger[metadataKey:]`.
|
||||
|
||||
```swift
|
||||
var logger = Logger(label: "org.swift.my-service")
|
||||
logger[metadataKey: "instanceId"] = "123"
|
||||
|
||||
logger.info("Service started.")
|
||||
// [instanceId: 123] Service started.
|
||||
```
|
||||
|
||||
On the other hand, things like a trace ID are dynamic and context-dependent, therefore would be obtained via `Baggage`:
|
||||
|
||||
```swift
|
||||
logger.info("Product fetched.")
|
||||
// [traceId: 42] Product fetched.
|
||||
```
|
||||
|
||||
Inline-metadata is suitable for one-offs such as a `productId` or a `paymentMethod` in an online store service, but are not enough to corralate the following log statements, i.e. tying them both to the same request:
|
||||
|
||||
```swift
|
||||
logger.info("Product fetched.", metadata: ["productId": "42"])
|
||||
logger.info("Product purchased.", metadata: ["paymentMethod": "apple-pay"])
|
||||
|
||||
// [productId: 42] Product fetched.
|
||||
// [paymentMethod: apple-pay] Product fetched.
|
||||
```
|
||||
|
||||
If there was a `Baggage` value with a trace ID surrounding these log statements, they would be automatically correlatable:
|
||||
|
||||
```swift
|
||||
var baggage = Baggage.topLevel
|
||||
baggage.traceID = 42
|
||||
Baggage.$current.withValue(baggage) {
|
||||
logger.info("Product fetched.", metadata: ["productId": "42"])
|
||||
logger.info("Product purchased.", metadata: ["paymentMethod": "apple-pay"])
|
||||
}
|
||||
|
||||
// [trace-id: 42, productId: 42] Product fetched.
|
||||
// [trace-id: 42, paymentMethod: apple-pay] Product fetched.
|
||||
```
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### MetadataProviders as a function of `Baggage -> Metadata`
|
||||
|
||||
This was considered and fully developed, however it would cause swift-log to have a dependency on the instrumentation type `Baggage`,
|
||||
which was seen as in-conflict-with the interest of swift-log remaining a zero-dependency library.
|
||||
|
||||
`Baggage` _is_ the well known type that is intended to be used for any kind of distributed systems instrumentation and tracing,
|
||||
however it adds additional complexity and confusion for users who are not interested in this domain. For example, developers
|
||||
may be confused about why `Baggage` and `Logger.Metadata` look somewhat similar, but behave very differently. This complexity
|
||||
is inherent to the two types actually being _very_ different, however we do not want to overwhelm newcomers or developers
|
||||
who are only intending to use swift-log within process. Such developers do not need to care about the added complexities
|
||||
of distributed systems.
|
||||
|
||||
The tradeoff we take here is that every metadata provider will have to perform its own task-local (and therefore also thread-local),
|
||||
access in order to obtain the `Baggage` value, rather than the lookup being able to be performed _once_ and shared between
|
||||
multiple providers when a multiplex provider was configured in the system. We view this tradeoff as worth taking, as the cost
|
||||
of actually formatting the metadata usually strongly dominates the cost of the task-local lookup.
|
||||
|
||||
### Removing `LogHandler.Metadata` in favor of `Baggage`
|
||||
|
||||
Removing logger metadata is not a good option because it serves a slightly different style of metadata than the baggage.
|
||||
|
||||
Baggage is intended for contextual, task-local, metadata which is _carried across multiple libraries_. The values stored in baggage are well-typed, and must declare keys for accessing values in a baggage, this works well for multiple pieces of an application needing to reach for specific baggage items: everyone aware of the `traceID` key, is able to query the baggage for this key (`baggage.traceID`) and obtain a well-typed value. This comes with a higher cost on declaring keys though, as well as a global namespace for those - which is desirable for such kinds of metadata.
|
||||
|
||||
This is not the same usage pattern as emitting a plain structured log where we'd like to include the name of an item we just queried:
|
||||
|
||||
```swift
|
||||
log.info("Obtained item! Hooray!", metadata: ["item": "\(item)"])
|
||||
```
|
||||
|
||||
In this example, the key/value pair for `"item"` is pretty ad-hoc, and we never need to refer to it elsewhere in the program. It never is queried by other pieces of the application, nor would it be useful to set it in baggage metadata, as the only purpose of the `item` key here is to log, and forget about it.
|
||||
|
||||
### Explicitly passing `Baggage` always
|
||||
|
||||
Baggage is designed for use cases like distributed tracing, or similar instrumentation patterns where "all" participating code may need to reach for it.
|
||||
|
||||
Specifically in logging, this means that _every_ call site for _every_ log statement would have to pass it explicitly resulting in annoying noisy code:
|
||||
|
||||
```swift
|
||||
class StoresRepository {
|
||||
func store(byID id: String, eventLoop: EventLoop, logger: Logger, baggage: Baggage) async throws -> Store {
|
||||
InstrumentationSystem.tracer.withSpan("Fetch Store") { span in
|
||||
logger.info("Fetched store.", baggage: span.baggage)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
try await storesRepository.store(
|
||||
byID: storeID,
|
||||
eventLoop: eventLoop,
|
||||
logger: logger,
|
||||
baggage: baggage
|
||||
)
|
||||
```
|
||||
|
||||
### Explicitly passing `Logger` always
|
||||
|
||||
Imagine we don't have metadata providers, we'd have to manually set trace IDs on loggers which doesn't really work as all libraries involved would need to know about the same specific trace ID. Even if we inverted the dependency to have `Tracing` depend on `Logging` so that we'd be able to define something like "Tracing, please populate this logger with metadata", we'd have to make sure this thing is called in all places to avoid dropping contextual metadata.
|
||||
|
||||
```swift
|
||||
import Tracing
|
||||
import Logging
|
||||
|
||||
let contextualLogger = InstrumentationSystem.tracer.populateTraceMetadata(logger)
|
||||
contextualLogger.info("Request received.")
|
||||
```
|
||||
|
||||
### Tracing providing extensions on Logger
|
||||
|
||||
Instead of having `swift-log` depend on `swift-distributed-tracing-baggage` we could also create extensions for `Logger` inside `swift-distributed-tracing` and have users call these new overloaded methods instead:
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
func tinfo(_ message: ..., baggage: Baggage?) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Such extensions could work like the currently-proposed APIs, but the risk of users calling the wrong methods is incredibly high and we cannot overload the existing methods' signatures because of ambiguity of call-sides without explicit Baggage being passed:
|
||||
|
||||
```swift
|
||||
logger.info("Hello")
|
||||
// we want this to pick up Baggage, but the signature would be ambiguous
|
||||
```
|
||||
|
||||
Also, this extension-based contextual metadata would require basically everyone in Server-side Swift to adapt their usage of `Logging` to use these extensions instead. With the proposed APIs, we'd only need to modify `Logging` and any NIO-based libraries such as `AsyncHTTPClient`, `Vapor`, etc. and not every single log statement in every application.
|
||||
@@ -0,0 +1,173 @@
|
||||
# SLG-0002: Compile-time log level elimination using traits
|
||||
|
||||
Enable compile-time elimination of log levels to achieve zero runtime overhead for logs that will never be needed in production.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0002
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#378](https://github.com/apple/swift-log/issues/378)
|
||||
- Implementation:
|
||||
- [apple/swift-log#389](https://github.com/apple/swift-log/pull/389)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
Add Swift package traits to allow applications to compile out less severe log levels, completely eliminating their runtime overhead from the final binary.
|
||||
|
||||
### Motivation
|
||||
|
||||
In production deployments, applications often know in advance which log levels will never be needed. For example, a production service typically only needs warning and above, while trace and debug levels are exclusively useful during development. Currently, even with the log level set to `.warning` at runtime, the code for trace and debug statements still exists in the binary and incurs overhead.
|
||||
|
||||
For performance-critical applications or resource-constrained environments, this overhead is unacceptable. Applications need a way to completely remove unnecessary log levels at compile time, achieving zero runtime cost.
|
||||
|
||||
Before this proposal, the only workarounds were:
|
||||
- Manually wrapping log statements in `#if DEBUG` checks (error-prone and verbose)
|
||||
- Accepting the runtime overhead (unacceptable for many use cases)
|
||||
|
||||
### Proposed solution
|
||||
|
||||
This proposal introduces seven package traits that correspond to maximum log level thresholds. Applications specify a trait when declaring their dependency on SwiftLog, and all less severe log levels are completely compiled out.
|
||||
|
||||
In your `Package.swift`:
|
||||
|
||||
```swift
|
||||
dependencies: [
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["MaxLogLevelWarning"]
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
With `MaxLogLevelWarning` enabled:
|
||||
|
||||
```swift
|
||||
// These become no-ops (compiled out completely):
|
||||
logger.trace("This will not be in the binary")
|
||||
logger.debug("This will not be in the binary")
|
||||
logger.info("This will not be in the binary")
|
||||
logger.notice("This will not be in the binary")
|
||||
logger.log(level: .debug, "This will not log anything")
|
||||
|
||||
// These work normally:
|
||||
logger.warning("This still works")
|
||||
logger.error("This still works")
|
||||
logger.critical("This still works")
|
||||
logger.log(level: .error, "This still works")
|
||||
```
|
||||
|
||||
### Detailed design
|
||||
|
||||
The seven available traits, ordered from most permissive to most restrictive, are:
|
||||
|
||||
```swift
|
||||
traits: [
|
||||
.trait(name: "MaxLogLevelDebug", description: "Debug and above available (compiles out trace)"),
|
||||
.trait(name: "MaxLogLevelInfo", description: "Info and above available (compiles out trace, debug)"),
|
||||
.trait(name: "MaxLogLevelNotice", description: "Notice and above available (compiles out trace, debug, info)"),
|
||||
.trait(
|
||||
name: "MaxLogLevelWarning",
|
||||
description: "Warning and above available (compiles out trace, debug, info, notice)"
|
||||
),
|
||||
.trait(
|
||||
name: "MaxLogLevelError",
|
||||
description: "Error and above available (compiles out trace, debug, info, notice, warning)"
|
||||
),
|
||||
.trait(name: "MaxLogLevelCritical", description: "Only critical available (compiles out all except critical)"),
|
||||
.trait(name: "MaxLogLevelNone", description: "All logging compiled out (no log levels available)"),
|
||||
|
||||
.default(enabledTraits: []),
|
||||
]
|
||||
```
|
||||
|
||||
By default (when no traits are specified), all log levels remain available.
|
||||
|
||||
Traits are additive: if multiple max level traits are specified in the dependency graph, the most restrictive one takes effect. This ensures that if any dependency requests stricter elimination, the entire build respects it.
|
||||
|
||||
> Important: Traits should only be set by applications, not libraries, as any trait defined in a transitive dependency will affect the entire dependency resolution tree.
|
||||
|
||||
For the generic `log(level:)` method, the implementation switches behavior based on whether any trait is enabled:
|
||||
|
||||
```swift
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
) {
|
||||
#if MaxLogLevelDebug || MaxLogLevelInfo || MaxLogLevelNotice || MaxLogLevelWarning || MaxLogLevelError || MaxLogLevelCritical || MaxLogLevelNone
|
||||
// When traits are enabled, dispatch to level-specific methods
|
||||
// to leverage their compile-time elimination
|
||||
switch level {
|
||||
case .trace:
|
||||
self.trace(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
|
||||
case .debug:
|
||||
self.debug(message(), metadata: metadata(), source: source(), file: file, function: function, line: line)
|
||||
// ... (all levels)
|
||||
}
|
||||
#else
|
||||
// When no traits are enabled, avoid the switch overhead
|
||||
self._log(
|
||||
level: level,
|
||||
message(),
|
||||
metadata: metadata(),
|
||||
source: source(),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
#endif
|
||||
}
|
||||
```
|
||||
|
||||
This approach adds a minimal switch statement overhead when traits are enabled, but allows the level-specific methods' compile-time elimination to work even when called through `log(level:)`. When no traits are enabled, the original zero-overhead path is preserved. Level-specific methods has no additional overhead.
|
||||
|
||||
### API stability
|
||||
|
||||
**For existing `Logger` users:**
|
||||
- When no traits are enabled (the default), behavior is identical to before
|
||||
- Users can opt in to traits at the application level without modifying any source code
|
||||
|
||||
**For existing `LogHandler` implementations:**
|
||||
- No changes are required to any `LogHandler` implementation
|
||||
|
||||
### Future directions
|
||||
|
||||
No future directions identified.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Per-log-level traits
|
||||
|
||||
An alternative approach would be to define one trait per log level that could be individually disabled:
|
||||
|
||||
```swift
|
||||
traits: [
|
||||
.trait(name: "DisableTraceLogs"),
|
||||
.trait(name: "DisableDebugLogs"),
|
||||
.trait(name: "DisableInfoLogs"),
|
||||
.trait(name: "DisableNoticeLogs"),
|
||||
.trait(name: "DisableWarningLogs"),
|
||||
.trait(name: "DisableErrorLogs"),
|
||||
.trait(name: "DisableCriticalLogs"),
|
||||
]
|
||||
```
|
||||
|
||||
Users would specify multiple traits to eliminate multiple levels:
|
||||
|
||||
```swift
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-log.git",
|
||||
from: "1.0.0",
|
||||
traits: ["DisableTraceLogs", "DisableDebugLogs", "DisableInfoLogs", "DisableNoticeLogs"]
|
||||
)
|
||||
```
|
||||
|
||||
This approach was rejected in favor of a `MaxLogLevel` semantics to make it less verbose to use the functionality and to be aligned with the similar functionality in logging packages in other languages users might already be familiar with.
|
||||
@@ -0,0 +1,416 @@
|
||||
# SLG-0003: Support for Attaching Errors to Log Entries
|
||||
|
||||
Add standardized way of attaching data from `Error` instances to log entries.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0003
|
||||
- Author(s): [Samuel Murray](https://github.com/samuelmurray)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#291](https://github.com/apple/swift-log/issues/291)
|
||||
- Implementation:
|
||||
- [apple/swift-log#425](https://github.com/apple/swift-log/pull/425)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
- [First attempt at solution](https://github.com/apple/swift-log/pull/384)
|
||||
|
||||
### Introduction
|
||||
|
||||
Add new methods on `Logger` that accept an `Error` instance, which is passed as-is to the underlying `LogHandler`. To ensure backwards compatibility and a smooth adoption, a default implementation where the error is serialized into `MetadataValue`s is provided.
|
||||
|
||||
### Motivation
|
||||
|
||||
SwiftLog advocates for the use of _structured logging_, which in its implementation is achieved by using the `metadata` attribute in the log methods. This is important since it allows for automated tools to parse the logs and extract metadata values for filtering and/or visualization. When logging in a catch-block, it often makes sense to attach some information from the thrown `Error` in the log post, so as to capture the root cause.
|
||||
|
||||
```swift
|
||||
do {
|
||||
try someThrowingFunc()
|
||||
} catch {
|
||||
logger.warning("Something went wrong") // Want to somehow attach information about the error
|
||||
}
|
||||
```
|
||||
|
||||
Currently, there is no standardized way of doing this. The simplest way to do it would be to simply attach the stringified error to the message.
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong: \(error)")
|
||||
```
|
||||
|
||||
This of course is not _structured_, so a better way would be:
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong", metadata: ["error": "\(error)"])
|
||||
```
|
||||
|
||||
However, since there is no clear preference for what metadata key to use, it is likely that different code bases use variations of the above. This makes it hard for automated tools to extract error information, since there is no single key to look for.
|
||||
|
||||
Additionally, there is more information that we could extract from the error, such as the type name.
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong", metadata: ["error.message": "\(error)", "error.type": "\(String(reflecting: type(of: error)))"])
|
||||
```
|
||||
|
||||
The above is a reasonable way to log a generic error, but it is unlikely that everyone will use the same metadata keys. It is also quite a lot of code, for something that feels like it should be easy to do - i.e. attach an error to a log.
|
||||
|
||||
Finally, even if you log errors in a consistent way in your code, you do not control logs generated in other modules/packages that you use. In practice, this makes it so that different parts of your application could log error information under different keys, which, again, makes it harder for tooling.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
The solution we propose is to add convenience methods in `Logger` that allows the caller to do the following:
|
||||
|
||||
```swift
|
||||
do {
|
||||
try someThrowingFunc()
|
||||
} catch {
|
||||
logger.warning("Something went wrong", error: error)
|
||||
}
|
||||
```
|
||||
|
||||
The error would get passed as-is to the underlying `LogHandler`, which is free to serialize it in an appropriate way. We propose that such convenience methods are added for all log methods (even if it arguably makes less sense for e.g. `trace` and `debug` than `warning`).
|
||||
|
||||
There are two clear gains from this:
|
||||
|
||||
* It is obvious for the caller _how_ to attach an `Error` to a log (and the caller code also looks cleaner).
|
||||
* `LogHandler`s are free to serialize the `Error` in an way appropriate to that handler.
|
||||
|
||||
A `LogHandler` instance can access the `Error` using a new protocol method. A typical `LogHandler` implementation could be to extract the string representation and type name, and serialize it as metadata.
|
||||
|
||||
```swift
|
||||
struct ErrorLogHandler: LogHandler {
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
var metadata = metadata ?? [:]
|
||||
if let error {
|
||||
metadata.merge([
|
||||
"error.message": "\(error)",
|
||||
"error.type": "\(String(reflecting: type(of: error)))",
|
||||
]) { $1 }
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
As we extend the API of both `Logger` and `LogHandler`, we need to ensure compatibility with existing solutions on both sides. Specifically, users should be able to use the new `Logger` methods with existing `LogHandler`s, and get a reasonable serialization of the error. Otherwise, early adopters would have to manually serialize it _in addition to_ passing it using the new argument, until all `LogHandler`s have been updated. To achieve this, we add a default implementation on the `LogHandler` method, that serializes the `Error` as metadata, similar to the example above.
|
||||
|
||||
### Detailed design
|
||||
|
||||
The proposed solution is to add a new overload for each log method (`trace`, ..., `critical`) that accepts an `Error` as its second argument, as well as a new overload for `Logger.log`, that accepts an `Error` as its third argument.
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
/// Log a message at the 'trace' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/trace`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func trace(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'debug' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/debug`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func debug(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'info' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/info`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func info(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'notice' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/notice`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func notice(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'warning' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/warning`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func warning(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'error' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/error`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func error(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message at the 'critical' log level with the source that you provide.
|
||||
///
|
||||
/// If ``Level/critical`` is at least as severe as this logger's ``logLevel`` the system logs the message;
|
||||
/// otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func critical(
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
|
||||
/// Log a message using the log level and source that you provide.
|
||||
///
|
||||
/// If the `logLevel` passed to this method is more severe than the `Logger`'s ``logLevel``, the library
|
||||
/// logs the message, otherwise nothing will happen.
|
||||
///
|
||||
/// - parameters:
|
||||
/// - level: The severity level of the `message`.
|
||||
/// - message: The message to be logged. The `message` parameter supports any string interpolation literal.
|
||||
/// - error: An `Error` to attach to this log message.
|
||||
/// - metadata: One-off metadata to attach to this log message.
|
||||
/// - source: The source this log message originates from. The value defaults
|
||||
/// to the module that emits the log message.
|
||||
/// - file: The file this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#fileID`.
|
||||
/// - function: The function this log message originates from. There's usually no need to pass it explicitly, as
|
||||
/// it defaults to `#function`.
|
||||
/// - line: The line this log message originates from. There's usually no need to pass it explicitly, as it
|
||||
/// defaults to `#line`.
|
||||
@inlinable
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
_ message: @autoclosure () -> Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: @autoclosure () -> Logger.Metadata? = nil,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID,
|
||||
function: String = #function,
|
||||
line: UInt = #line
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
A new method is also added to `LogHandler`, which receives the `Error` passed to `Logger`.
|
||||
|
||||
```swift
|
||||
protocol LogHandler {
|
||||
/// The library calls this method when a log handler must emit a log message.
|
||||
///
|
||||
/// There is no need for the `LogHandler` to check if the `level` is above or
|
||||
/// below the configured `logLevel` as `Logger` already performed this check and
|
||||
/// determined that a message should be logged.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - error: The `Error` associated to this log message.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
A default implementation is included via an extension method, that calls the existing `log` function. This is to ensure backwards compatibility, and is similar to how `source` was added. The default implementation will serialize the `Error`, extracting its string representation and fully qualified type name, and add those to the metadata under the keys `"error.message"` and `"error.type"` respectively.
|
||||
|
||||
A draft implementation can be found in [apple/swift-log#425](https://github.com/apple/swift-log/pull/425).
|
||||
|
||||
We choose the keys `"error.message"` and `"error.type"` since they correspond to what [ECS](https://www.elastic.co/docs/reference/ecs/ecs-error) and [OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/#error-type) use. However, we propose that the metadata keys used should **not** be considered stable or part of the `swift-log` API. Instead, if a `LogHandler` wants to use separate keys, it should implement the new protocol method, rather than re-map the metadata keys.
|
||||
|
||||
### API stability
|
||||
|
||||
The proposed additions are fully backwards compatible, meaning that all existing code will continue to function as is. Additionally, a user of `Logger` can start using the new convenience methods, without any modifications of the `LogHandler`, thanks to the default implementation and since a `LogHandler` is already expected to handle `Metadata`.
|
||||
|
||||
However, when using the default implementation, a potential metadata collision exists when an `Error` is passed via the new methods while the same keys (`"error.message"`, `"error.type"`) are present in metadata:
|
||||
|
||||
```swift
|
||||
logger.warning("Something went wrong", error: error, metadata: ["error.message": "some other info"])
|
||||
```
|
||||
|
||||
We recommend that the `error` parameter takes precedence in such cases, with conflicting metadata values discarded. This aligns with the principle that explicit `error:` parameters represent primary data, while the same keys in metadata are likely incidental. In practice, we don't expect callers to deliberately pass conflicting error information.
|
||||
|
||||
Conversely, a `LogHandler` can implement the new protocol method, and still function with existing users of `Logger` - the `error` parameter will then always be `nil`.
|
||||
|
||||
### Future directions
|
||||
|
||||
#### recordError
|
||||
|
||||
If `swift-log` develops better support for scoped loggers, it might be possible to add a `recordError` method on `Logger`, that would attach the `Error` to all logs in that scope.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Standardized Error metadata via Logger convenience
|
||||
|
||||
The first proposed solution was to treat the new `Logger` methods as "convenience methods", that simply serialized the `Error` as metadata and did not pass the raw `Error` to `LogHandler`. The end result was similar to the currently proposed default implementation in `LogHandler`. In this solution, the metadata keys (`"error.message"` and `"error.type"`) were considered stable and part of the API, since that allowed for `LogHandler` implementations to re-map the keys (e.g. to `"err.*"`).
|
||||
|
||||
Ultimately, this was declined in favor of the current proposal. While the metadata based solution was simple, it lacked the flexibility that passing the raw `Error` allows for.
|
||||
|
||||
#### recordError convenience method
|
||||
|
||||
In the first iteration, we considered adding a new convenience method `recordError` on `Logger`, that would take an `Error`, serialize it, and add to the metadata on the `Logger`. This would primarily have been useful for when a `Logger` instance were passed down a call hierarchy and the `Error` metadata were relevant further down. However, it doesn't work well with the current proposal, since the serialization happens at a later stage.
|
||||
|
||||
#### Using .stringConvertible to pass Error to LogHandler
|
||||
|
||||
An alternative way to let the `LogHandler` get access to the raw `Error` would be to use the existing `.stringConvertible` enum case of `MetadataValue`. By putting the `Error` under a well-known metadata key (such as `"error"`), a `LogHandler` could get access to it, without any changes to the `LogHandler` protocol. However, this would only work for `Error`s that conform to `CustomStringConvertible`.
|
||||
|
||||
#### some Error vs any Error
|
||||
|
||||
The error argument in `Logger` was considered to be `some Error` rather than `any Error`. Ultimately, `any Error` was preferred. This is because in most typical use cases (e.g. general catch blocks), the error is an existential, so by using `some Error` we would get a slight performance penalty.
|
||||
@@ -0,0 +1,467 @@
|
||||
# SLG-0004: Metadata values privacy attribute
|
||||
|
||||
Introduce an attributed metadata system that allows attaching attributes to metadata values, with privacy level as the first attribute enabling developers to mark metadata as `.private` or `.public`.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0004
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Deferred**
|
||||
- Issue: https://github.com/apple/swift-log/issues/204
|
||||
- Implementation:
|
||||
- [apple/swift-log#418](https://github.com/apple/swift-log/pull/418)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
- [Review discussion](https://forums.swift.org/t/proposal-slg-0004-metadata-values-privacy-attribute/85249/16)
|
||||
|
||||
### Introduction
|
||||
|
||||
This proposal introduces an **attributed metadata system** that allows attaching attributes to metadata values. Privacy level is the first concrete attribute, enabling developers to mark metadata values as `.private` or `.public` so `LogHandler` implementations can redact sensitive values before logging.
|
||||
|
||||
### Motivation
|
||||
|
||||
SwiftLog lacks a mechanism to attach attributes to metadata values. This prevents marking metadata as sensitive and limits future extensibility for other metadata attributes.
|
||||
|
||||
Applications need privacy controls for:
|
||||
- Compliance with privacy regulations.
|
||||
- Backend integration with privacy-aware logging systems.
|
||||
- Systematic control over what data appears in logs.
|
||||
|
||||
Beyond privacy, an attributed metadata system provides a foundation for future extensions such as retention policies, data classification, or other metadata attributes.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Introduce new `AttributedMetadata` data type, enabling users to mark metadata values with `.private` and `.public` privacy label:
|
||||
|
||||
```swift
|
||||
// Add privacy level to metadata values obtained through a metadata provider
|
||||
let serviceIp = "127.0.0.1"
|
||||
var logger = Logger(label: "my-app", metadataProvider: .init {[
|
||||
"service.ip": "\(serviceIp, privacy: .private)",
|
||||
]})
|
||||
|
||||
// Add privacy level to metadata values attached to a `Loghandler` instance
|
||||
let requestId = UUID()
|
||||
logger[attributedMetadataKey: "request.id"] = "\(requestId, privacy: .private)"
|
||||
|
||||
// Mark sensitive values as private and non-sensitive as public at logging call site
|
||||
let userId = UUID()
|
||||
let action = "login"
|
||||
logger.info("User action", attributedMetadata: [
|
||||
"user.id": "\(userId, privacy: .private)",
|
||||
"action": "\(action)" // default is .public for ease of adoption
|
||||
])
|
||||
```
|
||||
|
||||
This allows `Logger` users to mark certain metadata values as "I only trust LogHandlers, who know how to handle sensitive data, to see this value".
|
||||
|
||||
### Detailed design
|
||||
|
||||
#### Attributed Metadata
|
||||
|
||||
To support privacy labels and enable future extensibility, we introduce a generalized **attributed metadata** system. This provides a foundation for attaching arbitrary attributes to metadata values, with privacy labels being the first concrete use case:
|
||||
|
||||
```swift
|
||||
// Plain metadata (existing)
|
||||
let metadataValue: MetadataValue = .string("value")
|
||||
logger.info("Message", metadata: ["key": metadataValue])
|
||||
|
||||
// Attributed metadata (new) — a value with attributes
|
||||
logger.info("Message", attributedMetadata: [
|
||||
"key": AttributedMetadataValue(value: metadataValue, attributes: ...)
|
||||
])
|
||||
```
|
||||
|
||||
The attributed metadata system instroduces new public API:
|
||||
|
||||
1. **`AttributedMetadataValue`**: Wraps a standard `MetadataValue` with associated attributes.
|
||||
2. **`MetadataValueAttributes`**: Container for attributes.
|
||||
3. **`AttributedMetadata`**: Dictionary type mapping `String` keys to attributed values.
|
||||
4. **Parallel logging API**: New log methods accepting `attributedMetadata` parameter.
|
||||
|
||||
This design separates the transport mechanism (attributed metadata) from specific attribute semantics (privacy labels), allowing future extensions without breaking existing attributed metadata code.
|
||||
|
||||
#### Privacy levels
|
||||
|
||||
With attributed metadata as the foundation, privacy labels are implemented as the first concrete attribute:
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
/// A metadata value with associated privacy attributes.
|
||||
///
|
||||
/// `AttributedMetadataValue` wraps a standard `MetadataValue` with privacy attributes,
|
||||
/// allowing you to mark metadata as private or public for privacy-aware logging.
|
||||
///
|
||||
/// ## Creating Attributed Metadata
|
||||
///
|
||||
/// Use string interpolation with privacy parameter:
|
||||
///
|
||||
/// ```swift
|
||||
/// // Preferred: String interpolation with privacy level specified
|
||||
/// let userId = "12345"
|
||||
/// let action = "login"
|
||||
/// logger.info("User action", attributedMetadata: [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "action": "\(action, privacy: .public)" // explicit .public for non-sensitive data
|
||||
/// ])
|
||||
///
|
||||
/// // Direct creation
|
||||
/// let attributed = Logger.AttributedMetadataValue(
|
||||
/// .string("12345"),
|
||||
/// privacy: .private
|
||||
/// )
|
||||
/// ```
|
||||
///
|
||||
/// ## Important Limitations
|
||||
///
|
||||
/// - **No nested privacy**: When marking a dictionary or array as private, all contained
|
||||
/// values are treated with the same privacy level. Fine-grained privacy within nested
|
||||
/// structures is not currently supported.
|
||||
///
|
||||
/// - **Metadata only**: Privacy levels apply only to metadata values, not to log messages.
|
||||
/// Avoid including sensitive data in log message string interpolation.
|
||||
public struct AttributedMetadataValue: CustomStringConvertible, Sendable {
|
||||
/// The redaction marker used for private values.
|
||||
internal static let redactionMarker = "<private>"
|
||||
|
||||
public let value: MetadataValue
|
||||
public let attributes: MetadataValueAttributes
|
||||
|
||||
/// String representation redacts private values to the redaction marker.
|
||||
public var description: String {
|
||||
attributes.privacy == .public ? value.description : Self.redactionMarker
|
||||
}
|
||||
|
||||
public init(_ value: MetadataValue, attributes: MetadataValueAttributes)
|
||||
public init(_ value: MetadataValue, privacy: PrivacyLevel)
|
||||
}
|
||||
|
||||
extension AttributedMetadataValue {
|
||||
/// Attributes that can be associated with metadata values.
|
||||
public struct MetadataValueAttributes: CustomStringConvertible, Hashable, Sendable {
|
||||
/// Privacy level for metadata values.
|
||||
///
|
||||
/// Privacy levels allow you to mark metadata values as either private (sensitive data that should be
|
||||
/// protected) or public (safe to log in any context).
|
||||
///
|
||||
/// ## Usage
|
||||
///
|
||||
/// Use string interpolation with the privacy parameter to create attributed metadata values:
|
||||
///
|
||||
/// ```swift
|
||||
/// let userId = "12345"
|
||||
/// let action = "login"
|
||||
/// logger.info("User action", attributedMetadata: [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "action": "\(action, privacy: .public)",
|
||||
/// "ip": "\(ipAddress, privacy: .private)"
|
||||
/// ])
|
||||
/// ```
|
||||
@frozen
|
||||
public enum PrivacyLevel: Sendable, CaseIterable, Equatable, Hashable, CustomStringConvertible {
|
||||
/// Private data that should be redacted in non-secure contexts.
|
||||
case `private`
|
||||
|
||||
/// Public data safe for general logging.
|
||||
case `public`
|
||||
}
|
||||
|
||||
/// The privacy level of this metadata value.
|
||||
public var privacy: PrivacyLevel
|
||||
|
||||
/// Create metadata value attributes with the specified privacy level.
|
||||
///
|
||||
/// - Parameter privacy: The privacy level for this metadata. Defaults to `.public`.
|
||||
public init(privacy: PrivacyLevel = .public)
|
||||
}
|
||||
|
||||
/// The underlying metadata value without privacy attributes.
|
||||
public var value: MetadataValue
|
||||
|
||||
/// The privacy attributes associated with this metadata value.
|
||||
public var attributes: MetadataValueAttributes
|
||||
|
||||
/// Create an attributed metadata value with the specified attributes.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - value: The metadata value to wrap.
|
||||
/// - attributes: The attributes for this value.
|
||||
public init(_ value: MetadataValue, attributes: MetadataValueAttributes)
|
||||
|
||||
/// Convenience initializer for creating attributed metadata with a privacy level.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - value: The metadata value to wrap.
|
||||
/// - privacy: The privacy level for this value.
|
||||
public init(_ value: MetadataValue, privacy: PrivacyLevel)
|
||||
}
|
||||
|
||||
/// Metadata dictionary with privacy attributes.
|
||||
///
|
||||
/// A dictionary mapping string keys to ``AttributedMetadataValue`` instances, used with
|
||||
/// the `attributedMetadata` parameter of logging methods.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let userId = "12345"
|
||||
/// let requestId = "req-789"
|
||||
/// let metadata: Logger.AttributedMetadata = [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "request.id": "\(requestId, privacy: .public)",
|
||||
/// "action": "purchase" // String literal defaults to .public
|
||||
/// ]
|
||||
/// logger.info("User action", attributedMetadata: metadata)
|
||||
/// ```
|
||||
public typealias AttributedMetadata = [String: AttributedMetadataValue]
|
||||
}
|
||||
```
|
||||
|
||||
#### String interpolation for attributed metadata
|
||||
|
||||
```swift
|
||||
extension Logger.AttributedMetadataValue: ExpressibleByStringLiteral, ExpressibleByStringInterpolation {
|
||||
/// Custom string interpolation that captures privacy levels from interpolated values.
|
||||
///
|
||||
/// This enables syntax like:
|
||||
/// ```swift
|
||||
/// logger.info("User action", attributedMetadata: [
|
||||
/// "user.id": "\(userId, privacy: .private)",
|
||||
/// "action": "\(action, privacy: .public)"
|
||||
/// ])
|
||||
/// ```
|
||||
public struct StringInterpolation: StringInterpolationProtocol {
|
||||
public init(literalCapacity: Int, interpolationCount: Int)
|
||||
public mutating func appendLiteral(_ literal: String)
|
||||
|
||||
/// Interpolation with explicit privacy parameter.
|
||||
public mutating func appendInterpolation<T>(_ value: T, privacy: Logger.PrivacyLevel = .public)
|
||||
where T: CustomStringConvertible
|
||||
}
|
||||
|
||||
/// Creates an attributed metadata value from a string literal (defaults to .public).
|
||||
public init(stringLiteral value: String)
|
||||
|
||||
/// Creates an attributed metadata value from string interpolation.
|
||||
public init(stringInterpolation: StringInterpolation)
|
||||
}
|
||||
```
|
||||
|
||||
#### New Logger methods
|
||||
|
||||
```swift
|
||||
extension Logger {
|
||||
// Attributed metadata storage
|
||||
var attributedMetadata: Logger.AttributedMetadata { get set }
|
||||
subscript(attributedMetadataKey: String) -> Logger.AttributedMetadataValue? { get set }
|
||||
|
||||
// Log family of methods
|
||||
public func log(level: Level, _ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func trace(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func debug(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func info(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func notice(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func warning(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func error(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
public func critical(_ message: @autoclosure () -> Message,
|
||||
attributedMetadata: @autoclosure () -> AttributedMetadata?,
|
||||
source: @autoclosure () -> String? = nil,
|
||||
file: String = #fileID, function: String = #function, line: UInt = #line)
|
||||
}
|
||||
```
|
||||
|
||||
#### AttributedMetadata support in LogHandler protocol
|
||||
|
||||
```swift
|
||||
protocol LogHandler {
|
||||
func log(level: Logger.Level, message: Logger.Message,
|
||||
attributedMetadata: Logger.AttributedMetadata?, source: String,
|
||||
file: String, function: String, line: UInt)
|
||||
|
||||
var attributedMetadata: Logger.AttributedMetadata { get set }
|
||||
subscript(attributedMetadataKey: String) -> Logger.AttributedMetadataValue? { get set }
|
||||
}
|
||||
|
||||
// Default implementations provided for backward compatibility
|
||||
extension LogHandler {
|
||||
// Default attributed metadata log method - redacts private values using helper
|
||||
public func log(level: Logger.Level, message: Logger.Message,
|
||||
attributedMetadata: Logger.AttributedMetadata?,
|
||||
source: String, file: String, function: String, line: UInt) {
|
||||
let processedMetadata = attributedMetadata.flatMap(Self.attributedToPlain)
|
||||
self.log(level: level, message: message, metadata: processedMetadata,
|
||||
source: source, file: file, function: function, line: line)
|
||||
}
|
||||
|
||||
// Default attributed metadata storage - uses helpers for conversion
|
||||
public var attributedMetadata: Logger.AttributedMetadata {
|
||||
get { self.metadata.mapValues(Self.plainToAttributed) }
|
||||
set { self.metadata = newValue.mapValues(Self.attributedToPlain) }
|
||||
}
|
||||
|
||||
public subscript(attributedMetadataKey key: String) -> Logger.AttributedMetadataValue? {
|
||||
get {
|
||||
guard let plainValue = self[metadataKey: key] else { return nil }
|
||||
return Self.plainToAttributed(plainValue)
|
||||
}
|
||||
set {
|
||||
if let attributedValue = newValue {
|
||||
self[metadataKey: key] = Self.attributedToPlain(attributedValue)
|
||||
} else {
|
||||
self[metadataKey: key] = nil
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### AttributedMetadata support in MetadataProvider
|
||||
|
||||
```swift
|
||||
extension Logger.MetadataProvider {
|
||||
/// Creates a new metadata provider that returns attributed metadata.
|
||||
///
|
||||
/// Attributed metadata providers allow you to specify privacy levels and other
|
||||
/// attributes for each metadata value. When accessed through the plain ``get()``
|
||||
/// method (for backward compatibility), private values are redacted to `"<private>"`.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let provider = Logger.MetadataProvider {
|
||||
/// [
|
||||
/// "request-id": "\(RequestContext.current.id, privacy: .public)",
|
||||
/// "user-id": "\(RequestContext.current.userId, privacy: .private)"
|
||||
/// ]
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter provideAttributed: A closure that extracts attributed metadata from the current execution context.
|
||||
/// - Returns: A metadata provider that returns attributed metadata.
|
||||
@_disfavoredOverload
|
||||
public static func init(_ provideAttributed: @escaping @Sendable () -> AttributedMetadata) -> MetadataProvider
|
||||
|
||||
/// Returns attributed metadata if this is an attributed provider.
|
||||
///
|
||||
/// Handlers supporting attributed metadata should call this first,
|
||||
/// falling back to `get()` if it returns nil.
|
||||
public func getAttributed() -> AttributedMetadata?
|
||||
}
|
||||
```
|
||||
|
||||
### API stability
|
||||
|
||||
- All existing APIs unchanged.
|
||||
- Plain and attributed metadata APIs coexist.
|
||||
- No deprecation planned.
|
||||
- Adoption is optional and incremental on both application and Log Handler sides.
|
||||
- Default implementation ensures existing handlers work; logging private metadata is an application concern requiring a compatible `LogHandler`.
|
||||
|
||||
### Future directions
|
||||
|
||||
- Add more attributes (e.g., value data type, etc) and potential future unification of plain and attributed metadata APIs.
|
||||
- Introduce "custom attributes", allowing applications to define application-specific attributes to work with application-specific log handlers.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
1. **Key-based redaction:** Configure which keys should be treated as private rather than marking each value:
|
||||
|
||||
```swift
|
||||
logger.privateKeys = ["user.id", "password", "email"]
|
||||
logger.info("User action", metadata: [
|
||||
"user.id": "12345", // Automatically private
|
||||
"action": "login" // Automatically public
|
||||
])
|
||||
```
|
||||
|
||||
Advantages:
|
||||
- Simpler API (no new types).
|
||||
- Centralized configuration.
|
||||
- Safer at scale (new sensitive fields update all logs automatically).
|
||||
- Easier migration.
|
||||
|
||||
**Not chosen because:**
|
||||
|
||||
- **Privacy belongs to data, not identifiers:** The same private data might be logged under different keys ("email", "user.email", "contact"), and the same key might contain different data with different privacy requirements in different contexts. Key-based redaction creates a synchronization problem—developers must maintain a separate list of "private keys" that stays in sync with actual logging code across the codebase, with no compile-time or review-time verification.
|
||||
|
||||
- **Code review visibility:** With value-based privacy, reviewers see privacy decisions at the call site: `"email": user.email.private()` makes it immediately clear that data is sensitive. With key-based redaction, reviewers must cross-reference a separate configuration file, making security review significantly harder.
|
||||
|
||||
- **No synchronization needed:** Value-based privacy is self-contained—privacy travels with the data at the point of use. No separate configuration to maintain, no risk of configuration drift, no runtime surprises when a key is missing from the private keys list.
|
||||
|
||||
- **Pattern complexity:** Supporting patterns/regex adds complexity and potential performance concerns.
|
||||
|
||||
The current design prioritizes **explicitness and data-centric privacy** over **configuration-based simplicity**. Privacy decisions are made where data is logged, making them visible during code review and keeping privacy attributes coupled to the data they protect.
|
||||
|
||||
2. **Convenience methods (`.private()` and `.public()`):** Add extension methods to `String` and `MetadataValue` for creating attributed metadata:
|
||||
|
||||
```swift
|
||||
extension String {
|
||||
public func `private`() -> Logger.AttributedMetadataValue
|
||||
public func `public`() -> Logger.AttributedMetadataValue
|
||||
}
|
||||
|
||||
logger.info("User action", attributedMetadata: [
|
||||
"user.id": "12345".private(),
|
||||
"action": "login".public()
|
||||
])
|
||||
```
|
||||
|
||||
**Not chosen because:**
|
||||
|
||||
- **Consistency with existing patterns:** `Logger.Message` and `Logger.MetadataValue` already use string interpolation extensively.
|
||||
- **Natural syntax:** `"\(value, privacy: .private)"` reads clearly and fits Swift's interpolation conventions.
|
||||
- **Less API surface:** No need for multiple extension methods across different types.
|
||||
|
||||
Metadata values already support string interpolation in SwiftLog. Rather than inventing additional API surface area with new methods, we leverage the existing string interpolation infrastructure with a custom `StringInterpolation` type. This provides:
|
||||
|
||||
3. **Default privacy level to `.private`:** Make attributed metadata values default to `.private` privacy level when no explicit privacy parameter is provided:
|
||||
|
||||
```swift
|
||||
logger.info("User action", attributedMetadata: [
|
||||
"user.id": "\(userId, privacy: .private)", // Explicit private (redundant with default)
|
||||
"action": "\(action, privacy: .public)" // Must explicitly mark as public
|
||||
])
|
||||
```
|
||||
|
||||
Advantages:
|
||||
- Security-by-default: requires explicit opt-out for logging non-sensitive data.
|
||||
- Safer for accidental inclusion of sensitive data.
|
||||
|
||||
**Not chosen because:**
|
||||
|
||||
Privacy should be an explicit opt-in action from the user. The current design (defaulting to `.public`) prioritizes **ease of adoption** over **security-by-default**:
|
||||
- Easier adoption - less boilerplate for common non-sensitive metadata.
|
||||
- Matches the mental model that "most data is safe to log".
|
||||
- Lower friction for migration from plain metadata.
|
||||
- Forces developers to think about privacy only for sensitive data, rather than requiring `.public` annotations everywhere.
|
||||
|
||||
4. **Pass all metadata to non-privacy-aware handlers:** Security risk; current design filters private data by default.
|
||||
|
||||
5. **Message-level privacy:** Less granular than metadata-level privacy and requires message handling changes.
|
||||
|
||||
6. **Privacy level handling configuration** to be an attribute of the `Logger` instead of LogHandler configuration. This would centralize the configuration across various `LogHandler` implementations. However, existing `LogHandler` already have configurations and they might want to customize the behavior even further.
|
||||
|
||||
7. **Handler metadata merging:** LogHandlers are responsible for merging their own `metadata` property, `metadataProvider` output, and the explicit `attributedMetadata` parameter. This is consistent with how plain metadata works - handlers control merging. Plain handler metadata and provider values should be treated as public (`.public` privacy level). Attributed metadata from the log call takes precedence.
|
||||
|
||||
8. **Add a third `.auto`/`.default` privacy attribute value:** Libraries and applications can mark a metadata value as `privacy: .default` and rely on the `LogHandler` to configure what the default is. While this might've been a solution to overcome default `.public` values for all the attributed metadata, in reality it is confusing from the semantic point of view. If someone wants to mark something as `.default`, because this _might_ be sensitive, then it should be marked as `.private` or not logged at all. If something does not need to be marked as `.private`, then it is `.public`. A custom `LogHandler` with an allow list of metadata keys/messages/modules can be used as an escape hatch in case the application does not trust its dependencies.
|
||||
@@ -0,0 +1,180 @@
|
||||
# SLG-0005: `LogEvent`-based `LogHandler` API
|
||||
|
||||
Replace the flat-parameter `log(level:message:metadata:source:file:function:line:)` method on `LogHandler` with
|
||||
`log(event: LogEvent)`, enabling forward-compatible evolution of the `LogHandler` interface without breaking existing
|
||||
handler implementations.
|
||||
|
||||
## Overview
|
||||
|
||||
- Proposal: SLG-0005
|
||||
- Author(s): [Vladimir Kukushkin](https://github.com/kukushechkin)
|
||||
- Status: **Approved**
|
||||
- Issue: [apple/swift-log#421](https://github.com/apple/swift-log/issues/421)
|
||||
- Implementation:
|
||||
- [apple/swift-log#423](https://github.com/apple/swift-log/pull/423)
|
||||
- Related links:
|
||||
- [Lightweight proposals process description](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/Proposals.md)
|
||||
- [SLG-0003: Standardized Error Metadata via Logger Convenience](https://github.com/apple/swift-log/blob/main/Sources/Logging/Docs.docc/Proposals/SLG-0003.md)
|
||||
|
||||
### Introduction
|
||||
|
||||
Introduce `LogEvent` that bundles all log-statement data, and replace the flat-parameter
|
||||
`log(level:message:metadata:source:file:function:line:)` method on `LogHandler` with `log(event: LogEvent)`.
|
||||
|
||||
### Motivation
|
||||
|
||||
The `LogHandler` protocol currently requires implementing a single method with seven parameters:
|
||||
|
||||
```swift
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
```
|
||||
|
||||
Every time a new piece of data needs to be forwarded from a log call site to the handler — an error, or a richer metadata type — the only options are:
|
||||
|
||||
- **Add a new parameter to the existing method.** This is a source-breaking change: every existing `LogHandler`
|
||||
implementation across the entire Swift ecosystem must be updated simultaneously.
|
||||
- **Add a new `Logger` overload.** This requires 2 parallel APIs to coexist until the old one can be safely deprecated.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
Introduce `LogEvent`, a `struct` that carries all the data associated with a single log statement. `LogEvent` is
|
||||
a handler-side type: it is constructed by `Logger._log` and passed to `LogHandler`. The public `Logger` call-site
|
||||
API — `logger.info(...)`, `logger.log(level:...)` and so on — is unchanged.
|
||||
|
||||
The `LogHandler` protocol gains a new required method `log(event: LogEvent)`, while the old flat-parameter method
|
||||
is deprecated.
|
||||
|
||||
For existing handlers, a default implementation of `log(event:)` forwards to the old method, so no code changes
|
||||
are required to keep existing implementations working. Handlers that want to take advantage of new fields added to
|
||||
`LogEvent` in future proposals implement `log(event:)`.
|
||||
|
||||
### Detailed design
|
||||
|
||||
#### New `LogEvent` type
|
||||
|
||||
A new top-level `struct` in the `Logging` module:
|
||||
|
||||
```swift
|
||||
public struct LogEvent: Sendable {
|
||||
public var level: Logger.Level
|
||||
public var message: Logger.Message
|
||||
private var _metadata: Logger.Metadata?
|
||||
public var metadata: Logger.Metadata? {
|
||||
get { self._metadata }
|
||||
set { self._metadata = newValue }
|
||||
}
|
||||
public var source: String
|
||||
public var file: String
|
||||
public var function: String
|
||||
public var line: UInt
|
||||
|
||||
public init(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Updated `LogHandler` protocol
|
||||
|
||||
```swift
|
||||
public protocol LogHandler: _SwiftLogSendableLogHandler {
|
||||
|
||||
/// The library calls this method when a log handler must emit a log message.
|
||||
///
|
||||
/// There is no need for the `LogHandler` to check if the level is above or below the configured `logLevel`
|
||||
/// as `Logger` already performed this check and determined that a message should be logged.
|
||||
///
|
||||
/// - Parameter event: The log event containing the level, message, metadata, and source location.
|
||||
func log(event: LogEvent)
|
||||
|
||||
/// Please do _not_ implement this method when you create a `LogHandler` implementation.
|
||||
/// Implement ``log(event:)`` instead.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Default implementation
|
||||
|
||||
The default for `log(event:)` forwards all event fields to the old flat-parameter method,
|
||||
preserving the behavior of existing handlers with no source changes required.
|
||||
|
||||
The default implementation is marked as deprecated to encourage handler authors to migrate to `log(event:)`.
|
||||
Handlers that still rely on the forwarding bridge will see a deprecation warning at compile time, signaling that
|
||||
they should adopt the new method directly.
|
||||
|
||||
```swift
|
||||
extension LogHandler {
|
||||
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
|
||||
public func log(event: LogEvent) {
|
||||
self.log(
|
||||
level: event.level,
|
||||
message: event.message,
|
||||
metadata: event.metadata,
|
||||
source: event.source,
|
||||
file: event.file,
|
||||
function: event.function,
|
||||
line: event.line
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### API stability
|
||||
|
||||
**For existing `Logger` users:** No changes. All existing call sites continue to compile and behave identically.
|
||||
|
||||
**For existing `LogHandler` implementations:** Implementations of
|
||||
`log(level:message:metadata:source:file:function:line:)` continue to work without any source changes. The
|
||||
default implementation of `log(event:)` forwards to the old method.
|
||||
|
||||
### Future directions
|
||||
|
||||
Future proposals can add new fields to `LogEvent` with sensible defaults — a richer metadata
|
||||
type, or an attached `Error` (as a follow-up for [SLG-0003 proposal](https://forums.swift.org/t/proposal-slg-0003-standardized-error-metadata-via-logger-convenience/84518/39)) —
|
||||
without touching the `LogHandler` protocol and without requiring any changes to
|
||||
existing handler implementations. This is the primary motivation for this proposal.
|
||||
|
||||
The [SLG-0004 proposal](https://github.com/apple/swift-log/pull/416) introduces an `AttributedMetadata` type that wraps
|
||||
`Logger.Metadata` with additional context. Adding it to `LogEvent` as a new optional field would be
|
||||
source-compatible, and the existing `metadata` field could become a computed property that projects from
|
||||
`attributedMetadata` when present, keeping old handlers fully functional without modification.
|
||||
|
||||
### Alternatives considered
|
||||
|
||||
#### Adding parameters with default values to the existing method
|
||||
|
||||
Adding new parameters with default values avoids introducing a new method, but still constitutes a
|
||||
source-breaking change: every existing `LogHandler` implementation that implements the method explicitly
|
||||
must add the new parameter. The whole point of this proposal is to avoid that pattern indefinitely.
|
||||
@@ -0,0 +1,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.
|
||||
@@ -0,0 +1,99 @@
|
||||
# ``Logging``
|
||||
|
||||
A unified, performant, and ergonomic logging API for Swift.
|
||||
|
||||
## Overview
|
||||
|
||||
SwiftLog provides a logging API package designed to establish a common API the
|
||||
ecosystem can use. It allows packages to emit log messages without tying them to
|
||||
any specific logging implementation, while applications can choose any
|
||||
compatible logging backend.
|
||||
|
||||
SwiftLog is an _API package_ which cuts the logging problem in half:
|
||||
1. A logging API (this package)
|
||||
2. Logging backend implementations (community-provided)
|
||||
|
||||
This separation allows libraries to adopt the API while applications choose any
|
||||
compatible logging backend implementation without requiring changes from
|
||||
libraries.
|
||||
|
||||
## Getting Started
|
||||
|
||||
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
|
||||
|
||||
Add the dependency to your `Package.swift`:
|
||||
|
||||
```swift
|
||||
.package(url: "https://github.com/apple/swift-log", from: "1.6.0")
|
||||
```
|
||||
|
||||
And to your target:
|
||||
|
||||
```swift
|
||||
.target(
|
||||
name: "YourTarget",
|
||||
dependencies: [
|
||||
.product(name: "Logging", package: "swift-log")
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```swift
|
||||
// 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!")
|
||||
```
|
||||
|
||||
This outputs:
|
||||
```
|
||||
2025-10-24T17:26:47-0700 info MyLogger: [your_app] Hello World!
|
||||
```
|
||||
|
||||
### Default Behavior
|
||||
|
||||
SwiftLog provides basic console logging via ``StreamLogHandler``. By default it
|
||||
uses `stdout`, however, you can configure it to use `stderr` instead:
|
||||
|
||||
```swift
|
||||
LoggingSystem.bootstrap(StreamLogHandler.standardError)
|
||||
```
|
||||
|
||||
``StreamLogHandler`` is primarily for convenience. For production applications,
|
||||
implement the ``LogHandler`` protocol directly or use a community-maintained
|
||||
backend.
|
||||
|
||||
|
||||
## Topics
|
||||
|
||||
### Logging API
|
||||
|
||||
- <doc:UnderstandingLoggers>
|
||||
- ``Logger``
|
||||
- ``LoggingSystem``
|
||||
|
||||
### Log Handlers
|
||||
|
||||
- ``LogHandler``
|
||||
- ``MultiplexLogHandler``
|
||||
- ``StreamLogHandler``
|
||||
- ``SwiftLogNoOpLogHandler``
|
||||
|
||||
### Best Practices
|
||||
|
||||
- <doc:LoggingBestPractices>
|
||||
- <doc:ImplementingALogHandler>
|
||||
- <doc:DisableLogLevelsDuringCompilation>
|
||||
|
||||
### Contributing
|
||||
|
||||
- <doc:Proposals>
|
||||
+86
-39
@@ -2,7 +2,7 @@
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
@@ -16,7 +16,7 @@
|
||||
//
|
||||
// This source file is part of the SwiftNIO open source project
|
||||
//
|
||||
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
|
||||
// Copyright (c) 2017-2026 Apple Inc. and the SwiftNIO project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
@@ -26,18 +26,26 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if canImport(WASILibc)
|
||||
// No locking on WASILibc
|
||||
#else
|
||||
|
||||
#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS)
|
||||
#if canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif os(Windows)
|
||||
import ucrt
|
||||
import WinSDK
|
||||
#elseif canImport(Glibc)
|
||||
import Glibc
|
||||
@preconcurrency import Glibc
|
||||
#elseif canImport(Android)
|
||||
@preconcurrency import Android
|
||||
#elseif canImport(Musl)
|
||||
@preconcurrency import Musl
|
||||
#elseif canImport(Bionic)
|
||||
@preconcurrency import Bionic
|
||||
#elseif canImport(WASILibc)
|
||||
@preconcurrency import WASILibc
|
||||
#if canImport(wasi_pthread)
|
||||
import wasi_pthread
|
||||
#endif
|
||||
#else
|
||||
#error("Unsupported runtime")
|
||||
#error("The concurrency lock module was unable to identify your C library.")
|
||||
#endif
|
||||
|
||||
/// A threading lock based on `libpthread` instead of `libdispatch`.
|
||||
@@ -46,47 +54,67 @@ import Glibc
|
||||
/// 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 {
|
||||
package final class Lock {
|
||||
#if os(Windows)
|
||||
fileprivate let mutex: UnsafeMutablePointer<SRWLOCK> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#else
|
||||
#elseif os(FreeBSD) || os(OpenBSD)
|
||||
fileprivate let mutex: UnsafeMutablePointer<pthread_mutex_t?> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
fileprivate let mutex: UnsafeMutablePointer<pthread_mutex_t> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#endif
|
||||
|
||||
/// Create a new lock.
|
||||
public init() {
|
||||
package init() {
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.mutex)
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
var attr = pthread_mutexattr_t(bitPattern: 0)
|
||||
#else
|
||||
var attr = pthread_mutexattr_t()
|
||||
pthread_mutexattr_init(&attr)
|
||||
pthread_mutexattr_settype(&attr, .init(PTHREAD_MUTEX_ERRORCHECK))
|
||||
#endif
|
||||
var err = pthread_mutexattr_init(&attr)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutexattr_init with error \(err)")
|
||||
debugOnly {
|
||||
#if os(FreeBSD) || os(OpenBSD)
|
||||
pthread_mutexattr_settype(&attr, .init(PTHREAD_MUTEX_ERRORCHECK.rawValue))
|
||||
#else
|
||||
pthread_mutexattr_settype(&attr, .init(PTHREAD_MUTEX_ERRORCHECK))
|
||||
#endif
|
||||
}
|
||||
|
||||
let err = pthread_mutex_init(self.mutex, &attr)
|
||||
err = pthread_mutex_init(self.mutex, &attr)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
// `pthread_mutexattr_t` only lives during init; destroy here instead of deinit.
|
||||
let attrDestroyErr = pthread_mutexattr_destroy(&attr)
|
||||
precondition(
|
||||
attrDestroyErr == 0,
|
||||
"\(#function) failed in pthread_mutexattr_destroy with error \(attrDestroyErr)"
|
||||
)
|
||||
#endif
|
||||
}
|
||||
|
||||
deinit {
|
||||
#if os(Windows)
|
||||
// SRWLOCK does not need to be free'd
|
||||
#else
|
||||
mutex.deallocate()
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_mutex_destroy(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
mutex.deallocate()
|
||||
#endif
|
||||
self.mutex.deallocate()
|
||||
}
|
||||
|
||||
/// Acquire the lock.
|
||||
///
|
||||
/// Whenever possible, consider using `withLock` instead of this method and
|
||||
/// `unlock`, to simplify lock handling.
|
||||
public func lock() {
|
||||
package func lock() {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.mutex)
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_mutex_lock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
@@ -96,17 +124,15 @@ internal final class Lock {
|
||||
///
|
||||
/// Whenever possible, consider using `withLock` instead of this method and
|
||||
/// `lock`, to simplify lock handling.
|
||||
public func unlock() {
|
||||
package func unlock() {
|
||||
#if os(Windows)
|
||||
ReleaseSRWLockExclusive(self.mutex)
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_mutex_unlock(self.mutex)
|
||||
precondition(err == 0, "\(#function) failed in pthread_mutex with error \(err)")
|
||||
#endif
|
||||
}
|
||||
}
|
||||
|
||||
extension Lock {
|
||||
/// Acquire the lock for the duration of the given block.
|
||||
///
|
||||
/// This convenience method should be preferred to `lock` and `unlock` in
|
||||
@@ -116,7 +142,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()
|
||||
@@ -126,22 +152,44 @@ 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)
|
||||
}
|
||||
}
|
||||
|
||||
/// A utility function that runs the body code only in debug builds, without
|
||||
/// emitting compiler warnings.
|
||||
///
|
||||
/// This is currently the only way to do this in Swift: see
|
||||
/// https://forums.swift.org/t/support-debug-only-code/11037 for a discussion.
|
||||
@inlinable
|
||||
internal func debugOnly(_ body: () -> Void) {
|
||||
assert(
|
||||
{
|
||||
body()
|
||||
return true
|
||||
}()
|
||||
)
|
||||
}
|
||||
|
||||
extension Lock: @unchecked Sendable {}
|
||||
|
||||
/// A reader/writer threading lock based on `libpthread` instead of `libdispatch`.
|
||||
///
|
||||
/// This object provides a lock on top of a single `pthread_rwlock_t`. This kind
|
||||
/// 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 ReadWriteLock {
|
||||
#if os(Windows)
|
||||
internal final class ReadWriteLock: @unchecked Sendable {
|
||||
#if canImport(WASILibc)
|
||||
// WASILibc is single threaded, provides no locks
|
||||
#elseif os(Windows)
|
||||
fileprivate let rwlock: UnsafeMutablePointer<SRWLOCK> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
fileprivate var shared: Bool = true
|
||||
#elseif os(FreeBSD) || os(OpenBSD)
|
||||
fileprivate let rwlock: UnsafeMutablePointer<pthread_rwlock_t?> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
#else
|
||||
fileprivate let rwlock: UnsafeMutablePointer<pthread_rwlock_t> =
|
||||
UnsafeMutablePointer.allocate(capacity: 1)
|
||||
@@ -151,7 +199,7 @@ internal final class ReadWriteLock {
|
||||
public init() {
|
||||
#if os(Windows)
|
||||
InitializeSRWLock(self.rwlock)
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_init(self.rwlock, nil)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -159,23 +207,23 @@ internal final class ReadWriteLock {
|
||||
|
||||
deinit {
|
||||
#if os(Windows)
|
||||
// SRWLOCK does not need to be free'd
|
||||
#else
|
||||
self.rwlock.deallocate()
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_destroy(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
self.rwlock.deallocate()
|
||||
#endif
|
||||
}
|
||||
|
||||
/// Acquire a reader lock.
|
||||
///
|
||||
/// Whenever possible, consider using `withReaderLock` instead of this
|
||||
/// method and `unlock`, to simplify lock handling.
|
||||
public func lockRead() {
|
||||
fileprivate func lockRead() {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockShared(self.rwlock)
|
||||
self.shared = true
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_rdlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -185,11 +233,11 @@ internal final class ReadWriteLock {
|
||||
///
|
||||
/// Whenever possible, consider using `withWriterLock` instead of this
|
||||
/// method and `unlock`, to simplify lock handling.
|
||||
public func lockWrite() {
|
||||
fileprivate func lockWrite() {
|
||||
#if os(Windows)
|
||||
AcquireSRWLockExclusive(self.rwlock)
|
||||
self.shared = false
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_wrlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -200,14 +248,14 @@ internal final class ReadWriteLock {
|
||||
/// Whenever possible, consider using `withReaderLock` and `withWriterLock`
|
||||
/// instead of this method and `lockRead` and `lockWrite`, to simplify lock
|
||||
/// handling.
|
||||
public func unlock() {
|
||||
fileprivate func unlock() {
|
||||
#if os(Windows)
|
||||
if self.shared {
|
||||
ReleaseSRWLockShared(self.rwlock)
|
||||
} else {
|
||||
ReleaseSRWLockExclusive(self.rwlock)
|
||||
}
|
||||
#else
|
||||
#elseif (compiler(<6.1) && !os(WASI)) || (compiler(>=6.1) && _runtime(_multithreaded))
|
||||
let err = pthread_rwlock_unlock(self.rwlock)
|
||||
precondition(err == 0, "\(#function) failed in pthread_rwlock with error \(err)")
|
||||
#endif
|
||||
@@ -261,4 +309,3 @@ extension ReadWriteLock {
|
||||
try self.withWriterLock(body)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,125 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A log event that contains all the information about a single log statement.
|
||||
///
|
||||
/// `LogEvent` is passed to a ``LogHandler`` via ``LogHandler/log(event:)`` and carries every piece of data emitted
|
||||
/// at the log call site. Handlers may inspect, modify, or forward any of the event's properties.
|
||||
///
|
||||
/// All properties are mutable so that handler wrappers (for example ``MultiplexLogHandler``) can rewrite fields
|
||||
/// such as metadata or source before forwarding to downstream handlers.
|
||||
public struct LogEvent: Sendable {
|
||||
/// The log level of this event.
|
||||
public var level: Logger.Level
|
||||
|
||||
/// The message of this event.
|
||||
public var message: Logger.Message
|
||||
|
||||
/// The error associated with this event, if any.
|
||||
public var error: (any Error)?
|
||||
|
||||
/// The metadata associated with this event, if any.
|
||||
public var metadata: Logger.Metadata? {
|
||||
get { self._metadata }
|
||||
set { self._metadata = newValue }
|
||||
}
|
||||
|
||||
private var _metadata: Logger.Metadata?
|
||||
|
||||
/// The source where this log event originated, for example the logging module.
|
||||
///
|
||||
/// When no explicit source was provided at the call site, this is derived lazily from ``file``
|
||||
/// every time this property is accessed. Handlers that never read this property pay no
|
||||
/// allocation cost for source computation.
|
||||
public var source: String {
|
||||
@inlinable get { self._source ?? Logger.currentModule(fileID: self.file) }
|
||||
@inlinable set { self._source = newValue }
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal var _source: String?
|
||||
|
||||
/// The file this log event originates from.
|
||||
public var file: String
|
||||
|
||||
/// The function this log event originates from.
|
||||
public var function: String
|
||||
|
||||
/// The line this log event originates from.
|
||||
public var line: UInt
|
||||
|
||||
/// Creates a new log event.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of this event.
|
||||
/// - message: The message of this event.
|
||||
/// - metadata: The metadata associated with this event, if any.
|
||||
/// - source: The source where this log event originated. When `nil`, ``source`` is derived lazily
|
||||
/// from ``file`` on first access so handlers that never read it pay no allocation cost.
|
||||
/// - file: The file this log event originates from.
|
||||
/// - function: The function this log event originates from.
|
||||
/// - line: The line this log event originates from.
|
||||
public init(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.init(
|
||||
level: level,
|
||||
message: message,
|
||||
error: nil,
|
||||
metadata: metadata,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
|
||||
/// Creates a new log event.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of this event.
|
||||
/// - message: The message of this event.
|
||||
/// - error: The error associated with this event, if any.
|
||||
/// - metadata: The metadata associated with this event, if any.
|
||||
/// - source: The source where this log event originated. When `nil`, ``source`` is derived lazily
|
||||
/// from ``file`` on first access so handlers that never read it pay no allocation cost.
|
||||
/// - file: The file this log event originates from.
|
||||
/// - function: The function this log event originates from.
|
||||
/// - line: The line this log event originates from.
|
||||
public init(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
error: (any Error)?,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.level = level
|
||||
self.message = message
|
||||
self.error = error
|
||||
self._metadata = metadata
|
||||
self._source = source
|
||||
self.file = file
|
||||
self.function = function
|
||||
self.line = line
|
||||
}
|
||||
}
|
||||
@@ -12,54 +12,61 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// 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.
|
||||
/// To use the SwiftLog API, please refer to the documentation of `Logger`.
|
||||
/// 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 ``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
|
||||
///
|
||||
/// When developing your `LogHandler`, please make sure the following test works.
|
||||
///
|
||||
/// ```swift
|
||||
/// LoggingSystem.bootstrap(MyLogHandler.init) // your LogHandler might have a different bootstrapping step
|
||||
/// var logger1 = Logger(label: "first logger")
|
||||
/// logger1.logLevel = .debug
|
||||
/// logger1[metadataKey: "only-on"] = "first"
|
||||
/// @Test
|
||||
/// func logHandlerValueSemantics() {
|
||||
/// LoggingSystem.bootstrap(MyLogHandler.init)
|
||||
/// var logger1 = Logger(label: "first logger")
|
||||
/// logger1.logLevel = .debug
|
||||
/// logger1[metadataKey: "only-on"] = "first"
|
||||
///
|
||||
/// var logger2 = logger1
|
||||
/// logger2.logLevel = .error // this must not override `logger1`'s log level
|
||||
/// logger2[metadataKey: "only-on"] = "second" // this must not override `logger1`'s metadata
|
||||
/// var logger2 = logger1
|
||||
/// logger2.logLevel = .error // Must not affect logger1
|
||||
/// logger2[metadataKey: "only-on"] = "second" // Must not affect logger1
|
||||
///
|
||||
/// XCTAssertEqual(.debug, logger1.logLevel)
|
||||
/// XCTAssertEqual(.error, logger2.logLevel)
|
||||
/// XCTAssertEqual("first", logger1[metadataKey: "only-on"])
|
||||
/// XCTAssertEqual("second", logger2[metadataKey: "only-on"])
|
||||
/// // These expectations must pass
|
||||
/// #expect(logger1.logLevel == .debug)
|
||||
/// #expect(logger2.logLevel == .error)
|
||||
/// #expect(logger1[metadataKey: "only-on"] == "first")
|
||||
/// #expect(logger2[metadataKey: "only-on"] == "second")
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// ### 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
|
||||
///
|
||||
@@ -74,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) {
|
||||
/// // [...]
|
||||
/// }
|
||||
///
|
||||
@@ -101,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() }
|
||||
@@ -110,34 +126,67 @@
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// Please note that the above `LogHandler` will still pass the 'log level is a value' test above it iff the global log
|
||||
/// level has not been overridden. And most importantly it passes the requirement listed above: A change to the log
|
||||
/// level on one `Logger` should not affect the log level of another `Logger` variable.
|
||||
public protocol LogHandler {
|
||||
/// This method is called when a `LogHandler` must emit a log message. There is no need for the `LogHandler` to
|
||||
/// check if the `level` is above or below the configured `logLevel` as `Logger` already performed this check and
|
||||
/// determined that a message should be logged.
|
||||
/// > 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 log handler uses when a log statement is about to be emitted.
|
||||
///
|
||||
/// - 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.
|
||||
func log(level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt)
|
||||
/// 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 }
|
||||
|
||||
/// SwiftLog 1.0 compatibility method. Please do _not_ implement, implement
|
||||
/// `log(level:message:metadata:source:file:function:line:)` instead.
|
||||
@available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
|
||||
func log(level: Logging.Logger.Level, message: Logging.Logger.Message, metadata: Logging.Logger.Metadata?, file: String, function: String, line: UInt)
|
||||
/// The library calls this method when a log handler must emit a log message.
|
||||
///
|
||||
/// There is no need for the `LogHandler` to check if the level is above or below the configured `logLevel`
|
||||
/// as `Logger` already performed this check and determined that a message should be logged.
|
||||
///
|
||||
/// - Parameter event: The log event containing the level, message, metadata, and source location.
|
||||
func log(event: LogEvent)
|
||||
|
||||
/// Please do _not_ implement this method when you create a `LogHandler` implementation.
|
||||
/// Implement ``log(event:)`` instead.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - source: The source where the log message originated, for example the logging module.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
|
||||
/// SwiftLog 1.0 log compatibility method.
|
||||
///
|
||||
/// Please do _not_ implement this method when you create a LogHandler implementation.
|
||||
/// Implement ``log(event:)`` instead.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - level: The log level of the message.
|
||||
/// - message: The message to log. To obtain a `String` representation call `message.description`.
|
||||
/// - metadata: The metadata associated to this log message.
|
||||
/// - file: The file this log message originates from.
|
||||
/// - function: The function this log message originates from.
|
||||
/// - line: The line this log message originates from.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
func log(
|
||||
level: Logging.Logger.Level,
|
||||
message: Logging.Logger.Message,
|
||||
metadata: Logging.Logger.Metadata?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
)
|
||||
|
||||
/// Add, remove, or change the logging metadata.
|
||||
///
|
||||
@@ -164,25 +213,101 @@ public protocol LogHandler {
|
||||
}
|
||||
|
||||
extension LogHandler {
|
||||
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
|
||||
public func log(level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt) {
|
||||
self.log(level: level, message: message, metadata: metadata, file: file, function: function, line: line)
|
||||
}
|
||||
|
||||
@available(*, deprecated, renamed: "log(level:message:metadata:source:file:function:line:)")
|
||||
public func log(level: Logging.Logger.Level, message: Logging.Logger.Message, metadata: Logging.Logger.Metadata?, file: String, function: String, line: UInt) {
|
||||
self.log(level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: Logger.currentModule(filePath: file),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line)
|
||||
/// 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
|
||||
}
|
||||
set {
|
||||
#if DEBUG
|
||||
if LoggingSystem.warnOnceLogHandlerNotSupportedMetadataProvider(Self.self) {
|
||||
self.log(
|
||||
event: LogEvent(
|
||||
level: .warning,
|
||||
message:
|
||||
"Attempted to set metadataProvider on \(Self.self) that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.",
|
||||
metadata: nil,
|
||||
source: "Logging",
|
||||
file: #file,
|
||||
function: #function,
|
||||
line: #line
|
||||
)
|
||||
)
|
||||
}
|
||||
#endif
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension LogHandler {
|
||||
/// Default implementation of ``log(event:)`` for backward compatibility with handlers that implement the
|
||||
/// deprecated flat-parameter method.
|
||||
///
|
||||
/// Handlers that implement ``log(level:message:metadata:source:file:function:line:)`` continue to work
|
||||
/// without any source changes; this default forwards the event's fields to that method.
|
||||
///
|
||||
/// New handlers should implement ``log(event:)`` directly and rely on this default only as a fallback.
|
||||
///
|
||||
/// > Warning: Do not call this default directly. It exists only as a backward-compatibility bridge.
|
||||
/// Implement ``log(event:)`` in your ``LogHandler`` instead.
|
||||
@available(*, deprecated, message: "You should implement this method instead of using the default implementation")
|
||||
public func log(event: LogEvent) {
|
||||
self.log(
|
||||
level: event.level,
|
||||
message: event.message,
|
||||
metadata: event.metadata,
|
||||
source: event.source,
|
||||
file: event.file,
|
||||
function: event.function,
|
||||
line: event.line
|
||||
)
|
||||
}
|
||||
|
||||
/// A default implementation for a log message handler that forwards to the SwiftLog 1.0 compatibility method.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
|
||||
/// A default implementation for the SwiftLog 1.0 log message handler.
|
||||
@available(*, deprecated, renamed: "log(event:)")
|
||||
public func log(
|
||||
level: Logging.Logger.Level,
|
||||
message: Logging.Logger.Message,
|
||||
metadata: Logging.Logger.Metadata?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.log(
|
||||
level: level,
|
||||
message: message,
|
||||
metadata: metadata,
|
||||
source: Logger.currentModule(filePath: file),
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Sendable support helpers
|
||||
|
||||
@preconcurrency public protocol _SwiftLogSendableLogHandler: Sendable {}
|
||||
+1737
-644
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,101 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2022 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif os(Windows)
|
||||
import CRT
|
||||
#elseif canImport(Glibc)
|
||||
import Glibc
|
||||
#elseif canImport(Android)
|
||||
import Android
|
||||
#elseif canImport(Musl)
|
||||
import Musl
|
||||
#elseif canImport(WASILibc)
|
||||
import WASILibc
|
||||
#else
|
||||
#error("Unsupported runtime")
|
||||
#endif
|
||||
|
||||
@preconcurrency protocol _SwiftLogSendable: Sendable {}
|
||||
|
||||
extension Logger {
|
||||
/// A MetadataProvider automatically injects runtime-generated metadata
|
||||
/// to all logs emitted by a logger.
|
||||
///
|
||||
/// ### Example
|
||||
/// A metadata provider may be used to automatically inject metadata such as
|
||||
/// trace IDs:
|
||||
///
|
||||
/// ```swift
|
||||
/// import Tracing // https://github.com/apple/swift-distributed-tracing
|
||||
///
|
||||
/// let metadataProvider = MetadataProvider {
|
||||
/// guard let traceID = Baggage.current?.traceID else { return nil }
|
||||
/// return ["traceID": "\(traceID)"]
|
||||
/// }
|
||||
/// let logger = Logger(label: "example", metadataProvider: metadataProvider)
|
||||
/// var baggage = Baggage.topLevel
|
||||
/// baggage.traceID = 42
|
||||
/// Baggage.withValue(baggage) {
|
||||
/// logger.info("hello") // automatically includes ["traceID": "42"] metadata
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// We recommend referring to [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing)
|
||||
/// for metadata providers which make use of its tracing and metadata propagation infrastructure. It is however
|
||||
/// possible to make use of metadata providers independently of tracing and instruments provided by that library,
|
||||
/// if necessary.
|
||||
public struct MetadataProvider: _SwiftLogSendable {
|
||||
/// Provide ``Logger.Metadata`` from the current context.
|
||||
@usableFromInline
|
||||
internal let _provideMetadata: @Sendable () -> Metadata
|
||||
|
||||
/// Creates a new metadata provider.
|
||||
///
|
||||
/// - Parameter provideMetadata: A closure that extracts metadata from the current execution context.
|
||||
public init(_ provideMetadata: @escaping @Sendable () -> Metadata) {
|
||||
self._provideMetadata = provideMetadata
|
||||
}
|
||||
|
||||
/// Invokes the metadata provider and returns the generated contextual metadata.
|
||||
public func get() -> Metadata {
|
||||
self._provideMetadata()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger.MetadataProvider {
|
||||
/// A pseudo metadata provider that merges metadata from multiple other metadata providers.
|
||||
///
|
||||
/// ### Merging conflicting keys
|
||||
///
|
||||
/// `MetadataProvider`s are invoked left to right in the order specified in the `providers` argument.
|
||||
/// In case multiple providers try to add a value for the same key, the last provider "wins" and its value is being used.
|
||||
///
|
||||
/// - Parameter providers: An array of `MetadataProvider`s to delegate to. The array must not be empty.
|
||||
/// - Returns: A pseudo-`MetadataProvider` merging metadata from the given `MetadataProvider`s.
|
||||
public static func multiplex(_ providers: [Logger.MetadataProvider]) -> Logger.MetadataProvider? {
|
||||
assert(!providers.isEmpty, "providers MUST NOT be empty")
|
||||
return Logger.MetadataProvider {
|
||||
providers.reduce(into: [:]) { metadata, provider in
|
||||
let providedMetadata = provider.get()
|
||||
guard !providedMetadata.isEmpty else {
|
||||
return
|
||||
}
|
||||
metadata.merge(providedMetadata, uniquingKeysWith: { _, rhs in rhs })
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,156 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 errorEquality() throws {
|
||||
let (logHandler, logger) = self.makeTestLogger()
|
||||
logger.info("hello", error: TestError.first)
|
||||
let entry = try #require(logHandler.entries.first)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
== InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: TestError.first,
|
||||
metadata: [:],
|
||||
)
|
||||
)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
!= InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: nil,
|
||||
metadata: [:],
|
||||
)
|
||||
)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
!= InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: TestError.second,
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
|
||||
#expect(
|
||||
entry
|
||||
!= InMemoryLogHandler.Entry(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
error: Nested.TestError.first,
|
||||
metadata: [:]
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
@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)
|
||||
}
|
||||
|
||||
enum TestError: Error {
|
||||
case first
|
||||
case second
|
||||
}
|
||||
|
||||
struct Nested {
|
||||
enum TestError: Error {
|
||||
case first
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,35 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// LinuxMain.swift
|
||||
//
|
||||
import XCTest
|
||||
|
||||
///
|
||||
/// NOTE: This file was generated by generate_linux_tests.rb
|
||||
///
|
||||
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
|
||||
///
|
||||
|
||||
#if os(Linux) || os(FreeBSD)
|
||||
@testable import LoggingTests
|
||||
|
||||
XCTMain([
|
||||
testCase(CompatibilityTest.allTests),
|
||||
testCase(GlobalLoggerTest.allTests),
|
||||
testCase(LocalLoggerTest.allTests),
|
||||
testCase(LoggingTest.allTests),
|
||||
testCase(MDCTest.allTests),
|
||||
])
|
||||
#endif
|
||||
@@ -1,31 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// CompatibilityTest+XCTest.swift
|
||||
//
|
||||
import XCTest
|
||||
|
||||
///
|
||||
/// NOTE: This file was generated by generate_linux_tests.rb
|
||||
///
|
||||
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
|
||||
///
|
||||
|
||||
extension CompatibilityTest {
|
||||
static var allTests: [(String, (CompatibilityTest) -> () throws -> Void)] {
|
||||
return [
|
||||
("testAllLogLevelsWorkWithOldSchoolLogHandlerWorks", testAllLogLevelsWorkWithOldSchoolLogHandlerWorks),
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -12,14 +12,16 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/* NOT @testable */ import Logging
|
||||
import XCTest
|
||||
// Not testable
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
final class CompatibilityTest: XCTestCase {
|
||||
func testAllLogLevelsWorkWithOldSchoolLogHandlerWorks() {
|
||||
struct CompatibilityTest {
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
@Test func allLogLevelsWorkWithOldSchoolLogHandlerWorks() {
|
||||
let testLogging = OldSchoolTestLogging()
|
||||
|
||||
var logger = Logger(label: "\(#function)", factory: testLogging.make)
|
||||
var logger = Logger(label: "\(#function)", factory: { testLogging.make(label: $0) })
|
||||
logger.logLevel = .trace
|
||||
|
||||
logger.trace("yes: trace")
|
||||
@@ -39,40 +41,131 @@ final class CompatibilityTest: XCTestCase {
|
||||
testLogging.history.assertExist(level: .error, message: "yes: error", source: "no source")
|
||||
testLogging.history.assertExist(level: .critical, message: "yes: critical", source: "no source")
|
||||
}
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
@Test func allLogLevelsWorkWithNewerButStillOldLogHandlerWorks() {
|
||||
let testLogging = NewerButStillOldTestLogging()
|
||||
|
||||
var logger = Logger(label: "\(#function)", factory: { testLogging.make(label: $0) })
|
||||
logger.logLevel = .trace
|
||||
|
||||
logger.trace("yes: trace", source: "yes: trace source")
|
||||
logger.debug("yes: debug", source: "yes: debug source")
|
||||
logger.info("yes: info", source: "yes: info source")
|
||||
logger.notice("yes: notice", source: "yes: notice source")
|
||||
logger.warning("yes: warning", source: "yes: warning source")
|
||||
logger.error("yes: error", source: "yes: error source")
|
||||
logger.critical("yes: critical", source: "yes: critical source")
|
||||
|
||||
// Please note that the source is _not_ propagated (because the backend doesn't support it).
|
||||
testLogging.history.assertExist(level: .trace, message: "yes: trace", source: "yes: trace source")
|
||||
testLogging.history.assertExist(level: .debug, message: "yes: debug", source: "yes: debug source")
|
||||
testLogging.history.assertExist(level: .info, message: "yes: info", source: "yes: info source")
|
||||
testLogging.history.assertExist(level: .notice, message: "yes: notice", source: "yes: notice source")
|
||||
testLogging.history.assertExist(level: .warning, message: "yes: warning", source: "yes: warning source")
|
||||
testLogging.history.assertExist(level: .error, message: "yes: error", source: "yes: error source")
|
||||
testLogging.history.assertExist(level: .critical, message: "yes: critical", source: "yes: critical source")
|
||||
}
|
||||
}
|
||||
|
||||
private struct OldSchoolTestLogging {
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
|
||||
func make(label: String) -> LogHandler {
|
||||
return OldSchoolLogHandler(label: label,
|
||||
config: self.config,
|
||||
recorder: self.recorder,
|
||||
metadata: [:],
|
||||
logLevel: .info)
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
func make(label: String) -> any LogHandler {
|
||||
OldSchoolLogHandler(
|
||||
label: label,
|
||||
config: self.config,
|
||||
recorder: self.recorder,
|
||||
metadata: [:],
|
||||
logLevel: .info
|
||||
)
|
||||
}
|
||||
|
||||
var config: Config { return self._config }
|
||||
var history: History { return self.recorder }
|
||||
var config: Config { self._config }
|
||||
var history: some History { self.recorder }
|
||||
}
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
private struct OldSchoolLogHandler: LogHandler {
|
||||
var label: String
|
||||
let config: Config
|
||||
let recorder: Recorder
|
||||
|
||||
func make(label: String) -> LogHandler {
|
||||
return TestLogHandler(label: label, config: self.config, recorder: self.recorder)
|
||||
func make(label: String) -> some LogHandler {
|
||||
TestLogHandler(label: label, config: self.config, recorder: self.recorder)
|
||||
}
|
||||
|
||||
func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt) {
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.recorder.record(level: level, metadata: metadata, message: message, source: "no source")
|
||||
}
|
||||
|
||||
subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
return self.metadata[metadataKey]
|
||||
self.metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
self.metadata[metadataKey] = newValue
|
||||
}
|
||||
}
|
||||
|
||||
var metadata: Logger.Metadata
|
||||
|
||||
var logLevel: Logger.Level
|
||||
}
|
||||
|
||||
private struct NewerButStillOldTestLogging {
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
func make(label: String) -> any LogHandler {
|
||||
NewerButStillOldLogHandler(
|
||||
label: label,
|
||||
config: self.config,
|
||||
recorder: self.recorder,
|
||||
metadata: [:],
|
||||
logLevel: .info
|
||||
)
|
||||
}
|
||||
|
||||
var config: Config { self._config }
|
||||
var history: some History { self.recorder }
|
||||
}
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
private struct NewerButStillOldLogHandler: LogHandler {
|
||||
var label: String
|
||||
let config: Config
|
||||
let recorder: Recorder
|
||||
|
||||
func make(label: String) -> some LogHandler {
|
||||
TestLogHandler(label: label, config: self.config, recorder: self.recorder)
|
||||
}
|
||||
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.recorder.record(level: level, metadata: metadata, message: message, source: source)
|
||||
}
|
||||
|
||||
subscript(metadataKey metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
self.metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
self.metadata[metadataKey] = newValue
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// GlobalLoggingTest+XCTest.swift
|
||||
//
|
||||
import XCTest
|
||||
|
||||
///
|
||||
/// NOTE: This file was generated by generate_linux_tests.rb
|
||||
///
|
||||
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
|
||||
///
|
||||
|
||||
extension GlobalLoggerTest {
|
||||
static var allTests: [(String, (GlobalLoggerTest) -> () throws -> Void)] {
|
||||
return [
|
||||
("test1", test1),
|
||||
("test2", test2),
|
||||
("test3", test3),
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -11,17 +11,23 @@
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
@testable import Logging
|
||||
import XCTest
|
||||
|
||||
class GlobalLoggerTest: XCTestCase {
|
||||
func test1() throws {
|
||||
import Dispatch
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
/// 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)
|
||||
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
|
||||
@@ -37,15 +43,19 @@ 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)
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config to log errors and above
|
||||
logging.config.set(value: Logger.Level.error)
|
||||
@@ -58,21 +68,32 @@ class GlobalLoggerTest: XCTestCase {
|
||||
logging.history.assertNotExist(level: .info, message: "Struct2::doSomethingElse")
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomething")
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomethingElse", metadata: ["foo": "bar"])
|
||||
logging.history.assertNotExist(level: .warning, message: "Struct3::doSomethingElseAsync", metadata: ["foo": "bar"])
|
||||
logging.history.assertNotExist(
|
||||
level: .warning,
|
||||
message: "Struct3::doSomethingElseAsync",
|
||||
metadata: ["foo": "bar"]
|
||||
)
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomething", metadata: ["foo": "bar"])
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomethingAsync", metadata: ["foo": "bar"])
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomethingElse::Local", metadata: ["baz": "qux"])
|
||||
logging.history.assertNotExist(
|
||||
level: .debug,
|
||||
message: "Struct3::doSomethingElse::Local",
|
||||
metadata: ["baz": "qux"]
|
||||
)
|
||||
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)
|
||||
LoggingSystem.bootstrapInternal { logging.make(label: $0) }
|
||||
|
||||
// change test logging config
|
||||
logging.config.set(value: .warning)
|
||||
@@ -90,7 +111,11 @@ class GlobalLoggerTest: XCTestCase {
|
||||
logging.history.assertExist(level: .warning, message: "Struct3::doSomethingElseAsync", metadata: ["foo": "bar"])
|
||||
logging.history.assertExist(level: .info, message: "TestLibrary::doSomething", metadata: ["foo": "bar"])
|
||||
logging.history.assertExist(level: .info, message: "TestLibrary::doSomethingAsync", metadata: ["foo": "bar"])
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomethingElse::Local", metadata: ["baz": "qux"])
|
||||
logging.history.assertNotExist(
|
||||
level: .debug,
|
||||
message: "Struct3::doSomethingElse::Local",
|
||||
metadata: ["baz": "qux"]
|
||||
)
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomethingElse::end")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct3::doSomething::end")
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct2::doSomethingElse::end")
|
||||
@@ -99,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")
|
||||
|
||||
@@ -112,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")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -128,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")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -139,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() {
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// LocalLoggingTest+XCTest.swift
|
||||
//
|
||||
import XCTest
|
||||
|
||||
///
|
||||
/// NOTE: This file was generated by generate_linux_tests.rb
|
||||
///
|
||||
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
|
||||
///
|
||||
|
||||
extension LocalLoggerTest {
|
||||
static var allTests: [(String, (LocalLoggerTest) -> () throws -> Void)] {
|
||||
return [
|
||||
("test1", test1),
|
||||
("test2", test2),
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -11,19 +11,22 @@
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Dispatch
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
import XCTest
|
||||
|
||||
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)
|
||||
|
||||
// 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")
|
||||
@@ -33,58 +36,96 @@ 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::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)
|
||||
|
||||
// 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
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomething") // global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomethingElse") // global context
|
||||
logging.history.assertExist(level: .info, message: "Struct2::doSomething") // local context
|
||||
logging.history.assertExist(level: .info, message: "Struct2::doSomethingElse") // local context
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomething", metadata: ["bar": "baz"]) // local context
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomethingElse", metadata: ["bar": "baz"]) // local context
|
||||
logging.history.assertExist(level: .warning, message: "Struct3::doSomethingElseAsync", metadata: ["bar": "baz"]) // local context
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomething") // global context
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomethingAsync") // global context
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::Local", metadata: ["bar": "baz", "baz": "qux"]) // hyper local context
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomethingElse::end", metadata: ["bar": "baz"]) // local context
|
||||
logging.history.assertExist(level: .debug, message: "Struct2::doSomethingElse::end") // local context
|
||||
logging.history.assertExist(level: .debug, message: "Struct3::doSomething::end", metadata: ["bar": "baz"]) // local context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomethingElse::end") // global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomething::end") // global context
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomething")
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .debug, message: "Struct1::doSomethingElse")
|
||||
// local context
|
||||
logging.history.assertExist(level: .info, message: "Struct2::doSomething")
|
||||
// local context
|
||||
logging.history.assertExist(level: .info, message: "Struct2::doSomethingElse")
|
||||
// local context
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomething", metadata: ["bar": "baz"])
|
||||
// local context
|
||||
logging.history.assertExist(level: .error, message: "Struct3::doSomethingElse", metadata: ["bar": "baz"])
|
||||
// local context
|
||||
logging.history.assertExist(level: .warning, message: "Struct3::doSomethingElseAsync", metadata: ["bar": "baz"])
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomething")
|
||||
// global context
|
||||
logging.history.assertNotExist(level: .info, message: "TestLibrary::doSomethingAsync")
|
||||
// hyper local .debug context
|
||||
logging.history.assertExist(
|
||||
level: .debug,
|
||||
message: "Struct3::doSomethingElse::Local",
|
||||
metadata: ["bar": "baz", "baz": "qux"]
|
||||
)
|
||||
// local .debug context
|
||||
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"]
|
||||
)
|
||||
// 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")
|
||||
}
|
||||
}
|
||||
|
||||
// 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 {
|
||||
get { return self.logger.logLevel }
|
||||
get { self.logger.logLevel }
|
||||
set { self.logger.logLevel = newValue }
|
||||
}
|
||||
|
||||
// since logger is a value type, we can reuse our copy to manage metadata
|
||||
subscript(metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get { return self.logger[metadataKey: metadataKey] }
|
||||
get { self.logger[metadataKey: metadataKey] }
|
||||
set { self.logger[metadataKey: metadataKey] = newValue }
|
||||
}
|
||||
}
|
||||
@@ -109,7 +150,7 @@ private struct Struct1 {
|
||||
private struct Struct2 {
|
||||
func doSomething(context: Context) {
|
||||
var c = context
|
||||
c.logLevel = .info // only effects from this point on
|
||||
c.logLevel = .info // only effects from this point on
|
||||
c.logger.info("Struct2::doSomething")
|
||||
self.doSomethingElse(context: c)
|
||||
c.logger.debug("Struct2::doSomething::end")
|
||||
@@ -117,10 +158,11 @@ private struct Struct2 {
|
||||
|
||||
private func doSomethingElse(context: Context) {
|
||||
var c = context
|
||||
c.logLevel = .debug // only effects from this point on
|
||||
c.logLevel = .debug // only effects from this point on
|
||||
c.logger.info("Struct2::doSomethingElse")
|
||||
Struct3().doSomething(context: c)
|
||||
c.logger.debug("Struct2::doSomethingElse::end")
|
||||
c.logger.trace("Struct2::doSomethingElse::end::lastLine")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -129,10 +171,11 @@ private struct Struct3 {
|
||||
|
||||
func doSomething(context: Context) {
|
||||
var c = context
|
||||
c["bar"] = "baz" // only effects from this point on
|
||||
c["bar"] = "baz" // only effects from this point on
|
||||
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) {
|
||||
@@ -153,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")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2026 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the SwiftNIO open source project
|
||||
//
|
||||
// Copyright (c) 2017-2026 Apple Inc. and the SwiftNIO project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if canImport(Dispatch)
|
||||
import Dispatch
|
||||
private let canImportDispatch = true
|
||||
#else
|
||||
private let canImportDispatch = false
|
||||
#endif
|
||||
|
||||
@Suite("Lock Test Suite")
|
||||
struct LockTestSuite {
|
||||
@Test(.enabled(if: canImportDispatch)) func testLockMutualExclusion() {
|
||||
#if canImport(Dispatch)
|
||||
let l = Lock()
|
||||
|
||||
nonisolated(unsafe) var x = 1
|
||||
let q = DispatchQueue(label: "q")
|
||||
let g = DispatchGroup()
|
||||
let sem1 = DispatchSemaphore(value: 0)
|
||||
let sem2 = DispatchSemaphore(value: 0)
|
||||
|
||||
l.lock()
|
||||
|
||||
q.async(group: g) {
|
||||
sem1.signal()
|
||||
l.lock()
|
||||
x = 2
|
||||
l.unlock()
|
||||
sem2.signal()
|
||||
}
|
||||
|
||||
sem1.wait()
|
||||
#expect(DispatchTimeoutResult.timedOut == g.wait(timeout: .now() + 0.1))
|
||||
#expect(1 == x)
|
||||
|
||||
l.unlock()
|
||||
sem2.wait()
|
||||
|
||||
l.lock()
|
||||
#expect(2 == x)
|
||||
l.unlock()
|
||||
#endif // canImport(Dispatch)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,189 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
struct LogEventTest {
|
||||
|
||||
// MARK: - Lazy source computation
|
||||
|
||||
@Test func sourceIsDerivedFromFileWhenNotProvided() {
|
||||
let event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.source == "MyModule")
|
||||
}
|
||||
|
||||
@Test func sourceUsesExplicitValueWhenProvided() {
|
||||
let event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: "ExplicitSource",
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.source == "ExplicitSource")
|
||||
}
|
||||
|
||||
@Test func sourceSetterOverridesLazyValue() {
|
||||
var event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.source == "MyModule")
|
||||
|
||||
event.source = "OverriddenSource"
|
||||
#expect(event.source == "OverriddenSource")
|
||||
}
|
||||
|
||||
@Test func sourceLazyDerivationDoesNotStoreComputedValue() {
|
||||
let event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "MyModule/MyFile.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
// Internal _source should be nil when no explicit source was provided.
|
||||
#expect(event._source == nil)
|
||||
// Accessing source derives it from file but does not mutate _source (it's a computed get).
|
||||
_ = event.source
|
||||
#expect(event._source == nil)
|
||||
}
|
||||
|
||||
@Test func metadataSetterStoresThroughComputedProperty() {
|
||||
var event = LogEvent(
|
||||
level: .info,
|
||||
message: "hello",
|
||||
metadata: nil,
|
||||
source: nil,
|
||||
file: "M/F.swift",
|
||||
function: "f()",
|
||||
line: 1
|
||||
)
|
||||
#expect(event.metadata == nil)
|
||||
|
||||
event.metadata = ["key": "value"]
|
||||
#expect(event.metadata?["key"] == "value")
|
||||
|
||||
event.metadata = nil
|
||||
#expect(event.metadata == nil)
|
||||
}
|
||||
|
||||
@Test func loggerDerivedSourceMatchesModuleName() {
|
||||
let recorder = Recorder()
|
||||
let handler = LogEventHandler(recorder: recorder)
|
||||
var logger = Logger(label: "test", handler)
|
||||
logger.logLevel = .trace
|
||||
|
||||
// Log without explicit source — source should be derived from #fileID.
|
||||
logger.info("derived source test")
|
||||
|
||||
let entries = recorder.entries
|
||||
#expect(entries.count == 1)
|
||||
#expect(entries[0].source == "LoggingTests")
|
||||
}
|
||||
|
||||
// MARK: - Default log(event:) forwarding to deprecated flat-parameter method
|
||||
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
@Test func defaultLogEventForwardsAllFieldsIncludingSourceLocation() {
|
||||
let recorder = Recorder()
|
||||
let handler = FlatParametersHandler(recorder: recorder)
|
||||
var logger = Logger(label: "test", handler)
|
||||
logger.logLevel = .trace
|
||||
|
||||
logger.warning("location test")
|
||||
let line = UInt(#line - 1)
|
||||
|
||||
let entries = recorder.entries
|
||||
#expect(entries.count == 1)
|
||||
#expect(entries[0].level == .warning)
|
||||
#expect(entries[0].message == "location test")
|
||||
#expect(entries[0].file.hasSuffix("LogEventTest.swift"))
|
||||
#expect(entries[0].function.contains("defaultLogEventForwardsAllFieldsIncludingSourceLocation"))
|
||||
#expect(entries[0].line == line)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Test Helpers
|
||||
|
||||
/// A handler that implements `log(event:)` directly and records entries.
|
||||
private struct LogEventHandler: LogHandler {
|
||||
let recorder: Recorder
|
||||
var logLevel: Logger.Level = .trace
|
||||
var metadata: Logger.Metadata = [:]
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
func log(event: LogEvent) {
|
||||
self.recorder.record(level: event.level, metadata: event.metadata, message: event.message, source: event.source)
|
||||
}
|
||||
|
||||
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[key] }
|
||||
set { self.metadata[key] = newValue }
|
||||
}
|
||||
}
|
||||
|
||||
/// A handler that only implements the deprecated flat-parameter method, relying on the
|
||||
/// default `log(event:)` forwarding bridge.
|
||||
@available(*, deprecated, message: "Testing deprecated functionality")
|
||||
private struct FlatParametersHandler: LogHandler {
|
||||
let recorder: Recorder
|
||||
var logLevel: Logger.Level = .trace
|
||||
var metadata: Logger.Metadata = [:]
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
func log(
|
||||
level: Logger.Level,
|
||||
message: Logger.Message,
|
||||
metadata: Logger.Metadata?,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.recorder.record(
|
||||
level: level,
|
||||
metadata: metadata,
|
||||
message: message,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
}
|
||||
|
||||
subscript(metadataKey key: String) -> Logger.Metadata.Value? {
|
||||
get { self.metadata[key] }
|
||||
set { self.metadata[key] = newValue }
|
||||
}
|
||||
}
|
||||
@@ -1,60 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// LoggingTest+XCTest.swift
|
||||
//
|
||||
import XCTest
|
||||
|
||||
///
|
||||
/// NOTE: This file was generated by generate_linux_tests.rb
|
||||
///
|
||||
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
|
||||
///
|
||||
|
||||
extension LoggingTest {
|
||||
static var allTests: [(String, (LoggingTest) -> () throws -> Void)] {
|
||||
return [
|
||||
("testAutoclosure", testAutoclosure),
|
||||
("testMultiplex", testMultiplex),
|
||||
("testMultiplexLogHandlerWithVariousLogLevels", testMultiplexLogHandlerWithVariousLogLevels),
|
||||
("testMultiplexLogHandlerNeedNotMaterializeValuesMultipleTimes", testMultiplexLogHandlerNeedNotMaterializeValuesMultipleTimes),
|
||||
("testMultiplexLogHandlerMetadata_settingMetadataThroughToUnderlyingHandlers", testMultiplexLogHandlerMetadata_settingMetadataThroughToUnderlyingHandlers),
|
||||
("testMultiplexLogHandlerMetadata_readingHandlerMetadata", testMultiplexLogHandlerMetadata_readingHandlerMetadata),
|
||||
("testDictionaryMetadata", testDictionaryMetadata),
|
||||
("testListMetadata", testListMetadata),
|
||||
("testStringConvertibleMetadata", testStringConvertibleMetadata),
|
||||
("testAutoClosuresAreNotForcedUnlessNeeded", testAutoClosuresAreNotForcedUnlessNeeded),
|
||||
("testLocalMetadata", testLocalMetadata),
|
||||
("testCustomFactory", testCustomFactory),
|
||||
("testAllLogLevelsExceptCriticalCanBeBlocked", testAllLogLevelsExceptCriticalCanBeBlocked),
|
||||
("testAllLogLevelsWork", testAllLogLevelsWork),
|
||||
("testAllLogLevelByFunctionRefWithSource", testAllLogLevelByFunctionRefWithSource),
|
||||
("testAllLogLevelByFunctionRefWithoutSource", testAllLogLevelByFunctionRefWithoutSource),
|
||||
("testLogsEmittedFromSubdirectoryGetCorrectModuleInNewerSwifts", testLogsEmittedFromSubdirectoryGetCorrectModuleInNewerSwifts),
|
||||
("testLogMessageWithStringInterpolation", testLogMessageWithStringInterpolation),
|
||||
("testLoggingAString", testLoggingAString),
|
||||
("testMultiplexerIsValue", testMultiplexerIsValue),
|
||||
("testLoggerWithGlobalOverride", testLoggerWithGlobalOverride),
|
||||
("testLogLevelCases", testLogLevelCases),
|
||||
("testLogLevelOrdering", testLogLevelOrdering),
|
||||
("testStreamLogHandlerWritesToAStream", testStreamLogHandlerWritesToAStream),
|
||||
("testStreamLogHandlerOutputFormat", testStreamLogHandlerOutputFormat),
|
||||
("testStreamLogHandlerOutputFormatWithMetaData", testStreamLogHandlerOutputFormatWithMetaData),
|
||||
("testStreamLogHandlerOutputFormatWithOrderedMetadata", testStreamLogHandlerOutputFormatWithOrderedMetadata),
|
||||
("testStdioOutputStreamWrite", testStdioOutputStreamWrite),
|
||||
("testStdioOutputStreamFlush", testStdioOutputStreamFlush),
|
||||
("testOverloadingError", testOverloadingError),
|
||||
]
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,31 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// MDCTest+XCTest.swift
|
||||
//
|
||||
import XCTest
|
||||
|
||||
///
|
||||
/// NOTE: This file was generated by generate_linux_tests.rb
|
||||
///
|
||||
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
|
||||
///
|
||||
|
||||
extension MDCTest {
|
||||
static var allTests: [(String, (MDCTest) -> () throws -> Void)] {
|
||||
return [
|
||||
("test1", test1),
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -12,43 +12,40 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
import Dispatch
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
import XCTest
|
||||
|
||||
class MDCTest: XCTestCase {
|
||||
func test1() throws {
|
||||
// bootstrap with our test logger
|
||||
let logging = TestLogging()
|
||||
LoggingSystem.bootstrapInternal(logging.make)
|
||||
|
||||
struct MDCTest {
|
||||
@Test func test() throws {
|
||||
// run the program
|
||||
MDC.global["foo"] = "bar"
|
||||
let group = DispatchGroup()
|
||||
for r in 5 ... 10 {
|
||||
for r in 5...10 {
|
||||
group.enter()
|
||||
DispatchQueue(label: "mdc-test-queue-\(r)").async {
|
||||
let add = Int.random(in: 10 ... 1000)
|
||||
let remove = Int.random(in: 0 ... add - 1)
|
||||
for i in 0 ... add {
|
||||
let add = Int.random(in: 10...1000)
|
||||
let remove = Int.random(in: 0...add - 1)
|
||||
for i in 0...add {
|
||||
MDC.global["key-\(i)"] = "value-\(i)"
|
||||
}
|
||||
for i in 0 ... remove {
|
||||
for i in 0...remove {
|
||||
MDC.global["key-\(i)"] = nil
|
||||
}
|
||||
XCTAssertEqual(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((add - remove) == MDC.global.metadata.count, "expected number of entries to match")
|
||||
for i in remove + 1...add {
|
||||
#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)")
|
||||
for i in 0...remove {
|
||||
#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")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,125 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
#if canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif os(Windows)
|
||||
import WinSDK
|
||||
#elseif canImport(Android)
|
||||
import Android
|
||||
#else
|
||||
import Glibc
|
||||
#endif
|
||||
|
||||
struct MetadataProviderTest {
|
||||
@Test func logHandlerThatDidNotImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
#if DEBUG
|
||||
// we only emit these warnings in debug mode
|
||||
let logging = TestLogging()
|
||||
var handler = LogHandlerThatDidNotImplementMetadataProviders(testLogging: logging)
|
||||
|
||||
handler.metadataProvider = .simpleTestProvider
|
||||
|
||||
logging.history.assertExist(
|
||||
level: .warning,
|
||||
message:
|
||||
"Attempted to set metadataProvider on LogHandlerThatDidNotImplementMetadataProviders that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.",
|
||||
source: "Logging"
|
||||
)
|
||||
|
||||
let countBefore = logging.history.entries.count
|
||||
handler.metadataProvider = .simpleTestProvider
|
||||
#expect(countBefore == logging.history.entries.count, "Should only log the warning once")
|
||||
#endif
|
||||
}
|
||||
|
||||
@Test func logHandlerThatDidImplementProvidersButSomeoneAttemptsToSetOneOnIt() {
|
||||
#if DEBUG
|
||||
// we only emit these warnings in debug mode
|
||||
let logging = TestLogging()
|
||||
var handler = LogHandlerThatDidImplementMetadataProviders(testLogging: logging)
|
||||
|
||||
handler.metadataProvider = .simpleTestProvider
|
||||
|
||||
logging.history.assertNotExist(
|
||||
level: .warning,
|
||||
message:
|
||||
"Attempted to set metadataProvider on LogHandlerThatDidImplementMetadataProviders that did not implement support for them. Please contact the log handler maintainer to implement metadata provider support.",
|
||||
source: "Logging"
|
||||
)
|
||||
#endif
|
||||
}
|
||||
}
|
||||
|
||||
extension Logger.MetadataProvider {
|
||||
static var simpleTestProvider: Logger.MetadataProvider {
|
||||
Logger.MetadataProvider {
|
||||
["test": "provided"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
struct LogHandlerThatDidNotImplementMetadataProviders: LogHandler {
|
||||
let testLogging: TestLogging
|
||||
init(testLogging: TestLogging) {
|
||||
self.testLogging = testLogging
|
||||
}
|
||||
|
||||
subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
|
||||
get {
|
||||
nil
|
||||
}
|
||||
set(newValue) {
|
||||
// ignore
|
||||
}
|
||||
}
|
||||
|
||||
var metadata: Logging.Logger.Metadata = [:]
|
||||
|
||||
var logLevel: Logging.Logger.Level = .trace
|
||||
|
||||
func log(event: LogEvent) {
|
||||
self.testLogging.make(label: "fake").log(event: event)
|
||||
}
|
||||
}
|
||||
|
||||
struct LogHandlerThatDidImplementMetadataProviders: LogHandler {
|
||||
let testLogging: TestLogging
|
||||
init(testLogging: TestLogging) {
|
||||
self.testLogging = testLogging
|
||||
}
|
||||
|
||||
subscript(metadataKey _: String) -> Logging.Logger.Metadata.Value? {
|
||||
get {
|
||||
nil
|
||||
}
|
||||
set(newValue) {
|
||||
// ignore
|
||||
}
|
||||
}
|
||||
|
||||
var metadata: Logging.Logger.Metadata = [:]
|
||||
|
||||
var logLevel: Logging.Logger.Level = .trace
|
||||
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
func log(event: LogEvent) {
|
||||
self.testLogging.make(label: "fake").log(event: event)
|
||||
}
|
||||
}
|
||||
+273
-119
@@ -11,52 +11,109 @@
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Dispatch
|
||||
import Foundation
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
import XCTest
|
||||
|
||||
internal struct TestLogging {
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
#if os(Windows)
|
||||
import WinSDK
|
||||
#endif
|
||||
|
||||
func make(label: String) -> LogHandler {
|
||||
return TestLogHandler(label: label, config: self.config, recorder: self.recorder)
|
||||
struct TestLogging {
|
||||
private let _config = Config() // shared among loggers
|
||||
private let recorder = Recorder() // shared among loggers
|
||||
|
||||
func make(label: String) -> some LogHandler {
|
||||
TestLogHandler(
|
||||
label: label,
|
||||
config: self.config,
|
||||
recorder: self.recorder,
|
||||
metadataProvider: LoggingSystem.metadataProvider
|
||||
)
|
||||
}
|
||||
|
||||
var config: Config { return self._config }
|
||||
var history: History { return self.recorder }
|
||||
func makeWithMetadataProvider(label: String, metadataProvider: Logger.MetadataProvider?) -> (some LogHandler) {
|
||||
TestLogHandler(
|
||||
label: label,
|
||||
config: self.config,
|
||||
recorder: self.recorder,
|
||||
metadataProvider: metadataProvider
|
||||
)
|
||||
}
|
||||
|
||||
var config: Config { self._config }
|
||||
var history: some History { self.recorder }
|
||||
}
|
||||
|
||||
internal struct TestLogHandler: LogHandler {
|
||||
private let logLevelLock = NSLock()
|
||||
private let metadataLock = NSLock()
|
||||
private let recorder: Recorder
|
||||
private let config: Config
|
||||
private var logger: Logger // the actual logger
|
||||
private var logger: Logger // the actual logger
|
||||
|
||||
let label: String
|
||||
var metadataProvider: Logger.MetadataProvider?
|
||||
|
||||
init(label: String, config: Config, recorder: Recorder, metadataProvider: Logger.MetadataProvider?) {
|
||||
self.label = label
|
||||
self.config = config
|
||||
self.recorder = recorder
|
||||
self.logger = Logger(label: "test", StreamLogHandler.standardOutput(label: label))
|
||||
self.logger.logLevel = .debug
|
||||
self.metadataProvider = metadataProvider
|
||||
}
|
||||
|
||||
init(label: String, config: Config, recorder: Recorder) {
|
||||
self.label = label
|
||||
self.config = config
|
||||
self.recorder = recorder
|
||||
self.logger = Logger(label: "test", StreamLogHandler.standardOutput(label: label))
|
||||
self.logger.logLevel = .debug
|
||||
self.metadataProvider = LoggingSystem.metadataProvider
|
||||
}
|
||||
|
||||
func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt) {
|
||||
let metadata = (self._metadataSet ? self.metadata : MDC.global.metadata).merging(metadata ?? [:], uniquingKeysWith: { _, new in new })
|
||||
self.logger.log(level: level, message, metadata: metadata, source: source, file: file, function: function, line: line)
|
||||
self.recorder.record(level: level, metadata: metadata, message: message, source: source)
|
||||
func log(event: LogEvent) {
|
||||
// baseline metadata, that was set on handler:
|
||||
var metadata = self._metadataSet ? self.metadata : MDC.global.metadata
|
||||
// contextual metadata, e.g. from task-locals:
|
||||
let contextualMetadata = self.metadataProvider?.get() ?? [:]
|
||||
if !contextualMetadata.isEmpty {
|
||||
metadata.merge(contextualMetadata, uniquingKeysWith: { _, contextual in contextual })
|
||||
}
|
||||
// override using any explicit metadata passed for this log statement:
|
||||
if let explicitMetadata = event.metadata {
|
||||
metadata.merge(explicitMetadata, uniquingKeysWith: { _, explicit in explicit })
|
||||
}
|
||||
|
||||
self.logger.log(
|
||||
level: event.level,
|
||||
event.message,
|
||||
error: event.error,
|
||||
metadata: metadata,
|
||||
source: event.source,
|
||||
file: event.file,
|
||||
function: event.function,
|
||||
line: event.line
|
||||
)
|
||||
self.recorder.record(
|
||||
level: event.level,
|
||||
metadata: metadata,
|
||||
message: event.message,
|
||||
error: event.error,
|
||||
source: event.source
|
||||
)
|
||||
}
|
||||
|
||||
private var _logLevel: Logger.Level?
|
||||
var logLevel: Logger.Level {
|
||||
get {
|
||||
// get from config unless set
|
||||
return self.logLevelLock.withLock { self._logLevel } ?? self.config.get(key: self.label)
|
||||
self._logLevel ?? self.config.get(key: self.label)
|
||||
}
|
||||
set {
|
||||
self.logLevelLock.withLock { self._logLevel = newValue }
|
||||
self._logLevel = newValue
|
||||
}
|
||||
}
|
||||
|
||||
@@ -67,28 +124,22 @@ internal struct TestLogHandler: LogHandler {
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logger.Metadata {
|
||||
var metadata: Logger.Metadata {
|
||||
get {
|
||||
// return self.logger.metadata
|
||||
return self.metadataLock.withLock { self._metadata }
|
||||
self._metadata
|
||||
}
|
||||
set {
|
||||
// self.logger.metadata = newValue
|
||||
self.metadataLock.withLock { self._metadata = newValue }
|
||||
self._metadata = newValue
|
||||
}
|
||||
}
|
||||
|
||||
// TODO: would be nice to delegate to local copy of logger but StdoutLogger is a reference type. why?
|
||||
subscript(metadataKey metadataKey: Logger.Metadata.Key) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
// return self.logger[metadataKey: metadataKey]
|
||||
return self.metadataLock.withLock { self._metadata[metadataKey] }
|
||||
self._metadata[metadataKey]
|
||||
}
|
||||
set {
|
||||
// return logger[metadataKey: metadataKey] = newValue
|
||||
self.metadataLock.withLock {
|
||||
self._metadata[metadataKey] = newValue
|
||||
}
|
||||
self._metadata[metadataKey] = newValue
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -100,7 +151,7 @@ internal class Config {
|
||||
private var storage = [String: Logger.Level]()
|
||||
|
||||
func get(key: String) -> Logger.Level {
|
||||
return self.get(key) ?? self.get(Config.ALL) ?? Logger.Level.debug
|
||||
self.get(key) ?? self.get(Config.ALL) ?? Logger.Level.debug
|
||||
}
|
||||
|
||||
func get(_ key: String) -> Logger.Level? {
|
||||
@@ -123,14 +174,48 @@ internal class Recorder: History {
|
||||
private let lock = NSLock()
|
||||
private var _entries = [LogEntry]()
|
||||
|
||||
func record(level: Logger.Level, metadata: Logger.Metadata?, message: Logger.Message, source: String) {
|
||||
return self.lock.withLock {
|
||||
self._entries.append(LogEntry(level: level, metadata: metadata, message: message.description, source: source))
|
||||
func record(
|
||||
level: Logger.Level,
|
||||
metadata: Logger.Metadata?,
|
||||
message: Logger.Message,
|
||||
error: (any Error)? = nil,
|
||||
source: String
|
||||
) {
|
||||
self.lock.withLock {
|
||||
self._entries.append(
|
||||
LogEntry(level: level, metadata: metadata, message: message.description, error: error, source: source)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
func record(
|
||||
level: Logger.Level,
|
||||
metadata: Logger.Metadata?,
|
||||
message: Logger.Message,
|
||||
error: (any Error)? = nil,
|
||||
source: String,
|
||||
file: String,
|
||||
function: String,
|
||||
line: UInt
|
||||
) {
|
||||
self.lock.withLock {
|
||||
self._entries.append(
|
||||
LogEntry(
|
||||
level: level,
|
||||
metadata: metadata,
|
||||
message: message.description,
|
||||
error: error,
|
||||
source: source,
|
||||
file: file,
|
||||
function: function,
|
||||
line: line
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
var entries: [LogEntry] {
|
||||
return self.lock.withLock { self._entries }
|
||||
self.lock.withLock { self._entries }
|
||||
}
|
||||
}
|
||||
|
||||
@@ -138,31 +223,31 @@ internal protocol History {
|
||||
var entries: [LogEntry] { get }
|
||||
}
|
||||
|
||||
internal extension History {
|
||||
extension History {
|
||||
func atLevel(level: Logger.Level) -> [LogEntry] {
|
||||
return self.entries.filter { entry in
|
||||
self.entries.filter { entry in
|
||||
level == entry.level
|
||||
}
|
||||
}
|
||||
|
||||
var trace: [LogEntry] {
|
||||
return self.atLevel(level: .debug)
|
||||
self.atLevel(level: .debug)
|
||||
}
|
||||
|
||||
var debug: [LogEntry] {
|
||||
return self.atLevel(level: .debug)
|
||||
self.atLevel(level: .debug)
|
||||
}
|
||||
|
||||
var info: [LogEntry] {
|
||||
return self.atLevel(level: .info)
|
||||
self.atLevel(level: .info)
|
||||
}
|
||||
|
||||
var warning: [LogEntry] {
|
||||
return self.atLevel(level: .warning)
|
||||
self.atLevel(level: .warning)
|
||||
}
|
||||
|
||||
var error: [LogEntry] {
|
||||
return self.atLevel(level: .error)
|
||||
self.atLevel(level: .error)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -170,84 +255,142 @@ internal struct LogEntry {
|
||||
let level: Logger.Level
|
||||
let metadata: Logger.Metadata?
|
||||
let message: String
|
||||
let error: (any Error)?
|
||||
let source: String
|
||||
let file: String
|
||||
let function: String
|
||||
let line: UInt
|
||||
|
||||
init(
|
||||
level: Logger.Level,
|
||||
metadata: Logger.Metadata?,
|
||||
message: String,
|
||||
error: (any Error)?,
|
||||
source: String,
|
||||
file: String = "",
|
||||
function: String = "",
|
||||
line: UInt = 0
|
||||
) {
|
||||
self.level = level
|
||||
self.metadata = metadata
|
||||
self.message = message
|
||||
self.error = error
|
||||
self.source = source
|
||||
self.file = file
|
||||
self.function = function
|
||||
self.line = line
|
||||
}
|
||||
}
|
||||
|
||||
extension History {
|
||||
#if compiler(>=5.3)
|
||||
func assertExist(level: Logger.Level,
|
||||
message: String,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #file,
|
||||
fileID: String = #fileID,
|
||||
line: UInt = #line) {
|
||||
func assertExist(
|
||||
level: Logger.Level,
|
||||
message: String,
|
||||
error: (any Error)? = nil,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: String = #filePath,
|
||||
fileID: String = #fileID,
|
||||
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, "entry not found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file, line: line)
|
||||
let entry = self.find(level: level, message: message, error: error, metadata: metadata, source: source)
|
||||
#expect(
|
||||
entry != nil,
|
||||
"entry not found: \(level), \(source), \(String(describing: metadata)), \(message), \(String(describing: error))",
|
||||
sourceLocation: SourceLocation(fileID: fileID, filePath: file, line: line, column: column)
|
||||
)
|
||||
}
|
||||
|
||||
func assertNotExist(level: Logger.Level,
|
||||
message: String,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #file,
|
||||
fileID: String = #file,
|
||||
line: UInt = #line) {
|
||||
func assertNotExist(
|
||||
level: Logger.Level,
|
||||
message: String,
|
||||
error: (any Error)? = nil,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: String = #filePath,
|
||||
fileID: String = #file,
|
||||
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, "entry was found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file, line: line)
|
||||
let entry = self.find(level: level, message: message, error: error, metadata: metadata, source: source)
|
||||
#expect(
|
||||
entry == nil,
|
||||
"entry was found: \(level), \(source), \(String(describing: metadata)), \(message), \(String(describing: error))",
|
||||
sourceLocation: SourceLocation(fileID: fileID, filePath: file, line: line, column: column)
|
||||
)
|
||||
}
|
||||
|
||||
#else
|
||||
func assertExist(level: Logger.Level,
|
||||
message: String,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #file,
|
||||
line: UInt = #line) {
|
||||
let source = source ?? Logger.currentModule(filePath: "\(file)")
|
||||
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
|
||||
XCTAssertNotNil(entry, "entry not found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file, line: line)
|
||||
func find(
|
||||
level: Logger.Level,
|
||||
message: String,
|
||||
error: (any Error)? = nil,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String
|
||||
) -> LogEntry? {
|
||||
self.entries.first { entry in
|
||||
if entry.level != level {
|
||||
return false
|
||||
}
|
||||
if entry.message != message {
|
||||
return false
|
||||
}
|
||||
if !errorsEqual(error, entry.error) {
|
||||
return false
|
||||
}
|
||||
if let lhs = entry.metadata, let rhs = metadata {
|
||||
if lhs.count != rhs.count {
|
||||
return false
|
||||
}
|
||||
|
||||
for lk in lhs.keys {
|
||||
if lhs[lk] != rhs[lk] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
for rk in rhs.keys {
|
||||
if lhs[rk] != rhs[rk] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
return true
|
||||
}
|
||||
if entry.source != source {
|
||||
return false
|
||||
}
|
||||
|
||||
return true
|
||||
}
|
||||
}
|
||||
|
||||
func assertNotExist(level: Logger.Level,
|
||||
message: String,
|
||||
metadata: Logger.Metadata? = nil,
|
||||
source: String? = nil,
|
||||
file: StaticString = #file,
|
||||
line: UInt = #line) {
|
||||
let source = source ?? Logger.currentModule(filePath: "\(file)")
|
||||
let entry = self.find(level: level, message: message, metadata: metadata, source: source)
|
||||
XCTAssertNil(entry, "entry was found: \(level), \(source), \(String(describing: metadata)), \(message)",
|
||||
file: file, line: line)
|
||||
}
|
||||
#endif
|
||||
|
||||
func find(level: Logger.Level, message: String, metadata: Logger.Metadata? = nil, source: String) -> LogEntry? {
|
||||
return self.entries.first { entry in
|
||||
entry.level == level &&
|
||||
entry.message == message &&
|
||||
entry.metadata ?? [:] == metadata ?? [:] &&
|
||||
entry.source == source
|
||||
private func errorsEqual(_ lhs: (any Error)?, _ rhs: (any Error)?) -> Bool {
|
||||
switch (lhs, rhs) {
|
||||
case (nil, nil):
|
||||
return true
|
||||
case let (l?, r?):
|
||||
return "\(l)" == "\(r)" && String(reflecting: type(of: l)) == String(reflecting: type(of: r))
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public class MDC {
|
||||
/// MDC stands for Mapped Diagnostic Context
|
||||
class MDC {
|
||||
private let lock = NSLock()
|
||||
private var storage = [Int: Logger.Metadata]()
|
||||
|
||||
public static var global = MDC()
|
||||
static let global = MDC()
|
||||
|
||||
private init() {}
|
||||
|
||||
public subscript(metadataKey: String) -> Logger.Metadata.Value? {
|
||||
subscript(metadataKey: String) -> Logger.Metadata.Value? {
|
||||
get {
|
||||
return self.lock.withLock {
|
||||
self.lock.withLock {
|
||||
self.storage[self.threadId]?[metadataKey]
|
||||
}
|
||||
}
|
||||
@@ -261,30 +404,38 @@ public class MDC {
|
||||
}
|
||||
}
|
||||
|
||||
public var metadata: Logger.Metadata {
|
||||
return self.lock.withLock {
|
||||
var metadata: Logger.Metadata {
|
||||
self.lock.withLock {
|
||||
self.storage[self.threadId] ?? [:]
|
||||
}
|
||||
}
|
||||
|
||||
public func clear() {
|
||||
func clear() {
|
||||
self.lock.withLock {
|
||||
_ = self.storage.removeValue(forKey: self.threadId)
|
||||
}
|
||||
}
|
||||
|
||||
public func with(metadata: Logger.Metadata, _ body: () throws -> Void) rethrows {
|
||||
metadata.forEach { self[$0] = $1 }
|
||||
func with(metadata: Logger.Metadata, _ body: () throws -> Void) rethrows {
|
||||
for (key, value) in metadata {
|
||||
self[key] = value
|
||||
}
|
||||
defer {
|
||||
metadata.keys.forEach { self[$0] = nil }
|
||||
for (key, _) in metadata {
|
||||
self[key] = nil
|
||||
}
|
||||
}
|
||||
try body()
|
||||
}
|
||||
|
||||
public func with<T>(metadata: Logger.Metadata, _ body: () throws -> T) rethrows -> T {
|
||||
metadata.forEach { self[$0] = $1 }
|
||||
func with<T>(metadata: Logger.Metadata, _ body: () throws -> T) rethrows -> T {
|
||||
for (key, value) in metadata {
|
||||
self[key] = value
|
||||
}
|
||||
defer {
|
||||
metadata.keys.forEach { self[$0] = nil }
|
||||
for (key, _) in metadata {
|
||||
self[key] = nil
|
||||
}
|
||||
}
|
||||
return try body()
|
||||
}
|
||||
@@ -297,35 +448,31 @@ public class MDC {
|
||||
}
|
||||
|
||||
private var threadId: Int {
|
||||
#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS)
|
||||
#if canImport(Darwin)
|
||||
return Int(pthread_mach_thread_np(pthread_self()))
|
||||
#elseif os(Windows)
|
||||
return Int(GetCurrentThreadId())
|
||||
#elseif os(FreeBSD)
|
||||
return Int(pthread_getthreadid_np())
|
||||
#elseif os(OpenBSD)
|
||||
return Int(bitPattern: pthread_self())
|
||||
#else
|
||||
return Int(pthread_self())
|
||||
#endif
|
||||
}
|
||||
}
|
||||
|
||||
internal extension NSLock {
|
||||
func withLock<T>(_ body: () -> T) -> T {
|
||||
self.lock()
|
||||
defer {
|
||||
self.unlock()
|
||||
}
|
||||
return body()
|
||||
}
|
||||
}
|
||||
|
||||
internal struct TestLibrary {
|
||||
internal struct TestLibrary: Sendable {
|
||||
private let logger = Logger(label: "TestLibrary")
|
||||
private let queue = DispatchQueue(label: "TestLibrary")
|
||||
|
||||
public init() {}
|
||||
init() {}
|
||||
|
||||
public func doSomething() {
|
||||
func doSomething() {
|
||||
self.logger.info("TestLibrary::doSomething")
|
||||
}
|
||||
|
||||
public func doSomethingAsync(completion: @escaping () -> Void) {
|
||||
func doSomethingAsync(completion: @escaping @Sendable () -> Void) {
|
||||
// libraries that use global loggers and async, need to make sure they propagate the
|
||||
// logging metadata when creating a new thread
|
||||
let metadata = MDC.global.metadata
|
||||
@@ -337,3 +484,10 @@ internal struct TestLibrary {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Sendable
|
||||
|
||||
extension TestLogHandler: @unchecked Sendable {}
|
||||
extension Recorder: @unchecked Sendable {}
|
||||
extension Config: @unchecked Sendable {}
|
||||
extension MDC: @unchecked Sendable {}
|
||||
@@ -0,0 +1,51 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2022 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import Testing
|
||||
|
||||
@testable import Logging
|
||||
|
||||
struct SendableTest {
|
||||
@Test func sendableLogger() async {
|
||||
let testLogging = TestLogging()
|
||||
|
||||
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"]
|
||||
let error = TestError()
|
||||
|
||||
let task = Task.detached {
|
||||
logger.info("info")
|
||||
logger.critical(message1)
|
||||
logger.critical(message2)
|
||||
logger.warning(.init(stringLiteral: "warning"), metadata: metadata)
|
||||
logger.warning("error", error: error)
|
||||
}
|
||||
|
||||
await task.value
|
||||
testLogging.history.assertExist(level: .info, message: "info", metadata: [:])
|
||||
testLogging.history.assertExist(level: .critical, message: "critical 1", metadata: [:])
|
||||
testLogging.history.assertExist(level: .critical, message: "critical 2", metadata: [:])
|
||||
testLogging.history.assertExist(level: .warning, message: "warning", metadata: metadata)
|
||||
testLogging.history.assertExist(level: .warning, message: "error", error: error)
|
||||
}
|
||||
|
||||
final class TestError: Error {}
|
||||
}
|
||||
@@ -1,35 +0,0 @@
|
||||
ARG swift_version=5.0
|
||||
ARG ubuntu_version=bionic
|
||||
ARG base_image=swift:$swift_version-$ubuntu_version
|
||||
FROM $base_image
|
||||
# needed to do again after FROM due to docker limitation
|
||||
ARG swift_version
|
||||
ARG ubuntu_version
|
||||
|
||||
# set as UTF-8
|
||||
RUN apt-get update && apt-get install -y locales locales-all
|
||||
ENV LC_ALL en_US.UTF-8
|
||||
ENV LANG en_US.UTF-8
|
||||
ENV LANGUAGE en_US.UTF-8
|
||||
|
||||
# dependencies
|
||||
RUN apt-get update && apt-get install -y wget
|
||||
RUN apt-get update && apt-get install -y lsof dnsutils netcat-openbsd net-tools curl jq # used by integration tests
|
||||
|
||||
# ruby and jazzy for docs generation
|
||||
RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev build-essential
|
||||
# switch of gem docs building
|
||||
RUN echo "gem: --no-document" > ~/.gemrc
|
||||
# jazzy no longer works on xenial as ruby is too old.
|
||||
RUN if [ "${ubuntu_version}" != "xenial" ] ; then gem install jazzy; fi
|
||||
|
||||
# tools
|
||||
RUN mkdir -p $HOME/.tools
|
||||
RUN echo 'export PATH="$HOME/.tools:$PATH"' >> $HOME/.profile
|
||||
|
||||
# swiftformat (until part of the toolchain)
|
||||
|
||||
ARG swiftformat_version=0.44.6
|
||||
RUN git clone --branch $swiftformat_version --depth 1 https://github.com/nicklockwood/SwiftFormat $HOME/.tools/swift-format
|
||||
RUN cd $HOME/.tools/swift-format && swift build -c release
|
||||
RUN ln -s $HOME/.tools/swift-format/.build/release/swiftformat $HOME/.tools/swiftformat
|
||||
@@ -1,16 +0,0 @@
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
runtime-setup:
|
||||
image: swift-log:18.04-5.0
|
||||
build:
|
||||
args:
|
||||
ubuntu_version: "bionic"
|
||||
swift_version: "5.0"
|
||||
|
||||
test:
|
||||
image: swift-log:18.04-5.0
|
||||
|
||||
shell:
|
||||
image: swift-log:18.04-5.0
|
||||
@@ -1,18 +0,0 @@
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
runtime-setup:
|
||||
image: swift-log:18.04-5.1
|
||||
build:
|
||||
args:
|
||||
ubuntu_version: "bionic"
|
||||
swift_version: "5.1"
|
||||
|
||||
test:
|
||||
image: swift-log:18.04-5.1
|
||||
environment: []
|
||||
#- SANITIZER_ARG=--sanitize=thread
|
||||
|
||||
shell:
|
||||
image: swift-log:18.04-5.1
|
||||
@@ -1,18 +0,0 @@
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
runtime-setup:
|
||||
image: swift-log:18.04-5.2
|
||||
build:
|
||||
args:
|
||||
ubuntu_version: "bionic"
|
||||
swift_version: "5.2"
|
||||
|
||||
test:
|
||||
image: swift-log:18.04-5.2
|
||||
environment: []
|
||||
#- SANITIZER_ARG=--sanitize=thread
|
||||
|
||||
shell:
|
||||
image: swift-log:18.04-5.2
|
||||
@@ -1,18 +0,0 @@
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
runtime-setup:
|
||||
image: swift-log:18.04-5.3
|
||||
build:
|
||||
args:
|
||||
ubuntu_version: "bionic"
|
||||
swift_version: "5.3"
|
||||
|
||||
test:
|
||||
image: swift-log:18.04-5.3
|
||||
environment: []
|
||||
#- SANITIZER_ARG=--sanitize=thread
|
||||
|
||||
shell:
|
||||
image: swift-log:18.04-5.3
|
||||
@@ -1,17 +0,0 @@
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
runtime-setup:
|
||||
image: swift-log:20.04-5.4
|
||||
build:
|
||||
args:
|
||||
base_image: "swiftlang/swift:nightly-5.4-focal"
|
||||
|
||||
test:
|
||||
image: swift-log:20.04-5.4
|
||||
environment: []
|
||||
#- SANITIZER_ARG=--sanitize=thread
|
||||
|
||||
shell:
|
||||
image: swift-log:20.04-5.4
|
||||
@@ -1,17 +0,0 @@
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
runtime-setup:
|
||||
image: swift-log:20.04-main
|
||||
build:
|
||||
args:
|
||||
base_image: "swiftlang/swift:nightly-main-focal"
|
||||
|
||||
test:
|
||||
image: swift-log:20.04-main
|
||||
environment: []
|
||||
#- SANITIZER_ARG=--sanitize=thread
|
||||
|
||||
shell:
|
||||
image: swift-log:20.04-main
|
||||
@@ -1,37 +0,0 @@
|
||||
# this file is not designed to be run directly
|
||||
# instead, use the docker-compose.<os>.<swift> files
|
||||
# eg docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.1804.50.yaml run test
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
|
||||
runtime-setup:
|
||||
image: swift-log:default
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
|
||||
common: &common
|
||||
image: swift-log:default
|
||||
depends_on: [runtime-setup]
|
||||
volumes:
|
||||
- ~/.ssh:/root/.ssh
|
||||
- ..:/code:z
|
||||
working_dir: /code
|
||||
cap_drop:
|
||||
- CAP_NET_RAW
|
||||
- CAP_NET_BIND_SERVICE
|
||||
|
||||
soundness:
|
||||
<<: *common
|
||||
command: /bin/bash -xcl "./scripts/soundness.sh"
|
||||
|
||||
test:
|
||||
<<: *common
|
||||
command: /bin/bash -xcl "swift test -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"
|
||||
|
||||
# util
|
||||
|
||||
shell:
|
||||
<<: *common
|
||||
entrypoint: /bin/bash
|
||||
@@ -1,94 +0,0 @@
|
||||
#!/bin/bash
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) 2019 Apple Inc. and the Swift Logging API project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the SwiftNIO open source project
|
||||
##
|
||||
## Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
set -eu
|
||||
|
||||
function usage() {
|
||||
echo "$0 [-u] version"
|
||||
echo
|
||||
echo "OPTIONS:"
|
||||
echo " -u: Additionally upload the podspec"
|
||||
}
|
||||
|
||||
upload=false
|
||||
while getopts ":u" opt; do
|
||||
case $opt in
|
||||
u)
|
||||
upload=true
|
||||
;;
|
||||
\?)
|
||||
usage
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
shift "$((OPTIND-1))"
|
||||
|
||||
if [[ $# -eq 0 ]]; then
|
||||
echo "Must provide target version"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
version=$1
|
||||
podspec_name="Logging"
|
||||
|
||||
here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
|
||||
tmpdir=$(mktemp -d /tmp/.build_podspecsXXXXXX)
|
||||
echo "Building podspec in $tmpdir"
|
||||
|
||||
cat > "${tmpdir}/${podspec_name}.podspec" <<- EOF
|
||||
Pod::Spec.new do |s|
|
||||
s.name = '$podspec_name'
|
||||
s.version = '$version'
|
||||
s.license = { :type => 'Apache 2.0', :file => 'LICENSE.txt' }
|
||||
s.summary = 'A Logging API for Swift.'
|
||||
s.homepage = 'https://github.com/apple/swift-log'
|
||||
s.author = 'Apple Inc.'
|
||||
s.source = { :git => 'https://github.com/apple/swift-log.git', :tag => s.version.to_s }
|
||||
s.documentation_url = 'https://apple.github.io/swift-log'
|
||||
s.module_name = 'Logging'
|
||||
|
||||
s.swift_version = '5.0'
|
||||
s.cocoapods_version = '>=1.6.0'
|
||||
s.ios.deployment_target = '8.0'
|
||||
s.osx.deployment_target = '10.9'
|
||||
s.tvos.deployment_target = '9.0'
|
||||
s.watchos.deployment_target = '2.0'
|
||||
|
||||
s.source_files = 'Sources/Logging/**/*.swift'
|
||||
end
|
||||
EOF
|
||||
|
||||
if $upload; then
|
||||
echo "Uploading ${tmpdir}/${podspec_name}.podspec"
|
||||
pod trunk push "${tmpdir}/${podspec_name}.podspec"
|
||||
else
|
||||
echo "Linting ${tmpdir}/${podspec_name}.podspec"
|
||||
pod spec lint "${tmpdir}/${podspec_name}.podspec"
|
||||
fi
|
||||
@@ -1,136 +0,0 @@
|
||||
#!/bin/bash
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) 2019 Apple Inc. and the Swift Logging API project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the SwiftNIO open source project
|
||||
##
|
||||
## Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
set -eu
|
||||
|
||||
# repodir
|
||||
function all_modules() {
|
||||
local repodir="$1"
|
||||
(
|
||||
set -eu
|
||||
cd "$repodir"
|
||||
swift package dump-package | jq '.products |
|
||||
map(select(.type | has("library") )) |
|
||||
map(.name) | .[]' | tr -d '"'
|
||||
)
|
||||
}
|
||||
|
||||
# repodir tag output
|
||||
function build_and_do() {
|
||||
local repodir=$1
|
||||
local tag=$2
|
||||
local output=$3
|
||||
|
||||
(
|
||||
cd "$repodir"
|
||||
git checkout -q "$tag"
|
||||
swift build
|
||||
while read -r module; do
|
||||
swift api-digester -sdk "$sdk" -dump-sdk -module "$module" \
|
||||
-o "$output/$module.json" -I "$repodir/.build/debug"
|
||||
done < <(all_modules "$repodir")
|
||||
)
|
||||
}
|
||||
|
||||
function usage() {
|
||||
echo >&2 "Usage: $0 REPO-GITHUB-URL NEW-VERSION OLD-VERSIONS..."
|
||||
echo >&2
|
||||
echo >&2 "This script requires a Swift 5.1+ toolchain."
|
||||
echo >&2
|
||||
echo >&2 "Examples:"
|
||||
echo >&2
|
||||
echo >&2 "Check between master and tag 2.1.1 of swift-nio:"
|
||||
echo >&2 " $0 https://github.com/apple/swift-nio master 2.1.1"
|
||||
echo >&2
|
||||
echo >&2 "Check between HEAD and commit 64cf63d7 using the provided toolchain:"
|
||||
echo >&2 " xcrun --toolchain org.swift.5120190702a $0 ../some-local-repo HEAD 64cf63d7"
|
||||
}
|
||||
|
||||
if [[ $# -lt 3 ]]; then
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
|
||||
sdk=/
|
||||
if [[ "$(uname -s)" == Darwin ]]; then
|
||||
sdk=$(xcrun --show-sdk-path)
|
||||
fi
|
||||
|
||||
hash jq 2> /dev/null || { echo >&2 "ERROR: jq must be installed"; exit 1; }
|
||||
tmpdir=$(mktemp -d /tmp/.check-api_XXXXXX)
|
||||
repo_url=$1
|
||||
new_tag=$2
|
||||
shift 2
|
||||
|
||||
repodir="$tmpdir/repo"
|
||||
git clone "$repo_url" "$repodir"
|
||||
git -C "$repodir" fetch -q origin '+refs/pull/*:refs/remotes/origin/pr/*'
|
||||
errors=0
|
||||
|
||||
for old_tag in "$@"; do
|
||||
mkdir "$tmpdir/api-old"
|
||||
mkdir "$tmpdir/api-new"
|
||||
|
||||
echo "Checking public API breakages from $old_tag to $new_tag"
|
||||
|
||||
build_and_do "$repodir" "$new_tag" "$tmpdir/api-new/"
|
||||
build_and_do "$repodir" "$old_tag" "$tmpdir/api-old/"
|
||||
|
||||
for f in "$tmpdir/api-new"/*; do
|
||||
f=$(basename "$f")
|
||||
report="$tmpdir/$f.report"
|
||||
if [[ ! -f "$tmpdir/api-old/$f" ]]; then
|
||||
echo "NOTICE: NEW MODULE $f"
|
||||
continue
|
||||
fi
|
||||
|
||||
echo -n "Checking $f... "
|
||||
swift api-digester -sdk "$sdk" -diagnose-sdk \
|
||||
--input-paths "$tmpdir/api-old/$f" -input-paths "$tmpdir/api-new/$f" 2>&1 \
|
||||
> "$report" 2>&1
|
||||
|
||||
if ! shasum "$report" | grep -q cefc4ee5bb7bcdb7cb5a7747efa178dab3c794d5; then
|
||||
echo ERROR
|
||||
echo >&2 "=============================="
|
||||
echo >&2 "ERROR: public API change in $f"
|
||||
echo >&2 "=============================="
|
||||
cat >&2 "$report"
|
||||
errors=$(( errors + 1 ))
|
||||
else
|
||||
echo OK
|
||||
fi
|
||||
done
|
||||
rm -rf "$tmpdir/api-new" "$tmpdir/api-old"
|
||||
done
|
||||
|
||||
if [[ "$errors" == 0 ]]; then
|
||||
echo "OK, all seems good"
|
||||
fi
|
||||
echo done
|
||||
exit "$errors"
|
||||
@@ -1,39 +0,0 @@
|
||||
#!/bin/bash
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
set -eu
|
||||
here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
|
||||
contributors=$( cd "$here"/.. && git shortlog -es | cut -f2 | sed 's/^/- /' )
|
||||
|
||||
cat > "$here/../CONTRIBUTORS.txt" <<- EOF
|
||||
For the purpose of tracking copyright, this is the list of individuals and
|
||||
organizations who have contributed source code to the Swift Logging API.
|
||||
|
||||
For employees of an organization/company where the copyright of work done
|
||||
by employees of that company is held by the company itself, only the company
|
||||
needs to be listed here.
|
||||
|
||||
## COPYRIGHT HOLDERS
|
||||
|
||||
- Apple Inc. (all contributors with '@apple.com')
|
||||
|
||||
### Contributors
|
||||
|
||||
$contributors
|
||||
|
||||
**Updating this list**
|
||||
|
||||
Please do not edit this file manually. It is generated using \`./scripts/generate_contributors_list.sh\`. If a name is misspelled or appearing multiple times: add an entry in \`./.mailmap\`
|
||||
EOF
|
||||
@@ -1,112 +0,0 @@
|
||||
#!/bin/bash
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
set -ex
|
||||
|
||||
my_path="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
|
||||
root_path="$my_path/.."
|
||||
version=$(git describe --abbrev=0 --tags || echo "0.0.0")
|
||||
modules=(Logging)
|
||||
|
||||
if [[ "$(uname -s)" == "Linux" ]]; then
|
||||
# build code if required
|
||||
if [[ ! -d "$root_path/.build/x86_64-unknown-linux" ]]; then
|
||||
swift build
|
||||
fi
|
||||
# setup source-kitten if required
|
||||
source_kitten_source_path="$root_path/.SourceKitten"
|
||||
if [[ ! -d "$source_kitten_source_path" ]]; then
|
||||
git clone https://github.com/jpsim/SourceKitten.git "$source_kitten_source_path"
|
||||
fi
|
||||
source_kitten_path="$source_kitten_source_path/.build/x86_64-unknown-linux/debug"
|
||||
if [[ ! -d "$source_kitten_path" ]]; then
|
||||
rm -rf "$source_kitten_source_path/.swift-version"
|
||||
cd "$source_kitten_source_path" && swift build && cd "$root_path"
|
||||
fi
|
||||
# generate
|
||||
mkdir -p "$root_path/.build/sourcekitten"
|
||||
for module in "${modules[@]}"; do
|
||||
if [[ ! -f "$root_path/.build/sourcekitten/$module.json" ]]; then
|
||||
"$source_kitten_path/sourcekitten" doc --spm-module $module > "$root_path/.build/sourcekitten/$module.json"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
[[ -d docs/$version ]] || mkdir -p docs/$version
|
||||
[[ -d swift-log.xcodeproj ]] || swift package generate-xcodeproj
|
||||
|
||||
# run jazzy
|
||||
if ! command -v jazzy > /dev/null; then
|
||||
gem install jazzy --no-ri --no-rdoc
|
||||
fi
|
||||
|
||||
jazzy_dir="$root_path/.build/jazzy"
|
||||
rm -rf "$jazzy_dir"
|
||||
mkdir -p "$jazzy_dir"
|
||||
|
||||
module_switcher="$jazzy_dir/README.md"
|
||||
jazzy_args=(--clean
|
||||
--author 'SwiftLog team'
|
||||
--readme "$module_switcher"
|
||||
--author_url https://github.com/apple/swift-log
|
||||
--github_url https://github.com/apple/swift-log
|
||||
--github-file-prefix https://github.com/apple/swift-log/tree/$version
|
||||
--theme fullwidth
|
||||
--xcodebuild-arguments -scheme,swift-log-Package)
|
||||
cat > "$module_switcher" <<"EOF"
|
||||
# SwiftLog Docs
|
||||
|
||||
SwiftLog is a Swift logging API package.
|
||||
|
||||
To get started with SwiftLog, [`import Logging`](../Logging/index.html). The
|
||||
most important type is [`Logger`](https://apple.github.io/swift-log/docs/current/Logging/Structs/Logger.html)
|
||||
which you can use to emit log messages.
|
||||
EOF
|
||||
|
||||
for module in "${modules[@]}"; do
|
||||
args=("${jazzy_args[@]}" --output "$jazzy_dir/docs/$version/$module" --docset-path "$jazzy_dir/docset/$version/$module"
|
||||
--module "$module" --module-version $version
|
||||
--root-url "https://apple.github.io/swift-log/docs/$version/$module/")
|
||||
if [[ -f "$root_path/.build/sourcekitten/$module.json" ]]; then
|
||||
args+=(--sourcekitten-sourcefile "$root_path/.build/sourcekitten/$module.json")
|
||||
fi
|
||||
jazzy "${args[@]}"
|
||||
done
|
||||
|
||||
# push to github pages
|
||||
if [[ $PUSH == true ]]; then
|
||||
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
|
||||
GIT_AUTHOR=$(git --no-pager show -s --format='%an <%ae>' HEAD)
|
||||
git fetch origin +gh-pages:gh-pages
|
||||
git checkout gh-pages
|
||||
rm -rf "docs/$version"
|
||||
rm -rf "docs/current"
|
||||
cp -r "$jazzy_dir/docs/$version" docs/
|
||||
cp -r "docs/$version" docs/current
|
||||
git add --all docs
|
||||
echo '<html><head><meta http-equiv="refresh" content="0; url=docs/current/Logging/index.html" /></head></html>' > index.html
|
||||
git add index.html
|
||||
touch .nojekyll
|
||||
git add .nojekyll
|
||||
changes=$(git diff-index --name-only HEAD)
|
||||
if [[ -n "$changes" ]]; then
|
||||
echo -e "changes detected\n$changes"
|
||||
git commit --author="$GIT_AUTHOR" -m "publish $version docs"
|
||||
git push origin gh-pages
|
||||
else
|
||||
echo "no changes detected"
|
||||
fi
|
||||
git checkout -f $BRANCH_NAME
|
||||
fi
|
||||
@@ -1,231 +0,0 @@
|
||||
#!/usr/bin/env ruby
|
||||
|
||||
#
|
||||
# process_test_files.rb
|
||||
#
|
||||
# Copyright 2016 Tony Stone
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# Created by Tony Stone on 5/4/16.
|
||||
#
|
||||
require 'getoptlong'
|
||||
require 'fileutils'
|
||||
require 'pathname'
|
||||
|
||||
include FileUtils
|
||||
|
||||
#
|
||||
# This ruby script will auto generate LinuxMain.swift and the +XCTest.swift extension files for Swift Package Manager on Linux platforms.
|
||||
#
|
||||
# See https://github.com/apple/swift-corelibs-xctest/blob/master/Documentation/Linux.md
|
||||
#
|
||||
def header(fileName)
|
||||
string = <<-eos
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// <FileName>
|
||||
//
|
||||
import XCTest
|
||||
|
||||
///
|
||||
/// NOTE: This file was generated by generate_linux_tests.rb
|
||||
///
|
||||
/// Do NOT edit this file directly as it will be regenerated automatically when needed.
|
||||
///
|
||||
eos
|
||||
|
||||
string
|
||||
.sub('<FileName>', File.basename(fileName))
|
||||
.sub('<Date>', Time.now.to_s)
|
||||
end
|
||||
|
||||
def createExtensionFile(fileName, classes)
|
||||
extensionFile = fileName.sub! '.swift', '+XCTest.swift'
|
||||
print 'Creating file: ' + extensionFile + "\n"
|
||||
|
||||
File.open(extensionFile, 'w') do |file|
|
||||
file.write header(extensionFile)
|
||||
file.write "\n"
|
||||
|
||||
for classArray in classes
|
||||
file.write 'extension ' + classArray[0] + " {\n"
|
||||
file.write ' static var allTests: [(String, (' + classArray[0] + ") -> () throws -> Void)] {\n"
|
||||
file.write " return [\n"
|
||||
|
||||
for funcName in classArray[1]
|
||||
file.write ' ("' + funcName + '", ' + funcName + "),\n"
|
||||
end
|
||||
|
||||
file.write " ]\n"
|
||||
file.write " }\n"
|
||||
file.write "}\n"
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
def createLinuxMain(testsDirectory, allTestSubDirectories, files)
|
||||
fileName = testsDirectory + '/LinuxMain.swift'
|
||||
print 'Creating file: ' + fileName + "\n"
|
||||
|
||||
File.open(fileName, 'w') do |file|
|
||||
file.write header(fileName)
|
||||
file.write "\n"
|
||||
|
||||
file.write "#if os(Linux) || os(FreeBSD)\n"
|
||||
for testSubDirectory in allTestSubDirectories.sort { |x, y| x <=> y }
|
||||
file.write '@testable import ' + testSubDirectory + "\n"
|
||||
end
|
||||
file.write "\n"
|
||||
file.write "XCTMain([\n"
|
||||
|
||||
testCases = []
|
||||
for classes in files
|
||||
for classArray in classes
|
||||
testCases << classArray[0]
|
||||
end
|
||||
end
|
||||
|
||||
for testCase in testCases.sort { |x, y| x <=> y }
|
||||
file.write ' testCase(' + testCase + ".allTests),\n"
|
||||
end
|
||||
file.write "])\n"
|
||||
file.write "#endif\n"
|
||||
end
|
||||
end
|
||||
|
||||
def parseSourceFile(fileName)
|
||||
puts 'Parsing file: ' + fileName + "\n"
|
||||
|
||||
classes = []
|
||||
currentClass = nil
|
||||
inIfLinux = false
|
||||
inElse = false
|
||||
ignore = false
|
||||
|
||||
#
|
||||
# Read the file line by line
|
||||
# and parse to find the class
|
||||
# names and func names
|
||||
#
|
||||
File.readlines(fileName).each do |line|
|
||||
if inIfLinux
|
||||
if /\#else/.match(line)
|
||||
inElse = true
|
||||
ignore = true
|
||||
else
|
||||
if /\#end/.match(line)
|
||||
inElse = false
|
||||
inIfLinux = false
|
||||
ignore = false
|
||||
end
|
||||
end
|
||||
else
|
||||
if /\#if[ \t]+os\(Linux\)/.match(line)
|
||||
inIfLinux = true
|
||||
ignore = false
|
||||
end
|
||||
end
|
||||
|
||||
next if ignore
|
||||
# Match class or func
|
||||
match = line[/class[ \t]+[a-zA-Z0-9_]*(?=[ \t]*:[ \t]*XCTestCase)|func[ \t]+test[a-zA-Z0-9_]*(?=[ \t]*\(\))/, 0]
|
||||
if match
|
||||
|
||||
if match[/class/, 0] == 'class'
|
||||
className = match.sub(/^class[ \t]+/, '')
|
||||
#
|
||||
# Create a new class / func structure
|
||||
# and add it to the classes array.
|
||||
#
|
||||
currentClass = [className, []]
|
||||
classes << currentClass
|
||||
else # Must be a func
|
||||
funcName = match.sub(/^func[ \t]+/, '')
|
||||
#
|
||||
# Add each func name the the class / func
|
||||
# structure created above.
|
||||
#
|
||||
currentClass[1] << funcName
|
||||
end
|
||||
end
|
||||
end
|
||||
classes
|
||||
end
|
||||
|
||||
#
|
||||
# Main routine
|
||||
#
|
||||
#
|
||||
|
||||
testsDirectory = 'Tests'
|
||||
|
||||
options = GetoptLong.new(['--tests-dir', GetoptLong::OPTIONAL_ARGUMENT])
|
||||
options.quiet = true
|
||||
|
||||
begin
|
||||
options.each do |option, value|
|
||||
case option
|
||||
when '--tests-dir'
|
||||
testsDirectory = value
|
||||
end
|
||||
end
|
||||
rescue GetoptLong::InvalidOption
|
||||
end
|
||||
|
||||
allTestSubDirectories = []
|
||||
allFiles = []
|
||||
|
||||
Dir[testsDirectory + '/*'].each do |subDirectory|
|
||||
next unless File.directory?(subDirectory)
|
||||
directoryHasClasses = false
|
||||
Dir[subDirectory + '/*Test{s,}.swift'].each do |fileName|
|
||||
next unless File.file? fileName
|
||||
fileClasses = parseSourceFile(fileName)
|
||||
|
||||
#
|
||||
# If there are classes in the
|
||||
# test source file, create an extension
|
||||
# file for it.
|
||||
#
|
||||
next unless fileClasses.count > 0
|
||||
createExtensionFile(fileName, fileClasses)
|
||||
directoryHasClasses = true
|
||||
allFiles << fileClasses
|
||||
end
|
||||
|
||||
if directoryHasClasses
|
||||
allTestSubDirectories << Pathname.new(subDirectory).split.last.to_s
|
||||
end
|
||||
end
|
||||
|
||||
#
|
||||
# Last step is the create a LinuxMain.swift file that
|
||||
# references all the classes and funcs in the source files.
|
||||
#
|
||||
if allFiles.count > 0
|
||||
createLinuxMain(testsDirectory, allTestSubDirectories, allFiles)
|
||||
end
|
||||
# eof
|
||||
@@ -1,169 +0,0 @@
|
||||
#!/bin/bash
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) 2018-2019 Apple Inc. and the Swift Logging API project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of Swift Logging API project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the SwiftNIO open source project
|
||||
##
|
||||
## Copyright (c) 2017-2019 Apple Inc. and the SwiftNIO project authors
|
||||
## Licensed under Apache License v2.0
|
||||
##
|
||||
## See LICENSE.txt for license information
|
||||
## See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
||||
##
|
||||
## SPDX-License-Identifier: Apache-2.0
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
|
||||
set -eu
|
||||
here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
|
||||
|
||||
function replace_acceptable_years() {
|
||||
# this needs to replace all acceptable forms with 'YEARS'
|
||||
sed -e 's/20[12][78901]-20[12][8901]/YEARS/' -e 's/20[12][8901]/YEARS/'
|
||||
}
|
||||
|
||||
printf "=> Checking linux tests... "
|
||||
FIRST_OUT="$(git status --porcelain)"
|
||||
ruby "$here/../scripts/generate_linux_tests.rb" > /dev/null
|
||||
SECOND_OUT="$(git status --porcelain)"
|
||||
if [[ "$FIRST_OUT" != "$SECOND_OUT" ]]; then
|
||||
printf "\033[0;31mmissing changes!\033[0m\n"
|
||||
git --no-pager diff
|
||||
exit 1
|
||||
else
|
||||
printf "\033[0;32mokay.\033[0m\n"
|
||||
fi
|
||||
|
||||
printf "=> Checking for unacceptable language... "
|
||||
# This greps for unacceptable terminology. The square bracket[s] are so that
|
||||
# "git grep" doesn't find the lines that greps :).
|
||||
unacceptable_terms=(
|
||||
-e blacklis[t]
|
||||
-e whitelis[t]
|
||||
-e slav[e]
|
||||
-e sanit[y]
|
||||
)
|
||||
if git grep --color=never -i "${unacceptable_terms[@]}" > /dev/null; then
|
||||
printf "\033[0;31mUnacceptable language found.\033[0m\n"
|
||||
git grep -i "${unacceptable_terms[@]}"
|
||||
exit 1
|
||||
fi
|
||||
printf "\033[0;32mokay.\033[0m\n"
|
||||
|
||||
printf "=> Checking format... "
|
||||
FIRST_OUT="$(git status --porcelain)"
|
||||
swiftformat . > /dev/null 2>&1
|
||||
SECOND_OUT="$(git status --porcelain)"
|
||||
if [[ "$FIRST_OUT" != "$SECOND_OUT" ]]; then
|
||||
printf "\033[0;31mformatting issues!\033[0m\n"
|
||||
git --no-pager diff
|
||||
exit 1
|
||||
else
|
||||
printf "\033[0;32mokay.\033[0m\n"
|
||||
fi
|
||||
|
||||
printf "=> Checking license headers\n"
|
||||
tmp=$(mktemp /tmp/.swift-log-soundness_XXXXXX)
|
||||
|
||||
for language in swift-or-c bash dtrace; do
|
||||
printf " * $language... "
|
||||
declare -a matching_files
|
||||
declare -a exceptions
|
||||
expections=( )
|
||||
matching_files=( -name '*' )
|
||||
case "$language" in
|
||||
swift-or-c)
|
||||
exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h)
|
||||
matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
|
||||
cat > "$tmp" <<"EOF"
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Logging API open source project
|
||||
//
|
||||
// Copyright (c) YEARS 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
EOF
|
||||
;;
|
||||
bash)
|
||||
matching_files=( -name '*.sh' )
|
||||
cat > "$tmp" <<"EOF"
|
||||
#!/bin/bash
|
||||
##===----------------------------------------------------------------------===##
|
||||
##
|
||||
## This source file is part of the Swift Logging API open source project
|
||||
##
|
||||
## Copyright (c) YEARS 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
|
||||
##
|
||||
##===----------------------------------------------------------------------===##
|
||||
EOF
|
||||
;;
|
||||
dtrace)
|
||||
matching_files=( -name '*.d' )
|
||||
cat > "$tmp" <<"EOF"
|
||||
#!/usr/sbin/dtrace -q -s
|
||||
/*===----------------------------------------------------------------------===*
|
||||
*
|
||||
* This source file is part of the Swift Logging API open source project
|
||||
*
|
||||
* Copyright (c) YEARS 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
|
||||
*
|
||||
*===----------------------------------------------------------------------===*/
|
||||
EOF
|
||||
;;
|
||||
*)
|
||||
echo >&2 "ERROR: unknown language '$language'"
|
||||
;;
|
||||
esac
|
||||
|
||||
expected_lines=$(cat "$tmp" | wc -l)
|
||||
expected_sha=$(cat "$tmp" | shasum)
|
||||
|
||||
(
|
||||
cd "$here/.."
|
||||
find . \
|
||||
\( \! -path './.build/*' -a \
|
||||
\( "${matching_files[@]}" \) -a \
|
||||
\( \! \( "${exceptions[@]}" \) \) \) | while read line; do
|
||||
if [[ "$(cat "$line" | replace_acceptable_years | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then
|
||||
printf "\033[0;31mmissing headers in file '$line'!\033[0m\n"
|
||||
diff -u <(cat "$line" | replace_acceptable_years | head -n $expected_lines) "$tmp"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
printf "\033[0;32mokay.\033[0m\n"
|
||||
)
|
||||
done
|
||||
|
||||
rm "$tmp"
|
||||
Reference in new issue
Block a user