From 7af28bef4cc8885b67686e958bb2206f14864b36 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] 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)
+ }
}
// ==== ----------------------------------------------------------------------------------------------------------------