+span implement withSpan() convenience (#13)

* +span implement withSpan() convenience

* Delete OSSignpostTracing.swift

Author: ktoso

Sources/Tracing/NoOpTracer.swift

@@ -17,6 +17,8 @@ import Dispatch
 
 /// No operation Tracer, used when no tracing is required.
 public struct NoOpTracer: Tracer {
+    public init() {}
+
     public func startSpan(
         _ operationName: String,
         baggage: Baggage,

Sources/Tracing/Tracer.swift

@@ -42,7 +42,7 @@ public protocol Tracer: Instrument {
 }
 
 extension Tracer {
-    /// Start a new `Span` with the given `Baggage` starting at `Timestamp.now()`.
+    /// Start a new `Span` with the given `Baggage` starting at `DispatchWallTime.now()`.
     ///
     /// - Parameters:
     ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
@@ -55,15 +55,17 @@ extension Tracer {
     ) -> Span {
         return self.startSpan(operationName, baggage: baggage, ofKind: kind, at: .now())
     }
+}
 
-    // ==== --------------------------------------------------------------------
-    // MARK: LoggingContext accepting
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: Span creation: with `LoggingContext`
 
-    /// Start a new `Span` with the given `Baggage` starting at `Timestamp.now()`.
+extension Tracer {
+    /// Start a new `Span` with the given `Baggage` starting at `DispatchWallTime.now()`.
     ///
     /// - Parameters:
     ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
-    ///   - context: Logging context containing a `Baggage` whichi may contain trace identifiers of a parent `Span`.
+    ///   - context: Logging context containing a `Baggage` which may contain trace identifiers of a parent `Span`.
     ///   - kind: The `SpanKind` of the `Span` to be created. Defaults to `.internal`.
     public func startSpan(
         _ operationName: String,
@@ -73,3 +75,62 @@ extension Tracer {
         return self.startSpan(operationName, baggage: context.baggage, ofKind: kind, at: .now())
     }
 }
+
+// ==== ----------------------------------------------------------------------------------------------------------------
+// MARK: Starting spans: `withSpan`
+
+extension Tracer {
+    /// Execute a specific task within a newly created `Span`.
+    ///
+    /// DO NOT `end()` the passed in span manually. It will be ended automatically when the `function` returns.
+    ///
+    /// - Parameters:
+    ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
+    ///   - context: Logging context containing a `Baggage` which may contain trace identifiers of a parent `Span`.
+    ///   - kind: The `SpanKind` of the `Span` to be created. Defaults to `.internal`.
+    ///   - function: function to wrap in a span start/end and execute immediately
+    /// - Returns: the value returned by `function`
+    /// - Throws: the error the `function` has thrown (if any)
+    public func withSpan<T>(
+        _ operationName: String,
+        context: LoggingContext,
+        ofKind kind: SpanKind = .internal,
+        _ function: (Span) throws -> T
+    ) rethrows -> T {
+        let span = self.startSpan(operationName, context: context, ofKind: kind)
+        do {
+            return try function(span)
+        } catch {
+            span.recordError(error)
+            span.end()
+            throw error // rethrow
+        }
+    }
+
+    /// Execute a specific task within a newly created `Span`.
+    ///
+    /// DO NOT `end()` the passed in span manually. It will be ended automatically when the `function` returns.
+    ///
+    /// - Parameters:
+    ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
+    ///   - baggage: Baggage potentially containing trace identifiers of a parent `Span`.
+    ///   - kind: The `SpanKind` of the `Span` to be created. Defaults to `.internal`.
+    ///   - function: function to wrap in a span start/end and execute immediately
+    /// - Returns: the value returned by `function`
+    /// - Throws: the error the `function` has thrown (if any)
+    public func withSpan<T>(
+        _ operationName: String,
+        baggage: Baggage,
+        ofKind kind: SpanKind = .internal,
+        _ function: (Span) throws -> T
+    ) rethrows -> T {
+        let span = self.startSpan(operationName, baggage: baggage, ofKind: kind)
+        do {
+            return try function(span)
+        } catch {
+            span.recordError(error)
+            span.end()
+            throw error // rethrow
+        }
+    }
+}

Tests/TracingTests/TracerTests+XCTest.swift

@@ -27,6 +27,8 @@ extension TracerTests {
       return [
                 ("testContextPropagation", testContextPropagation),
                 ("testContextPropagationWithNoOpSpan", testContextPropagationWithNoOpSpan),
+                ("testWithSpan_success", testWithSpan_success),
+                ("testWithSpan_throws", testWithSpan_throws),
            ]
    }
 }

Tests/TracingTests/TracerTests.swift

@@ -24,7 +24,10 @@ final class TracerTests: XCTestCase {
 
     func testContextPropagation() {
         let tracer = TestTracer()
-        InstrumentationSystem.bootstrap(tracer)
+        InstrumentationSystem.bootstrapInternal(tracer)
+        defer {
+            InstrumentationSystem.bootstrapInternal(NoOpTracer())
+        }
 
         let httpServer = FakeHTTPServer { context, _, client -> FakeHTTPResponse in
             client.performRequest(context, request: FakeHTTPRequest(path: "/test", headers: []))
@@ -52,8 +55,42 @@ final class TracerTests: XCTestCase {
         XCTAssertEqual(httpServer.client.baggages.count, 1)
         XCTAssertEqual(httpServer.client.baggages.first?.traceID, "test")
     }
+
+    func testWithSpan_success() {
+        let tracer = TestTracer()
+        InstrumentationSystem.bootstrapInternal(tracer)
+        defer {
+            InstrumentationSystem.bootstrapInternal(NoOpTracer())
+        }
+
+        let value = tracer.withSpan("hello", baggage: .topLevel) { _ in
+            "yes"
+        }
+
+        XCTAssertEqual(value, "yes")
+    }
+
+    func testWithSpan_throws() {
+        let tracer = TestTracer()
+        InstrumentationSystem.bootstrapInternal(tracer)
+        defer {
+            InstrumentationSystem.bootstrapInternal(NoOpTracer())
+        }
+
+        do {
+            _ = try tracer.withSpan("hello", baggage: .topLevel) { _ in
+                throw ExampleSpanError()
+            }
+        } catch {
+            XCTAssertEqual(error as? ExampleSpanError, ExampleSpanError())
+            return
+        }
+        XCTFail("Should have throw")
+    }
 }
 
+struct ExampleSpanError: Error, Equatable {}
+
 // MARK: - Fake HTTP Server
 
 typealias HTTPHeaders = [(String, String)]