diff --git a/Sources/Tracing/Docs.docc/Guides/InstrumentYourLibrary.md b/Sources/Tracing/Docs.docc/Guides/InstrumentYourLibrary.md index c7fc8304..18d67364 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 8b4341b5..8cf8e68f 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 8a400f7b..f2e3e597 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 50125fe9..693c1c14 100644 --- a/Sources/Tracing/SpanProtocol.swift +++ b/Sources/Tracing/SpanProtocol.swift @@ -136,7 +136,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(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 726aa883..e3ca14c9 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 3426cc99..3c079769 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 0a0a13df..19d86791 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.