From daf4e6be7992872521e88e3f21c9306dd485a126 Mon Sep 17 00:00:00 2001 From: Moritz Lang <16192401+slashmo@users.noreply.github.com> Date: Tue, 17 Dec 2024 00:20:30 +0100 Subject: [PATCH 1/3] Add recordingSpan and currentSpan methods to TracerProtocol **Motivation:** Currently, it is only possible to implicitly work with the current span by transparently creating a child span (using ServiceContext.current) under the hood. This is sufficient for almost all use-cases, but does not work in case a piece of code wants to add an event to the current span without having a handle on said span, e.g. if the span was created by a library. **Modifications:** I added a `recordingSpan(identifiedBy context: ServiceContext) -> Span?` requirement to `TracerProtocol`. This way, `Tracer` implementations may look up and return a span identified by the data they stored in the provided `ServiceContext`. It's worth noting that this method is only intended for obtaining spans which are still recording as opposed to already ended ones that may not even be in memory anymore. I also added a default implementation of this method to avoid introducing a breaking change. On top of this new protocol requirement, I added an extension to `TracerProtocol` with sugar to obtain the current span based on the task-local `ServiceContext`. **Result:** Library authors and application developers are now able to look up the current recording span to interact with it by e.g. adding events and attributes. --- Sources/Tracing/TracerProtocol.swift | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/Sources/Tracing/TracerProtocol.swift b/Sources/Tracing/TracerProtocol.swift index 4fdbea8..fd203a6 100644 --- a/Sources/Tracing/TracerProtocol.swift +++ b/Sources/Tracing/TracerProtocol.swift @@ -59,6 +59,14 @@ public protocol Tracer: LegacyTracer { file fileID: String, line: UInt ) -> Self.Span + + /// Retrieve the recording span for the given `ServiceContext`. + /// + /// - Note: This API does not enable look up of already finished spans. + /// It was added retroactively with a default implementation returning `nil` and therefore isn't guaranteed to be implemented by all `Tracer`s. + /// - Parameter context: The context containing information that uniquely identifies the span being obtained. + /// - Returns: The span identified by the given `ServiceContext` in case it's still recording. + func recordingSpan(identifiedBy context: ServiceContext) -> Span? } @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext @@ -106,6 +114,24 @@ extension Tracer { line: line ) } + + /// Default implementation for ``recordingSpan(identifiedBy:)`` which always returns `nil`. + /// This default exists in order to facilitate source-compatible introduction of the ``recordingSpan(identifiedBy:)`` protocol requirement. + /// + /// - Parameter context: The context containing information that uniquely identifies the span being obtained. + /// - Returns: `nil`. + public func recordingSpan(identifiedBy context: ServiceContext) -> Span? { + nil + } + + /// Attempt to retrieve the current recording span based on the task-local `ServiceContext`. + /// + /// - Note: This method should be considered best-effort as it might not (yet) be supported by the application author's `Tracer` of choice. + /// - Returns: A span if one can be obtained via the task-local `ServiceContext`. + public func currentSpan() -> Span? { + guard let context = ServiceContext.current else { return nil } + return recordingSpan(identifiedBy: context) + } } // ==== ---------------------------------------------------------------------------------------------------------------- From d2a4716f5802185963a3f9ca245868b86615260e Mon Sep 17 00:00:00 2001 From: Moritz Lang <16192401+slashmo@users.noreply.github.com> Date: Tue, 14 Jan 2025 13:04:36 +0100 Subject: [PATCH 2/3] Remove currentSpan() syntax sugar --- Sources/Tracing/TracerProtocol.swift | 9 --------- 1 file changed, 9 deletions(-) diff --git a/Sources/Tracing/TracerProtocol.swift b/Sources/Tracing/TracerProtocol.swift index fd203a6..3577400 100644 --- a/Sources/Tracing/TracerProtocol.swift +++ b/Sources/Tracing/TracerProtocol.swift @@ -123,15 +123,6 @@ extension Tracer { public func recordingSpan(identifiedBy context: ServiceContext) -> Span? { nil } - - /// Attempt to retrieve the current recording span based on the task-local `ServiceContext`. - /// - /// - Note: This method should be considered best-effort as it might not (yet) be supported by the application author's `Tracer` of choice. - /// - Returns: A span if one can be obtained via the task-local `ServiceContext`. - public func currentSpan() -> Span? { - guard let context = ServiceContext.current else { return nil } - return recordingSpan(identifiedBy: context) - } } // ==== ---------------------------------------------------------------------------------------------------------------- From 6ae210e24cac78522206062abb3843e2a9b85785 Mon Sep 17 00:00:00 2001 From: Moritz Lang <16192401+slashmo@users.noreply.github.com> Date: Tue, 14 Jan 2025 13:04:56 +0100 Subject: [PATCH 3/3] Rename recordingSpan(context:) to activeSpan(context:) --- Sources/Tracing/TracerProtocol.swift | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Sources/Tracing/TracerProtocol.swift b/Sources/Tracing/TracerProtocol.swift index 3577400..ea4c334 100644 --- a/Sources/Tracing/TracerProtocol.swift +++ b/Sources/Tracing/TracerProtocol.swift @@ -66,7 +66,7 @@ public protocol Tracer: LegacyTracer { /// It was added retroactively with a default implementation returning `nil` and therefore isn't guaranteed to be implemented by all `Tracer`s. /// - Parameter context: The context containing information that uniquely identifies the span being obtained. /// - Returns: The span identified by the given `ServiceContext` in case it's still recording. - func recordingSpan(identifiedBy context: ServiceContext) -> Span? + func activeSpan(identifiedBy context: ServiceContext) -> Span? } @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext @@ -115,12 +115,12 @@ extension Tracer { ) } - /// Default implementation for ``recordingSpan(identifiedBy:)`` which always returns `nil`. - /// This default exists in order to facilitate source-compatible introduction of the ``recordingSpan(identifiedBy:)`` protocol requirement. + /// Default implementation for ``activeSpan(identifiedBy:)`` which always returns `nil`. + /// This default exists in order to facilitate source-compatible introduction of the ``activeSpan(identifiedBy:)`` protocol requirement. /// /// - Parameter context: The context containing information that uniquely identifies the span being obtained. /// - Returns: `nil`. - public func recordingSpan(identifiedBy context: ServiceContext) -> Span? { + public func activeSpan(identifiedBy context: ServiceContext) -> Span? { nil } }