mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
Provide organization (aka curation) and abstracts for all of the public
types in the library.
### Motivation:
Updates to the documentation to fill in the missing abstracts for the
provided types, updating the language to follow Apple developer content
guidelines, and fixing smaller typos and grammar issues.
### Modifications:
Curation files added to provide organization for public types, ordering
the content to align with the narrative content provided earlier.
Updating API comments, adding abstracts and parameters where missing,
and moving some of the getting started content that was previously in
the main index into a separate article.
### Result:
starting point
```
--- Experimental coverage output enabled. ---
| Abstract | Curated | Code Listing
Types | 69% (11/16) | 38% (6/16) | 25% (4/16)
Members | 57% (54/94) | 3.2% (3/94) | 0.0% (0/94)
Globals | 7.1% (1/14) | 7.1% (1/14) | 7.1% (1/14)
```
Updated:
```
| Abstract | Curated | Code Listing
Types | 94% (15/16) | 94% (15/16) | 38% (6/16)
Members | 85% (80/94) | 97% (91/94) | 0.0% (0/94)
Globals | 14% (2/14) | 100% (14/14) | 7.1% (1/14)
```
---------
Co-authored-by: Honza Dvorsky <honza@apple.com>
Co-authored-by: Franz Busch <privat@franz-busch.de>
102 lines
3.9 KiB
Swift
102 lines
3.9 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// 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 })
|
|
}
|
|
}
|
|
}
|
|
}
|