Skip to content

Commit f0d6746

Browse files
yim-leestevapple
yim-lee
and
stevapple
authored
DocC Setup (#63)
* DocC Setup * Fix soundness script * Workaround LinuxMain error in newer Swift versions * Update Sources/Tracing/Docs.docc/InDepthGuide.md Co-authored-by: YR Chen <[email protected]> * Don't link to specific lines of code Co-authored-by: YR Chen <[email protected]>
1 parent d937d1b commit f0d6746

24 files changed

+903
-86
lines changed

‎Package.swift

+5-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// swift-tools-version:5.2
1+
// swift-tools-version:5.6
22
import PackageDescription
33

44
let package = Package(
@@ -9,6 +9,7 @@ let package = Package(
99
],
1010
dependencies: [
1111
.package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
12+
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
1213
],
1314
targets: [
1415
// ==== --------------------------------------------------------------------------------------------------------
@@ -46,7 +47,7 @@ let package = Package(
4647
// ==== --------------------------------------------------------------------------------------------------------
4748
// MARK: Performance / Benchmarks
4849

49-
.target(
50+
.executableTarget(
5051
name: "_TracingBenchmarks",
5152
dependencies: [
5253
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
@@ -56,7 +57,8 @@ let package = Package(
5657
),
5758
.target(
5859
name: "_TracingBenchmarkTools",
59-
dependencies: []
60+
dependencies: [],
61+
exclude: ["README_SWIFT.md"]
6062
),
6163
]
6264
)

‎[email protected]

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// swift-tools-version:5.2
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "swift-distributed-tracing",
6+
products: [
7+
.library(name: "Instrumentation", targets: ["Instrumentation"]),
8+
.library(name: "Tracing", targets: ["Tracing"]),
9+
],
10+
dependencies: [
11+
.package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
12+
],
13+
targets: [
14+
// ==== --------------------------------------------------------------------------------------------------------
15+
// MARK: Instrumentation
16+
17+
.target(
18+
name: "Instrumentation",
19+
dependencies: [
20+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
21+
]
22+
),
23+
.testTarget(
24+
name: "InstrumentationTests",
25+
dependencies: [
26+
.target(name: "Instrumentation"),
27+
]
28+
),
29+
30+
// ==== --------------------------------------------------------------------------------------------------------
31+
// MARK: Tracing
32+
33+
.target(
34+
name: "Tracing",
35+
dependencies: [
36+
.target(name: "Instrumentation"),
37+
]
38+
),
39+
.testTarget(
40+
name: "TracingTests",
41+
dependencies: [
42+
.target(name: "Tracing"),
43+
]
44+
),
45+
46+
// ==== --------------------------------------------------------------------------------------------------------
47+
// MARK: Performance / Benchmarks
48+
49+
.target(
50+
name: "_TracingBenchmarks",
51+
dependencies: [
52+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
53+
.target(name: "Tracing"),
54+
.target(name: "_TracingBenchmarkTools"),
55+
]
56+
),
57+
.target(
58+
name: "_TracingBenchmarkTools",
59+
dependencies: []
60+
),
61+
]
62+
)

‎[email protected]

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// swift-tools-version:5.2
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "swift-distributed-tracing",
6+
products: [
7+
.library(name: "Instrumentation", targets: ["Instrumentation"]),
8+
.library(name: "Tracing", targets: ["Tracing"]),
9+
],
10+
dependencies: [
11+
.package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
12+
],
13+
targets: [
14+
// ==== --------------------------------------------------------------------------------------------------------
15+
// MARK: Instrumentation
16+
17+
.target(
18+
name: "Instrumentation",
19+
dependencies: [
20+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
21+
]
22+
),
23+
.testTarget(
24+
name: "InstrumentationTests",
25+
dependencies: [
26+
.target(name: "Instrumentation"),
27+
]
28+
),
29+
30+
// ==== --------------------------------------------------------------------------------------------------------
31+
// MARK: Tracing
32+
33+
.target(
34+
name: "Tracing",
35+
dependencies: [
36+
.target(name: "Instrumentation"),
37+
]
38+
),
39+
.testTarget(
40+
name: "TracingTests",
41+
dependencies: [
42+
.target(name: "Tracing"),
43+
]
44+
),
45+
46+
// ==== --------------------------------------------------------------------------------------------------------
47+
// MARK: Performance / Benchmarks
48+
49+
.target(
50+
name: "_TracingBenchmarks",
51+
dependencies: [
52+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
53+
.target(name: "Tracing"),
54+
.target(name: "_TracingBenchmarkTools"),
55+
]
56+
),
57+
.target(
58+
name: "_TracingBenchmarkTools",
59+
dependencies: []
60+
),
61+
]
62+
)

‎[email protected]

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// swift-tools-version:5.2
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "swift-distributed-tracing",
6+
products: [
7+
.library(name: "Instrumentation", targets: ["Instrumentation"]),
8+
.library(name: "Tracing", targets: ["Tracing"]),
9+
],
10+
dependencies: [
11+
.package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
12+
],
13+
targets: [
14+
// ==== --------------------------------------------------------------------------------------------------------
15+
// MARK: Instrumentation
16+
17+
.target(
18+
name: "Instrumentation",
19+
dependencies: [
20+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
21+
]
22+
),
23+
.testTarget(
24+
name: "InstrumentationTests",
25+
dependencies: [
26+
.target(name: "Instrumentation"),
27+
]
28+
),
29+
30+
// ==== --------------------------------------------------------------------------------------------------------
31+
// MARK: Tracing
32+
33+
.target(
34+
name: "Tracing",
35+
dependencies: [
36+
.target(name: "Instrumentation"),
37+
]
38+
),
39+
.testTarget(
40+
name: "TracingTests",
41+
dependencies: [
42+
.target(name: "Tracing"),
43+
]
44+
),
45+
46+
// ==== --------------------------------------------------------------------------------------------------------
47+
// MARK: Performance / Benchmarks
48+
49+
.target(
50+
name: "_TracingBenchmarks",
51+
dependencies: [
52+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
53+
.target(name: "Tracing"),
54+
.target(name: "_TracingBenchmarkTools"),
55+
]
56+
),
57+
.target(
58+
name: "_TracingBenchmarkTools",
59+
dependencies: []
60+
),
61+
]
62+
)

‎[email protected]

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// swift-tools-version:5.2
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "swift-distributed-tracing",
6+
products: [
7+
.library(name: "Instrumentation", targets: ["Instrumentation"]),
8+
.library(name: "Tracing", targets: ["Tracing"]),
9+
],
10+
dependencies: [
11+
.package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
12+
],
13+
targets: [
14+
// ==== --------------------------------------------------------------------------------------------------------
15+
// MARK: Instrumentation
16+
17+
.target(
18+
name: "Instrumentation",
19+
dependencies: [
20+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
21+
]
22+
),
23+
.testTarget(
24+
name: "InstrumentationTests",
25+
dependencies: [
26+
.target(name: "Instrumentation"),
27+
]
28+
),
29+
30+
// ==== --------------------------------------------------------------------------------------------------------
31+
// MARK: Tracing
32+
33+
.target(
34+
name: "Tracing",
35+
dependencies: [
36+
.target(name: "Instrumentation"),
37+
]
38+
),
39+
.testTarget(
40+
name: "TracingTests",
41+
dependencies: [
42+
.target(name: "Tracing"),
43+
]
44+
),
45+
46+
// ==== --------------------------------------------------------------------------------------------------------
47+
// MARK: Performance / Benchmarks
48+
49+
.target(
50+
name: "_TracingBenchmarks",
51+
dependencies: [
52+
.product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
53+
.target(name: "Tracing"),
54+
.target(name: "_TracingBenchmarkTools"),
55+
]
56+
),
57+
.target(
58+
name: "_TracingBenchmarkTools",
59+
dependencies: []
60+
),
61+
]
62+
)

‎README.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -226,9 +226,9 @@ While this is verbose, this is only the low-level building blocks that this libr
226226

227227
> 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`.
228228
229-
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:
229+
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:
230230

231-
![Simple example trace in Zipkin Web UI](images/zipkin_trace.png)
231+
![Simple example trace in Zipkin Web UI](Sources/Tracing/Docs.docc/Resources/zipkin_trace.png)
232232

233233
### More examples
234234

@@ -402,7 +402,7 @@ When adapting an existing library/framework to support `LoggingContext` and it a
402402

403403
Examples:
404404

405-
- `Lamda.Context` may contain `baggage` and a `logger` and should be able to conform to `LoggingContext`
405+
- `Lambda.Context` may contain `baggage` and a `logger` and should be able to conform to `LoggingContext`
406406
- passing context to a `Lambda.Context` unaware library becomes: `http.request(url: "...", context: context)`.
407407
- `ChannelHandlerContext` offers a way to set/get baggage on the underlying channel via `context.baggage = ...`
408408
- 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
414414

415415
If really necessary, or for the purposes of testing, one can create a baggage or context using one of the two factory functions:
416416

417-
- [`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.
418-
- [`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.
417+
- [`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.
418+
- [`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.
419419

420420
Please refer to the respective functions documentation for details.
421421

‎Sources/Instrumentation/Instrument.swift

+5-5
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
//
33
// This source file is part of the Swift Distributed Tracing open source project
44
//
5-
// Copyright (c) 2020-2021 Apple Inc. and the Swift Distributed Tracing project
5+
// Copyright (c) 2020-2022 Apple Inc. and the Swift Distributed Tracing project
66
// authors
77
// Licensed under Apache License v2.0
88
//
@@ -44,22 +44,22 @@ public protocol Injector {
4444
/// Conforming types are usually cross-cutting tools like tracers. They are agnostic of what specific `Carrier` is used
4545
/// to propagate metadata across boundaries, but instead just specify what values to use for which keys.
4646
public protocol Instrument {
47-
/// Extract values from a `Carrier` by using the given extractor and inject them into the given `BaggageContext`.
47+
/// Extract values from a `Carrier` by using the given extractor and inject them into the given `Baggage`.
4848
/// It's quite common for `Instrument`s to come up with new values if they weren't passed along in the given `Carrier`.
4949
///
5050
/// - Parameters:
5151
/// - carrier: The `Carrier` that was used to propagate values across boundaries.
5252
/// - baggage: The `Baggage` into which these values should be injected.
53-
/// - extractor: The `Extractor` that extracts values from the given `Carrier`.
53+
/// - extractor: The ``Extractor`` that extracts values from the given `Carrier`.
5454
func extract<Carrier, Extract>(_ carrier: Carrier, into baggage: inout Baggage, using extractor: Extract)
5555
where Extract: Extractor, Extract.Carrier == Carrier
5656

57-
/// Inject values from a `BaggageContext` and inject them into the given `Carrier` using the given `Injector`.
57+
/// Extract values from a `Baggage` and inject them into the given `Carrier` using the given ``Injector``.
5858
///
5959
/// - Parameters:
6060
/// - baggage: The `Baggage` from which relevant information will be extracted.
6161
/// - carrier: The `Carrier` into which this information will be injected.
62-
/// - injector: The `Injector` used to inject extracted `BaggageContext` into the given `Carrier`.
62+
/// - injector: The ``Injector`` used to inject extracted `Baggage` into the given `Carrier`.
6363
func inject<Carrier, Inject>(_ baggage: Baggage, into carrier: inout Carrier, using injector: Inject)
6464
where Inject: Injector, Inject.Carrier == Carrier
6565
}

0 commit comments

Comments
 (0)