remove clock protocol, use autoclosure "now" instant (#120)

**Motivation:**

we don't need the clock protocol, but we do need the default clock to
provide an instant.

We also add time to recordError in this PR

Author: ktoso

Sources/Tracing/NoOpTracer.swift

@@ -23,13 +23,13 @@ public struct NoOpTracer: LegacyTracer {
 
     public init() {}
 
-    public func startAnySpan<Clock: TracerClock>(_ operationName: String,
-                                                 baggage: @autoclosure () -> Baggage,
-                                                 ofKind kind: SpanKind,
-                                                 clock: Clock,
-                                                 function: String,
-                                                 file fileID: String,
-                                                 line: UInt) -> any Span
+    public func startAnySpan<Instant: TracerInstant>(_ operationName: String,
+                                                     baggage: @autoclosure () -> Baggage,
+                                                     ofKind kind: SpanKind,
+                                                     at instant: @autoclosure () -> Instant,
+                                                     function: String,
+                                                     file fileID: String,
+                                                     line: UInt) -> any Span
     {
         NoOpSpan(baggage: baggage())
     }
@@ -73,7 +73,7 @@ public struct NoOpTracer: LegacyTracer {
 
         public func addEvent(_ event: SpanEvent) {}
 
-        public func recordError(_ error: Error, attributes: SpanAttributes) {}
+        public func recordError<Instant: TracerInstant>(_ error: Error, attributes: SpanAttributes, at instant: @autoclosure () -> Instant) {}
 
         public var attributes: SpanAttributes {
             get {
@@ -84,19 +84,19 @@ public struct NoOpTracer: LegacyTracer {
             }
         }
 
-        public func end<Clock: TracerClock>(clock: Clock) {
+        public func end<Instant: TracerInstant>(at instant: Instant) {
             // ignore
         }
     }
 }
 
 #if swift(>=5.7.0)
 extension NoOpTracer: Tracer {
-    public func startSpan<Clock: TracerClock>(
+    public func startSpan<Instant: TracerInstant>(
         _ operationName: String,
         baggage: @autoclosure () -> Baggage,
         ofKind kind: SpanKind,
-        clock: Clock,
+        at instant: @autoclosure () -> Instant,
         function: String,
         file fileID: String,
         line: UInt

Sources/Tracing/SpanProtocol.swift

@@ -65,9 +65,12 @@ public protocol Span: _SwiftTracingSendableSpan {
     /// Record an error of the given type described by the the given message.
     ///
     /// - Parameters:
-    ///   - error: The error to be recorded.
-    ///   - attributes: Additional attributes describing the error.
-    func recordError(_ error: Error, attributes: SpanAttributes)
+    ///   - error: The error to be recorded
+    ///   - attributes: Additional attributes describing the error
+    ///   - instant: the time instant at which the event occurred
+    func recordError<Instant: TracerInstant>(_ error: Error,
+                                             attributes: SpanAttributes,
+                                             at instant: @autoclosure () -> Instant)
 
     /// The attributes describing this `Span`.
     var attributes: SpanAttributes {
@@ -94,13 +97,22 @@ public protocol Span: _SwiftTracingSendableSpan {
     /// programming mistake to rely on this behavior.
     ///
     /// Parameters:
-    ///   - clock: The clock to use as time source for the start time of the ``Span``
+    ///   - instant: the time instant at which the span ended
     ///
     /// - SeeAlso: `Span.end()` which automatically uses the "current" time.
-    func end<Clock: TracerClock>(clock: Clock)
+    func end<Instant: TracerInstant>(at instant: Instant)
 }
 
 extension Span {
+    /// Record an error of the given type, at the current time, described by the the given message
+    ///
+    /// - Parameters:
+    ///   - error: The error to be recorded
+    ///   - attributes: Additional attributes describing the error
+    public func recordError(_ error: Error, attributes: SpanAttributes) {
+        self.recordError(error, attributes: attributes, at: DefaultTracerClock.now)
+    }
+
     /// End this `Span` at the current time.
     ///
     /// ### Rules about ending Spans
@@ -114,7 +126,7 @@ extension Span {
     /// - SeeAlso: ``end(clock:)`` which allows passing in a specific time, e.g. if the operation was ended and recorded somewhere and we need to post-factum record it.
     ///   Generally though prefer using the ``end()`` version of this API in user code and structure your system such that it can be called in the right place and time.
     public func end() {
-        self.end(clock: DefaultTracerClock())
+        self.end(at: DefaultTracerClock.now)
     }
 
     /// Adds a ``SpanLink`` between this `Span` and the given `Span`.
@@ -152,7 +164,7 @@ public struct SpanEvent: Equatable {
     /// It should be expressed as the number of nanoseconds since UNIX Epoch (January 1st 1970).
     public let nanosecondsSinceEpoch: UInt64
 
-    /// Representation of the timestamp this event occured as the number of milliseconds since UNIX Epoch (January 1st 1970).
+    /// Representation of the timestamp this event occurred as the number of milliseconds since UNIX Epoch (January 1st 1970).
     public var millisecondsSinceEpoch: UInt64 {
         self.nanosecondsSinceEpoch / 1_000_000
     }
@@ -161,14 +173,14 @@ public struct SpanEvent: Equatable {
     /// - Parameters:
     ///   - name: The human-readable name of this event.
     ///   - attributes: attributes describing this event. Defaults to no attributes.
-    ///   - clock: The clock to use as time source for the start time of the ``Span``
-    public init<Clock: TracerClock>(name: String,
-                                    clock: Clock,
-                                    attributes: SpanAttributes = [:])
+    ///   - instant: the time instant at which the event occurred
+    public init<Instant: TracerInstant>(name: String,
+                                        at instant: @autoclosure () -> Instant,
+                                        attributes: SpanAttributes = [:])
     {
         self.name = name
         self.attributes = attributes
-        self.nanosecondsSinceEpoch = clock.now.nanosecondsSinceEpoch
+        self.nanosecondsSinceEpoch = instant().nanosecondsSinceEpoch
     }
 
     public init(name: String,

Sources/Tracing/Tracer.swift

@@ -34,16 +34,16 @@ import Dispatch
 ///
 /// - Parameters:
 ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
-///   - clock: The clock to use as time source for the start time of the ``Span``
+///   - instant: the time instant at which the span started
 ///   - baggage: The `Baggage` providing information on where to start the new ``Span``.
 ///   - kind: The ``SpanKind`` of the new ``Span``.
 ///   - function: The function name in which the span was started
 ///   - fileID: The `fileID` where the span was started.
 ///   - line: The file line where the span was started.
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal Baggage
-public func startSpan<Clock: TracerClock>(
+public func startSpan<Instant: TracerInstant>(
     _ operationName: String,
-    clock: Clock,
+    at instant: @autoclosure () -> Instant,
     baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
     ofKind kind: SpanKind = .internal,
     function: String = #function,
@@ -54,7 +54,7 @@ public func startSpan<Clock: TracerClock>(
     // we try to not use the deprecated methods ourselves anyway
     InstrumentationSystem.legacyTracer.startAnySpan(
         operationName,
-        clock: clock,
+        at: instant(),
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -99,7 +99,7 @@ public func startSpan(
     // we try to not use the deprecated methods ourselves anyway
     InstrumentationSystem.legacyTracer.startAnySpan(
         operationName,
-        clock: DefaultTracerClock(),
+        at: DefaultTracerClock.now,
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -129,7 +129,7 @@ public func startSpan(
 ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
 ///   - baggage: The `Baggage` providing information on where to start the new ``Span``.
 ///   - kind: The ``SpanKind`` of the new ``Span``.
-///   - clock: The clock to use as time source for the start time of the ``Span``
+///   - instant: the time instant at which the span started
 ///   - function: The function name in which the span was started
 ///   - fileID: The `fileID` where the span was started.
 ///   - line: The file line where the span was started.
@@ -138,7 +138,7 @@ public func startSpan(
     _ operationName: String,
     baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
     ofKind kind: SpanKind = .internal,
-    clock: some TracerClock = DefaultTracerClock(),
+    at instant: @autoclosure () -> some TracerInstant = DefaultTracerClock.now,
     function: String = #function,
     file fileID: String = #fileID,
     line: UInt = #line
@@ -147,7 +147,7 @@ public func startSpan(
     // we try to not use the deprecated methods ourselves anyway
     InstrumentationSystem.tracer.startAnySpan(
         operationName,
-        clock: clock,
+        at: instant(),
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -173,7 +173,7 @@ public func startSpan(
 ///
 /// - Parameters:
 ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
-///   - clock: The clock to use as time source for the start time of the ``Span``
+///   - instant: the time instant at which the span started
 ///   - baggage: The `Baggage` providing information on where to start the new ``Span``.
 ///   - kind: The ``SpanKind`` of the new ``Span``.
 ///   - function: The function name in which the span was started
@@ -183,9 +183,9 @@ public func startSpan(
 /// - Returns: the value returned by `operation`
 /// - Throws: the error the `operation` has thrown (if any)
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal Baggage
-public func withSpan<T, Clock: TracerClock>(
+public func withSpan<T, Instant: TracerInstant>(
     _ operationName: String,
-    clock: Clock,
+    at instant: @autoclosure () -> Instant,
     baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
     ofKind kind: SpanKind = .internal,
     function: String = #function,
@@ -195,7 +195,7 @@ public func withSpan<T, Clock: TracerClock>(
 ) rethrows -> T {
     try InstrumentationSystem.legacyTracer.withAnySpan(
         operationName,
-        clock: DefaultTracerClock(),
+        at: DefaultTracerClock.now,
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -240,7 +240,7 @@ public func withSpan<T>(
 ) rethrows -> T {
     try InstrumentationSystem.legacyTracer.withAnySpan(
         operationName,
-        clock: DefaultTracerClock(),
+        at: DefaultTracerClock.now,
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -267,7 +267,7 @@ public func withSpan<T>(
 ///
 /// - Parameters:
 ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
-///   - clock: The clock to use as time source for the start time of the ``Span``
+///   - instant: the time instant at which the span started
 ///   - baggage: The `Baggage` providing information on where to start the new ``Span``.
 ///   - kind: The ``SpanKind`` of the new ``Span``.
 ///   - function: The function name in which the span was started
@@ -280,15 +280,15 @@ public func withSpan<T>(
     _ operationName: String,
     baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
     ofKind kind: SpanKind = .internal,
-    clock: some TracerClock = DefaultTracerClock(),
+    at instant: @autoclosure () -> some TracerInstant = DefaultTracerClock.now,
     function: String = #function,
     file fileID: String = #fileID,
     line: UInt = #line,
     _ operation: (any Span) throws -> T
 ) rethrows -> T {
     try InstrumentationSystem.legacyTracer.withAnySpan(
         operationName,
-        clock: clock,
+        at: instant(),
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -316,7 +316,7 @@ public func withSpan<T>(
 ///
 /// - Parameters:
 ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
-///   - clock: The clock to use as time source for the start time of the ``Span``
+///   - instant: the time instant at which the span started
 ///   - baggage: The `Baggage` providing information on where to start the new ``Span``.
 ///   - kind: The ``SpanKind`` of the new ``Span``.
 ///   - function: The function name in which the span was started
@@ -326,9 +326,9 @@ public func withSpan<T>(
 /// - Returns: the value returned by `operation`
 /// - Throws: the error the `operation` has thrown (if any)
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal Baggage
-public func withSpan<T, Clock: TracerClock>(
+public func withSpan<T, Instant: TracerInstant>(
     _ operationName: String,
-    clock: Clock,
+    at instant: @autoclosure () -> Instant,
     baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
     ofKind kind: SpanKind = .internal,
     function: String = #function,
@@ -338,7 +338,7 @@ public func withSpan<T, Clock: TracerClock>(
 ) async rethrows -> T {
     try await InstrumentationSystem.legacyTracer.withAnySpan(
         operationName,
-        clock: DefaultTracerClock(),
+        at: DefaultTracerClock.now,
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -383,7 +383,7 @@ public func withSpan<T>(
 ) async rethrows -> T {
     try await InstrumentationSystem.legacyTracer.withAnySpan(
         operationName,
-        clock: DefaultTracerClock(),
+        at: DefaultTracerClock.now,
         baggage: baggage(),
         ofKind: kind,
         function: function,
@@ -411,7 +411,7 @@ public func withSpan<T>(
 ///   - operationName: The name of the operation being traced. This may be a handler function, database call, ...
 ///   - baggage: The `Baggage` providing information on where to start the new ``Span``.
 ///   - kind: The ``SpanKind`` of the new ``Span``.
-///   - clock: The clock to use as time source for the start time of the ``Span``
+///   - instant: the time instant at which the span started
 ///   - function: The function name in which the span was started
 ///   - fileID: The `fileID` where the span was started.
 ///   - line: The file line where the span was started.
@@ -422,15 +422,15 @@ public func withSpan<T>(
     _ operationName: String,
     baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
     ofKind kind: SpanKind = .internal,
-    clock: some TracerClock = DefaultTracerClock(),
+    at instant: @autoclosure () -> some TracerInstant = DefaultTracerClock.now,
     function: String = #function,
     file fileID: String = #fileID,
     line: UInt = #line,
     _ operation: (any Span) async throws -> T
 ) async rethrows -> T {
     try await InstrumentationSystem.legacyTracer.withAnySpan(
         operationName,
-        clock: clock,
+        at: instant(),
         baggage: baggage(),
         ofKind: kind,
         function: function,