docs revamp on implementing tracers

Author: ktoso

Sources/Tracing/Docs.docc/Guides/ImplementATracer.md

@@ -25,7 +25,7 @@ In order to implement an instrument you need to implement the `Instrument` proto
 The two methods will be called by instrumented libraries/frameworks at asynchronous boundaries, giving you a chance to
 act on the provided information or to add additional information to be carried across these boundaries.
 
-> The [`ServiceContext` documentation](https://github.com/apple/swift-service-context) type is declared in the swift-service-context package.
+> The [`ServiceContext`](https://swiftpackageindex.com/apple/swift-service-context/documentation/servicecontextmodule) type is declared in the swift-service-context package.
 
 ### Creating a `Tracer`
 
@@ -36,7 +36,7 @@ When creating a tracer you will need to implement two types:
 
 > ``Span`` largely resembles span concept as defined  [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/api.md#span), however this package does not enforce certain rules specified in there - that is left up to a specific open telemetry tracer implementation.
 
-### Defining, injecting and extracting ServiceContext
+### Defining, injecting and extracting `ServiceContext`
 
 In order to be able to extract and inject values into the `ServiceContext` which is the value that is "carried around" across asynchronous contexts,
 we need to declare a `ServiceContextKey`. ServiceContext generally acts as a type-safe dictionary and declaring the keys this way allows us to perform lookups 
@@ -118,52 +118,76 @@ func handler(request: HTTPRequest) async throws {
 
 For your library/framework to be able to carry `ServiceContext` across asynchronous boundaries, it's crucial that you carry the context throughout your entire call chain in order to avoid dropping metadata.
 
-## Creating an instrument
+### Starting and ending spans
 
-Creating an instrument means adopting the `Instrument` protocol (or `Tracer` in case you develop a tracer).
-`Instrument` is part of the `Instrumentation` library & `Tracing` contains the `Tracer` protocol.
+The primary goal and user-facing API of a ``Tracer`` is to create spans.
 
-`Instrument` has two requirements:
+While you will need to implement all methods of the tracer protocol, the most important one is `startSpan`:
 
-1. A method to inject values inside a `ServiceContext` into a generic carrier (e.g. HTTP headers)
-2. A method to extract values from a generic carrier (e.g. HTTP headers) and store them in a `ServiceContext`
+```swift
+#if swift(>=5.7.0)
+extension MyTracer: Tracer {
+    func startSpan<Instant: TracerInstant>(
+        _ operationName: String,
+        context: @autoclosure () -> ServiceContext,
+        ofKind kind: SpanKind,
+        at instant: @autoclosure () -> Instant,
+        function: String,
+        file fileID: String,
+        line: UInt
+    ) -> MySpan {
+        let span = MySpan(
+            operationName: operationName,
+            startTime: instant(),
+            context: context(),
+            kind: kind,
+            onEnd: self.onEndSpan
+        )
+        self.spans.append(span)
+        return span
+    }
+}
+#endif
+```
 
-The two methods will be called by instrumented libraries/frameworks at asynchronous boundaries, giving you a chance to
-act on the provided information or to add additional information to be carried across these boundaries.
+If you can require Swift 5.7 prefer doing so, and return the concrete ``Span`` type from the `startSpan` method. 
+This allows users who decide to use your tracer explicitly, and not via the global bootstrapped system to avoid 
+wrapping tracers in existentials which can be beneficial in some situations.
 
-> Check out the [`ServiceContext` documentation](https://github.com/apple/swift-service-context) for more information on
-how to retrieve values from the `ServiceContext` and how to set values on it.
+Next, eventually the user started span will be ended and the `Span/end()` method will be invoked:
 
-### Creating a `Tracer`
+```swift
+public struct MySpan: Tracing.Span {
+    // ... implement all protocol requirements of Span ... 
 
-When creating a tracer you need to create two types:
+    public func end<Instant: TracerInstant>(at instant: @autoclosure () -> Instant) {
+        // store the `endInstant`
+        self.tracer.emit(self)
+    }
+}
+```
 
-1. Your tracer conforming to `Tracer`
-2. A span class conforming to `Span`
+It is possible to implement a span as a struct or a class, but a ``Span`` **must exhibit reference type behavior**.
+In other words, adding an attribute to one reference of a span must be visible in other references to it. 
 
-> The `Span` conforms to the standard rules defined in [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/api.md#span), so if unsure about usage patterns, you can refer to this specification and examples referring to it.
+The ability to implement a span using a struct comes in handy when implementing a "Noop" (do nothing) span and avoids heap allocations. Normal spans though generally will be backed by `class` based storage and should flush themselfes to the owning tracer once the span has been ended.
 
-### Defining, injecting and extracting ServiceContext
+#### Detecting not-ended spans
 
-```swift
-import Tracing
+It is a programmer error to NOT `end()` a span (be it by using `withSpan` or calling `startSpan` paired with `Span.end()`),
+and a tracer MAY choose to detect and error or fatal error in such situations.
 
-private enum TraceIDKey: ServiceContextKey {
-  typealias Value = String
-}
+It is possible to detect when a span has not been properly ended if the span's storage `deinit` is executed,
+however `end()` has not been called on it explicitly, like this:
 
-extension ServiceContext {
-  var traceID: String? {
-    get {
-      return self[TraceIDKey.self]
-    }
-    set {
-      self[TraceIDKey.self] = newValue
+```swift
+struct MySpan: Tracing.Span { 
+    final class _Storage {
+        var endInstant: Instant? = nil
+        
+        deinit {
+            precondition(endInstant != nil, "Span [...] was not properly ended before it was deinitialized!")
+        }
     }
-  }
 }
-
-var context = ServiceContext.topLevel(logger: ...)
-context.context.traceID = "4bf92f3577b34da6a3ce929d0e0e4736"
-print(context.context.traceID ?? "new trace id")
-```
+```