From 60393a7a24b3fb229c99a5dd6c00c3d9258c22eb Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 28 Mar 2024 16:22:01 -0700 Subject: [PATCH 1/2] update documentation references to fix broken reference links on SwiftPackageIndex hosted documentation for main --- .../Docs.docc/Guides/InstrumentYourLibrary.md | 4 ++-- .../Docs.docc/Guides/TraceYourApplication.md | 2 +- Sources/Tracing/Docs.docc/Tracer.md | 4 ++-- Sources/Tracing/SpanProtocol.swift | 4 ++-- Sources/Tracing/Tracer.swift | 6 +++--- Sources/Tracing/TracerProtocol+Legacy.swift | 14 +++++++------- Sources/Tracing/TracerProtocol.swift | 4 ++-- 7 files changed, 19 insertions(+), 19 deletions(-) diff --git a/Sources/Tracing/Docs.docc/Guides/InstrumentYourLibrary.md b/Sources/Tracing/Docs.docc/Guides/InstrumentYourLibrary.md index c7fc830..18d6736 100644 --- a/Sources/Tracing/Docs.docc/Guides/InstrumentYourLibrary.md +++ b/Sources/Tracing/Docs.docc/Guides/InstrumentYourLibrary.md @@ -238,7 +238,7 @@ func handler(request: HTTPRequest) async { } ``` -This is introducing multiple layers of nesting, and we have un-necessarily restored, picked-up, and restored the context again. In order to avoid this duplicate work, it is beneficial to use the ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` overload, which also accepts a `ServiceContext` as parameter, rather than picking it up from the task-local value: +This is introducing multiple layers of nesting, and we have un-necessarily restored, picked-up, and restored the context again. In order to avoid this duplicate work, it is beneficial to use the ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` overload, which also accepts a `ServiceContext` as parameter, rather than picking it up from the task-local value: ```swift // BETTER @@ -257,7 +257,7 @@ This method will only restore the context once, after the tracer has had a chanc #### Manual Span Lifetime Management -While the ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` API is preferable in most situations, it may not be possible to use when the lifetime of a span only terminates in yet another callback API. In such situations, it may be impossible to "wrap" the entire piece of code that would logically represent "the span" using a `withSpan(...) { ... }` call. +While the ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` API is preferable in most situations, it may not be possible to use when the lifetime of a span only terminates in yet another callback API. In such situations, it may be impossible to "wrap" the entire piece of code that would logically represent "the span" using a `withSpan(...) { ... }` call. In such situations you can resort to using the ``startSpan(_:context:ofKind:at:function:file:line:)`` and ``Span/end()`` APIs explicitly. Those APIs can then be used like this: diff --git a/Sources/Tracing/Docs.docc/Guides/TraceYourApplication.md b/Sources/Tracing/Docs.docc/Guides/TraceYourApplication.md index 8b4341b..8cf8e68 100644 --- a/Sources/Tracing/Docs.docc/Guides/TraceYourApplication.md +++ b/Sources/Tracing/Docs.docc/Guides/TraceYourApplication.md @@ -258,7 +258,7 @@ This was just a quick introduction to tracing, but hopefully you are now excited ### Efficiently working with Spans -We already saw the basic API to spawn a trace span, the ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` method, but we didn't discuss it in depth yet. In this section we'll discuss how to efficiently work with spans and some common patterns and practices. +We already saw the basic API to spawn a trace span, the ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` method, but we didn't discuss it in depth yet. In this section we'll discuss how to efficiently work with spans and some common patterns and practices. Firstly, spans are created using a `withSpan` call and performing the operation contained within the span in the trailing operation closure body. This is important because it automatically, and correctly, delimits the lifetime of the span: from its creation, until the operation closure returns: diff --git a/Sources/Tracing/Docs.docc/Tracer.md b/Sources/Tracing/Docs.docc/Tracer.md index 8a400f7..f2e3e59 100644 --- a/Sources/Tracing/Docs.docc/Tracer.md +++ b/Sources/Tracing/Docs.docc/Tracer.md @@ -4,9 +4,9 @@ ### Creating Spans -- ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` +- ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` ### Manual Span management -- ``startSpan(_:context:ofKind:at:function:file:line:)-u1y4`` +- ``startSpan(_:context:ofKind:at:function:file:line:)-c9un`` - ``Span/end()`` diff --git a/Sources/Tracing/SpanProtocol.swift b/Sources/Tracing/SpanProtocol.swift index 50125fe..f682fa1 100644 --- a/Sources/Tracing/SpanProtocol.swift +++ b/Sources/Tracing/SpanProtocol.swift @@ -135,8 +135,8 @@ extension Span { /// /// Implementations SHOULD prevent double-emitting by marking a span as ended internally, however it still is a /// programming mistake to rely on this behavior. - /// - /// - SeeAlso: ``end(clock:)`` which allows passing in a specific time, e.g. if the operation was ended and recorded somewhere and we need to post-factum record it. + /// + /// - SeeAlso: ``end(at:)`` which allows passing in a specific time, e.g. if the operation was ended and recorded somewhere and we need to post-factum record it. /// Generally though prefer using the ``end()`` version of this API in user code and structure your system such that it can be called in the right place and time. public func end() { self.end(at: DefaultTracerClock.now) diff --git a/Sources/Tracing/Tracer.swift b/Sources/Tracing/Tracer.swift index 726aa88..e3ca14c 100644 --- a/Sources/Tracing/Tracer.swift +++ b/Sources/Tracing/Tracer.swift @@ -24,7 +24,7 @@ import Dispatch /// we're about to start a top-level span, or if a span should be started from a different, /// stored away previously, /// -/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start +/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -71,7 +71,7 @@ public func startSpan( /// we're about to start a top-level span, or if a span should be started from a different, /// stored away previously, /// -/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start +/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -116,7 +116,7 @@ public func startSpan( /// we're about to start a top-level span, or if a span should be started from a different, /// stored away previously, /// -/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start +/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. diff --git a/Sources/Tracing/TracerProtocol+Legacy.swift b/Sources/Tracing/TracerProtocol+Legacy.swift index 3426cc9..3c07976 100644 --- a/Sources/Tracing/TracerProtocol+Legacy.swift +++ b/Sources/Tracing/TracerProtocol+Legacy.swift @@ -21,7 +21,7 @@ import Dispatch /// **This protocol will be deprecated as soon as possible**, and the library will continue recommending Swift 5.7+ /// in order to make use of new language features that make expressing the tracing API free of existential types when not necessary. /// -/// When possible, prefer using ``Tracer`` and ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` APIs, +/// When possible, prefer using ``Tracer`` and ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` APIs, /// rather than these `startAnySpan` APIs which unconditionally always return existential Spans even when not necessary /// (under Swift 5.7+ type-system enhancement wrt. protocols with associated types).. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext @@ -39,7 +39,7 @@ public protocol LegacyTracer: Instrument { /// /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at: /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -96,7 +96,7 @@ extension LegacyTracer { /// /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at: /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -146,7 +146,7 @@ extension LegacyTracer { /// /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at: /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -407,7 +407,7 @@ extension Tracer { /// /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at: /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -456,7 +456,7 @@ extension Tracer { /// /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at: /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -511,7 +511,7 @@ extension Tracer { /// /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at: /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. diff --git a/Sources/Tracing/TracerProtocol.swift b/Sources/Tracing/TracerProtocol.swift index 0a0a13d..19d8679 100644 --- a/Sources/Tracing/TracerProtocol.swift +++ b/Sources/Tracing/TracerProtocol.swift @@ -34,7 +34,7 @@ public protocol Tracer: LegacyTracer { /// we're about to start a top-level span, or if a span should be started from a different, /// stored away previously, /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. @@ -71,7 +71,7 @@ extension Tracer { /// we're about to start a top-level span, or if a span should be started from a different, /// stored away previously, /// - /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start + /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start /// a span as it automatically takes care of ending the span, and recording errors when thrown. /// Use `startSpan` iff you need to pass the span manually to a different /// location in your source code to end it. From 3a97d46167cd257fd9e6d9a59667d73f5909d62e Mon Sep 17 00:00:00 2001 From: Joseph Heck Date: Thu, 28 Mar 2024 16:37:10 -0700 Subject: [PATCH 2/2] Update Sources/Tracing/SpanProtocol.swift Co-authored-by: Moritz Lang --- Sources/Tracing/SpanProtocol.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/Tracing/SpanProtocol.swift b/Sources/Tracing/SpanProtocol.swift index f682fa1..693c1c1 100644 --- a/Sources/Tracing/SpanProtocol.swift +++ b/Sources/Tracing/SpanProtocol.swift @@ -135,7 +135,7 @@ extension Span { /// /// Implementations SHOULD prevent double-emitting by marking a span as ended internally, however it still is a /// programming mistake to rely on this behavior. - /// + /// /// - SeeAlso: ``end(at:)`` which allows passing in a specific time, e.g. if the operation was ended and recorded somewhere and we need to post-factum record it. /// Generally though prefer using the ``end()`` version of this API in user code and structure your system such that it can be called in the right place and time. public func end() {