Add SpanKind enum

Author: slashmo

Sources/Instrumentation/Tracing/NoOpTracing.swift

@@ -18,7 +18,12 @@ import Dispatch
 public struct NoOpTracingInstrument: TracingInstrument {
     public var currentSpan: Span? = nil
 
-    public func startSpan(named operationName: String, context: BaggageContext, at timestamp: DispatchTime?) -> Span {
+    public func startSpan(
+        named operationName: String,
+        context: BaggageContext,
+        ofKind kind: SpanKind,
+        at timestamp: DispatchTime?
+    ) -> Span {
         NoOpSpan()
     }
 
@@ -35,6 +40,7 @@ public struct NoOpTracingInstrument: TracingInstrument {
     public struct NoOpSpan: Span {
         public var operationName: String = ""
         public var status: SpanStatus?
+        public let kind: SpanKind = .internal
 
         public var startTimestamp: DispatchTime {
             .now()

Sources/Instrumentation/Tracing/Span.swift

@@ -24,6 +24,9 @@ public protocol Span {
     /// [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span).
     var operationName: String { get }
 
+    /// The kind of this span.
+    var kind: SpanKind { get }
+
     /// The status of this span.
     var status: SpanStatus? { get set }
 
@@ -246,3 +249,24 @@ public struct SpanStatus {
         case unauthenticated
     }
 }
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: Span Kind
+
+/// Describes the relationship between the Span, its parents, and its children in a Trace.
+public enum SpanKind {
+    /// Indicates that the span covers server-side handling of a synchronous RPC or other remote request.
+    /// This span is the child of a remote `.client` span that was expected to wait for a response.
+    case server
+    /// Indicates that the span describes a synchronous request to some remote service.
+    /// This span is the parent of a remote `.server` span and waits for its response.
+    case client
+    /// Indicates that the span describes the parent of an asynchronous request. This parent span is expected to end before the corresponding child
+    /// `.consumer` span, possibly even before the child span starts. In messaging scenarios with batching,
+    /// tracing individual messages requires a new `.producer` span per message to be created.
+    case producer
+    /// Indicates that the span describes the child of an asynchronous `.producer` request.
+    case consumer
+    /// Indicates that the span represents an internal operation within an application, as opposed to an operations with remote parents or children.
+    case `internal`
+}

Sources/Instrumentation/Tracing/TracingInstrument.swift

@@ -25,7 +25,12 @@ public protocol TracingInstrument: Instrument {
     ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
     ///   - context: The `BaggageContext` within to start the new `Span`.
     ///   - timestamp: The `DispatchTime` at which to start the new `Span`.
-    func startSpan(named operationName: String, context: BaggageContext, at timestamp: DispatchTime?) -> Span
+    func startSpan(
+        named operationName: String,
+        context: BaggageContext,
+        ofKind kind: SpanKind,
+        at timestamp: DispatchTime?
+    ) -> Span
 }
 
 extension TracingInstrument {
@@ -34,7 +39,14 @@ extension TracingInstrument {
     /// - Parameters:
     ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
     ///   - context: The `BaggageContext` within to start the new `Span`.
-    public func startSpan(named operationName: String, context: BaggageContext) -> Span {
-        self.startSpan(named: operationName, context: context, at: nil)
+    ///   - kind: The `SpanKind` of the `Span` to be created. Defaults to `.internal`.
+    ///   - timestamp: The `DispatchTime` at which to start the new `Span`. Defaults to `nil`.
+    public func startSpan(
+        named operationName: String,
+        context: BaggageContext,
+        ofKind kind: SpanKind = .internal,
+        at timestamp: DispatchTime? = nil
+    ) -> Span {
+        self.startSpan(named: operationName, context: context, ofKind: .internal, at: nil)
     }
 }

Tests/InstrumentationTests/SpanTests.swift

@@ -18,7 +18,13 @@ import XCTest
 final class SpanTests: XCTestCase {
     func testAddingEventCreatesCopy() {
         // TODO: We should probably replace OTSpan at some point with a NoOpSpan for testing things like this.
-        let span = OTSpan(operationName: "test", startTimestamp: .now(), context: BaggageContext(), onEnd: { _ in })
+        let span = OTSpan(
+            operationName: "test",
+            startTimestamp: .now(),
+            context: BaggageContext(),
+            kind: .internal,
+            onEnd: { _ in }
+        )
         XCTAssert(span.events.isEmpty)
 
         let copiedSpan = span.addingEvent("test-event")

Tests/InstrumentationTests/Tracing/TracedLockTests.swift

@@ -55,8 +55,18 @@ enum TaskIDKey: BaggageContextKey {
 private final class TracedLockPrintlnTracer: TracingInstrument {
     var currentSpan: Span? // FIXME: likely not like that
 
-    func startSpan(named operationName: String, context: BaggageContext, at timestamp: DispatchTime?) -> Span {
-        TracedLockPrintlnSpan(operationName: operationName, startTimestamp: timestamp ?? .now(), context: context)
+    func startSpan(
+        named operationName: String,
+        context: BaggageContext,
+        ofKind kind: SpanKind,
+        at timestamp: DispatchTime?
+    ) -> Span {
+        TracedLockPrintlnSpan(
+            operationName: operationName,
+            startTimestamp: timestamp ?? .now(),
+            kind: kind,
+            context: context
+        )
     }
 
     func inject<Carrier, Injector>(_ baggage: BaggageContext, into carrier: inout Carrier, using injector: Injector)
@@ -71,6 +81,7 @@ private final class TracedLockPrintlnTracer: TracingInstrument {
 
     struct TracedLockPrintlnSpan: Span {
         let operationName: String
+        let kind: SpanKind
 
         var status: SpanStatus? {
             didSet {
@@ -100,11 +111,13 @@ private final class TracedLockPrintlnTracer: TracingInstrument {
         init(
             operationName: String,
             startTimestamp: DispatchTime,
+            kind: SpanKind,
             context baggage: BaggageContext
         ) {
             self.operationName = operationName
             self.startTimestamp = startTimestamp
             self.baggage = baggage
+            self.kind = kind
 
             print("  span [\(self.operationName): \(self.baggage[TaskIDKey.self] ?? "no-name")] @ \(self.startTimestamp): start")
         }

Tests/InstrumentationTests/TracingInstrumentTests.swift

@@ -34,8 +34,18 @@ final class TracingInstrumentTests: XCTestCase {
 final class JaegerTracer: TracingInstrument {
     private(set) var currentSpan: Span?
 
-    func startSpan(named operationName: String, context: BaggageContext, at timestamp: DispatchTime?) -> Span {
-        let span = OTSpan(operationName: operationName, startTimestamp: timestamp ?? .now(), context: context) { span in
+    func startSpan(
+        named operationName: String,
+        context: BaggageContext,
+        ofKind kind: SpanKind,
+        at timestamp: DispatchTime?
+    ) -> Span {
+        let span = OTSpan(
+            operationName: operationName,
+            startTimestamp: timestamp ?? .now(),
+            context: context,
+            kind: kind
+        ) { span in
             span.baggage.logger.info(#"Emitting span "\#(span.operationName)" to backend"#)
             span.baggage.logger.info("\(span.attributes)")
         }
@@ -86,6 +96,7 @@ extension JaegerTracer {
 
 struct OTSpan: Span {
     let operationName: String
+    let kind: SpanKind
 
     var status: SpanStatus? {
         didSet {
@@ -118,12 +129,14 @@ struct OTSpan: Span {
         operationName: String,
         startTimestamp: DispatchTime,
         context baggage: BaggageContext,
+        kind: SpanKind,
         onEnd: @escaping (Span) -> Void
     ) {
         self.operationName = operationName
         self.startTimestamp = startTimestamp
         self.baggage = baggage
         self.onEnd = onEnd
+        self.kind = kind
     }
 
     mutating func addEvent(_ event: SpanEvent) {