Merge pull request #73 from slashmo/feature/spanlink

Add SpanLink type

Author: ktoso

Sources/Instrumentation/Tracing/NoOpTracing.swift

@@ -41,6 +41,7 @@ public struct NoOpTracingInstrument: TracingInstrument {
         public var operationName: String = ""
         public var status: SpanStatus?
         public let kind: SpanKind = .internal
+        public let links = [SpanLink]()
 
         public var startTimestamp: DispatchTime {
             .now()
@@ -56,6 +57,8 @@ public struct NoOpTracingInstrument: TracingInstrument {
             []
         }
 
+        public mutating func addLink(_ link: SpanLink) {}
+
         public mutating func addEvent(_ event: SpanEvent) {}
 
         public var attributes: SpanAttributes {

Sources/Instrumentation/Tracing/Span.swift

@@ -48,14 +48,19 @@ public protocol Span {
     /// - Parameter event: The `SpanEvent` to add to this `Span`.
     mutating func addEvent(_ event: SpanEvent)
 
-    // TODO: Wrap in a struct to hide collection implementation details.
-
     /// The attributes describing this `Span`.
     var attributes: SpanAttributes { get set }
 
     /// Returns true if this `Span` is recording information like events, attributes, status, etc.
     var isRecording: Bool { get }
 
+    /// The read-only collection of linked `Span`s.
+    var links: [SpanLink] { get }
+
+    /// Add a `SpanLink` in place.
+    /// - Parameter link: The `SpanLink` to add to this `Span`.
+    mutating func addLink(_ link: SpanLink)
+
     /// End this `Span` at the given timestamp.
     /// - Parameter timestamp: The `DispatchTime` at which the span ended.
     mutating func end(at timestamp: DispatchTime)
@@ -270,3 +275,26 @@ public enum SpanKind {
     /// Indicates that the span represents an internal operation within an application, as opposed to an operations with remote parents or children.
     case `internal`
 }
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: Span Link
+
+/// A link to another `Span`.
+/// The other `Span`s information is stored in `context` and `attributes` may be used to
+/// further describe the link.
+public struct SpanLink {
+    /// A `BaggageContext` containing identifying information about the link target `Span`.
+    public let context: BaggageContext
+
+    /// `SpanAttributes` further describing the connection between the `Span`s.
+    public let attributes: SpanAttributes
+
+    /// Create a new `SpanLink`.
+    /// - Parameters:
+    ///   - context: The `BaggageContext` identifying the targeted `Span`.
+    ///   - attributes: `SpanAttributes` that further describe the link. Defaults to no attributes.
+    public init(context: BaggageContext, attributes: SpanAttributes = [:]) {
+        self.context = context
+        self.attributes = attributes
+    }
+}

Tests/InstrumentationTests/Tracing/TracedLockTests.swift

@@ -94,6 +94,8 @@ private final class TracedLockPrintlnTracer: TracingInstrument {
 
         let baggage: BaggageContext
 
+        private(set) var links = [SpanLink]()
+
         private(set) var events = [SpanEvent]() {
             didSet {
                 self.isRecording = !self.events.isEmpty
@@ -122,6 +124,10 @@ private final class TracedLockPrintlnTracer: TracingInstrument {
             print("  span [\(self.operationName): \(self.baggage[TaskIDKey.self] ?? "no-name")] @ \(self.startTimestamp): start")
         }
 
+        mutating func addLink(_ link: SpanLink) {
+            self.links.append(link)
+        }
+
         mutating func addEvent(_ event: SpanEvent) {
             self.events.append(event)
         }

Tests/InstrumentationTests/TracingInstrumentTests.swift

@@ -115,6 +115,8 @@ struct OTSpan: Span {
         }
     }
 
+    private(set) var links = [SpanLink]()
+
     var attributes: SpanAttributes = [:] {
         didSet {
             self.isRecording = !self.attributes.isEmpty
@@ -139,6 +141,10 @@ struct OTSpan: Span {
         self.kind = kind
     }
 
+    mutating func addLink(_ link: SpanLink) {
+        self.links.append(link)
+    }
+
     mutating func addEvent(_ event: SpanEvent) {
         self.events.append(event)
     }