apple · yim-lee · Aug 10, 2022 · Aug 10, 2022 · Aug 10, 2022 · Aug 10, 2022
diff --git a/Package.swift b/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.2
+// swift-tools-version:5.6
 import PackageDescription
 
 let package = Package(
@@ -9,6 +9,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
         // ==== --------------------------------------------------------------------------------------------------------
@@ -46,7 +47,7 @@ let package = Package(
         // ==== --------------------------------------------------------------------------------------------------------
         // MARK: Performance / Benchmarks
 
-        .target(
+        .executableTarget(
             name: "_TracingBenchmarks",
             dependencies: [
                 .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
@@ -56,7 +57,8 @@ let package = Package(
         ),
         .target(
             name: "_TracingBenchmarkTools",
-            dependencies: []
+            dependencies: [],
+            exclude: ["README_SWIFT.md"]
         ),
     ]
 )
diff --git a/Package@swift-5.2.swift b/Package@swift-5.2.swift
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/Package@swift-5.3.swift b/Package@swift-5.3.swift
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/Package@swift-5.4.swift b/Package@swift-5.4.swift
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/Package@swift-5.5.swift b/Package@swift-5.5.swift
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/README.md b/README.md
@@ -226,9 +226,9 @@ While this is verbose, this is only the low-level building blocks that this libr
 
 > Eventually convenience wrappers will be provided, automatically wrapping future types etc. We welcome such contributions, but likely they should live in `swift-distributed-tracing-extras`.
 
-Once a system, or multiple systems have been instrumented, a Tracer been selected and your application runs and emits some trace information, you will be able to inspect how your application is behaving by looking at one of the various trace UIs, such as e.g. Zipkin:
+Once a system, or multiple systems have been instrumented, a Tracer has been selected and your application runs and emits some trace information, you will be able to inspect how your application is behaving by looking at one of the various trace UIs, such as e.g. Zipkin:
 
-![Simple example trace in Zipkin Web UI](images/zipkin_trace.png)
+![Simple example trace in Zipkin Web UI](Sources/Tracing/Docs.docc/Resources/zipkin_trace.png)
 
 ### More examples
 
@@ -402,7 +402,7 @@ When adapting an existing library/framework to support `LoggingContext` and it a
 
 Examples:
 
-- `Lamda.Context` may contain `baggage` and a `logger` and should be able to conform to `LoggingContext`
+- `Lambda.Context` may contain `baggage` and a `logger` and should be able to conform to `LoggingContext`
   - passing context to a `Lambda.Context` unaware library becomes: `http.request(url: "...", context: context)`.
 - `ChannelHandlerContext` offers a way to set/get baggage on the underlying channel via `context.baggage = ...`
   - this context is not passed outside a handler, but within it may be passed as is, and the baggage may be accessed on it directly through it.
@@ -414,8 +414,8 @@ Generally application developers _should not_ create new context objects, but ra
 
 If really necessary, or for the purposes of testing, one can create a baggage or context using one of the two factory functions:
 
-- [`DefaultLoggingContext.topLevel(logger:)`](https://github.com/apple/swift-distributed-tracing-baggage/blob/main/Sources/Baggage/LoggingContext.swift#L232-L259) or [`Baggage.topLevel`](https://github.com/apple/swift-distributed-tracing-baggage-core/blob/main/Sources/CoreBaggage/Baggage.swift#L79-L103) - which creates an empty context/baggage, without any values. It should _not_ be used too frequently, and as the name implies in applications it only should be used on the "top level" of the application, or at the beginning of a contextless (e.g. timer triggered) event processing.
-- [`DefaultLoggingContext.TODO(logger:reason:)`](https://github.com/apple/swift-distributed-tracing-baggage/blob/main/Sources/Baggage/LoggingContext.swift#L262-L292) or [`Baggage.TODO`](https://github.com/apple/swift-distributed-tracing-baggage-core/blob/main/Sources/CoreBaggage/Baggage.swift#L107-L136) - which should be used to mark a parameter where "before this code goes into production, a real context should be passed instead." An application can be run with `-DBAGGAGE_CRASH_TODOS` to cause the application to crash whenever a TODO context is still in use somewhere, making it easy to diagnose and avoid breaking context propagation by accidentally leaving in a `TODO` context in production.
+- [`DefaultLoggingContext.topLevel(logger:)`](https://github.com/apple/swift-distributed-tracing-baggage/blob/main/Sources/Baggage/LoggingContext.swift) or [`Baggage.topLevel`](https://github.com/apple/swift-distributed-tracing-baggage-core/blob/main/Sources/CoreBaggage/Baggage.swift) - which creates an empty context/baggage, without any values. It should _not_ be used too frequently, and as the name implies in applications it only should be used on the "top level" of the application, or at the beginning of a contextless (e.g. timer triggered) event processing.
+- [`DefaultLoggingContext.TODO(logger:reason:)`](https://github.com/apple/swift-distributed-tracing-baggage/blob/main/Sources/Baggage/LoggingContext.swift) or [`Baggage.TODO`](https://github.com/apple/swift-distributed-tracing-baggage-core/blob/main/Sources/CoreBaggage/Baggage.swift) - which should be used to mark a parameter where "before this code goes into production, a real context should be passed instead." An application can be run with `-DBAGGAGE_CRASH_TODOS` to cause the application to crash whenever a TODO context is still in use somewhere, making it easy to diagnose and avoid breaking context propagation by accidentally leaving in a `TODO` context in production.
 
 Please refer to the respective functions documentation for details.
 

diff --git a/Sources/Instrumentation/Instrument.swift b/Sources/Instrumentation/Instrument.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift Distributed Tracing open source project
 //
-// Copyright (c) 2020-2021 Apple Inc. and the Swift Distributed Tracing project
+// Copyright (c) 2020-2022 Apple Inc. and the Swift Distributed Tracing project
 // authors
 // Licensed under Apache License v2.0
 //
@@ -44,22 +44,22 @@ public protocol Injector {
 /// Conforming types are usually cross-cutting tools like tracers. They are agnostic of what specific `Carrier` is used
 /// to propagate metadata across boundaries, but instead just specify what values to use for which keys.
 public protocol Instrument {
-    /// Extract values from a `Carrier` by using the given extractor and inject them into the given `BaggageContext`.
+    /// Extract values from a `Carrier` by using the given extractor and inject them into the given `Baggage`.
     /// It's quite common for `Instrument`s to come up with new values if they weren't passed along in the given `Carrier`.
     ///
     /// - Parameters:
     ///   - carrier: The `Carrier` that was used to propagate values across boundaries.
     ///   - baggage: The `Baggage` into which these values should be injected.
-    ///   - extractor: The `Extractor` that extracts values from the given `Carrier`.
+    ///   - extractor: The ``Extractor`` that extracts values from the given `Carrier`.
     func extract<Carrier, Extract>(_ carrier: Carrier, into baggage: inout Baggage, using extractor: Extract)
         where Extract: Extractor, Extract.Carrier == Carrier
 
-    /// Inject values from a `BaggageContext` and inject them into the given `Carrier` using the given `Injector`.
+    /// Extract values from a `Baggage` and inject them into the given `Carrier` using the given ``Injector``.
     ///
     /// - Parameters:
     ///   - baggage: The `Baggage` from which relevant information will be extracted.
     ///   - carrier: The `Carrier` into which this information will be injected.
-    ///   - injector: The `Injector` used to inject extracted `BaggageContext` into the given `Carrier`.
+    ///   - injector: The ``Injector`` used to inject extracted `Baggage` into the given `Carrier`.
     func inject<Carrier, Inject>(_ baggage: Baggage, into carrier: inout Carrier, using injector: Inject)
         where Inject: Injector, Inject.Carrier == Carrier
 }