Consistent protocol naming for Instrument :party:

Author: ktoso

README.md

@@ -40,7 +40,7 @@ This project uses the context progagation type defined independently in:
     + [Extracting & injecting Baggage](#extracting--injecting-baggage)
     + [Tracing your library](#tracing-your-library)
 * In-Depth Guide for: **Instrument developers**
-    + [Creating an `InstrumentProtocol`](#instrument-developers--creating-an-instrument)
+    + [Creating an `Instrument`](#instrument-developers--creating-an-instrument)
     + [Creating a `Tracer`](#creating-a--tracer-)
 * [Contributing](#contributing)
 
@@ -119,7 +119,7 @@ To your main target, add a dependency on `Tracing` library and the instrument yo
 ),
 ```
 
-Then (in an application, libraries should _never_ invoke `bootstrap`), you will want to bootstrap the specific tracer you want to use in your application. A `Tracer` is a type of `InstrumentProtocol` and can be offered used to globally bootstrap the tracing system, like this:
+Then (in an application, libraries should _never_ invoke `bootstrap`), you will want to bootstrap the specific tracer you want to use in your application. A `Tracer` is a type of `Instrument` and can be offered used to globally bootstrap the tracing system, like this:
 
 
 ```swift
@@ -295,7 +295,7 @@ To your main target, add a dependency on the `Instrumentation library` and the i
 
 Instead of providing each instrumented library with a specific instrument explicitly, you *bootstrap* the
 `InstrumentationSystem` which acts as a singleton that libraries/frameworks access when calling out to the configured
-`InstrumentProtocol`:
+`Instrument`:
 
 ```swift
 InstrumentationSystem.bootstrap(FancyInstrument())
@@ -316,7 +316,7 @@ This is because tracing systems may attempt to emit metrics about their status e
 
 #### Bootstrapping multiple instruments using MultiplexInstrument
 
-It is important to note that `InstrumentationSystem.bootstrap(_: InstrumentProtocol)` must only be called once. In case you
+It is important to note that `InstrumentationSystem.bootstrap(_: Instrument)` must only be called once. In case you
 want to bootstrap the system to use multiple instruments, you group them in a `MultiplexInstrument` first, which you
 then pass along to the `bootstrap` method like this:
 
@@ -481,7 +481,7 @@ func get(url: String, context: LoggingContext) {
 }
 ```
 
-On the receiving side, an HTTP server should use the following `InstrumentProtocol` API to extract the HTTP headers of the given
+On the receiving side, an HTTP server should use the following `Instrument` API to extract the HTTP headers of the given
 `HTTPRequest` into:
 
 ```swift
@@ -538,10 +538,10 @@ func get(url: String, context: LoggingContext) {
 
 ## Instrument developers: Creating an instrument
 
-Creating an instrument means adopting the `InstrumentProtocol` protocol (or `Tracer` in case you develop a tracer).
-`InstrumentProtocol` is part of the `Instrumentation` library & `Tracing` contains the `Tracer` protocol.
+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.
 
-`InstrumentProtocol` has two requirements:
+`Instrument` has two requirements:
 
 1. A method to inject values inside a `LoggingContext` 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 `LoggingContext`

Sources/Instrumentation/Instrument.swift

@@ -50,9 +50,9 @@ public protocol Injector: _SwiftInstrumentationSendable {
 
 /// Conforming types are usually cross-cutting tools like tracers. They are agnostic of what specific `Carrier` is used
 /// to propagate metadata across boundaries, but instead just specify what values to use for which keys.
-public protocol InstrumentProtocol: _SwiftInstrumentationSendable {
+public protocol Instrument: _SwiftInstrumentationSendable {
     /// Extract values from a `Carrier` by using the given extractor and inject them into the given `Baggage`.
-    /// It's quite common for `InstrumentProtocol`s to come up with new values if they weren't passed along in the given `Carrier`.
+    /// It's quite common for `Instrument`s to come up with new values if they weren't passed along in the given `Carrier`.
     ///
     /// - Parameters:
     ///   - carrier: The `Carrier` that was used to propagate values across boundaries.

Sources/Instrumentation/InstrumentationSystem.swift

@@ -15,24 +15,24 @@
 import InstrumentationBaggage
 
 /// `InstrumentationSystem` is a global facility where the default cross-cutting tool can be configured.
-/// It is set up just once in a given program to select the desired ``InstrumentProtocol`` implementation.
+/// It is set up just once in a given program to select the desired ``Instrument`` implementation.
 ///
 /// # Bootstrap multiple Instruments
 /// If you need to use more that one cross-cutting tool you can do so by using ``MultiplexInstrument``.
 ///
-/// # Access the InstrumentProtocol
-/// ``instrument``: Returns whatever you passed to ``bootstrap(_:)`` as an ``InstrumentProtocol``.
+/// # Access the Instrument
+/// ``instrument``: Returns whatever you passed to ``bootstrap(_:)`` as an ``Instrument``.
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal Baggage
 public enum InstrumentationSystem {
     private static let lock = ReadWriteLock()
-    private static var _instrument: InstrumentProtocol = NoOpInstrument()
+    private static var _instrument: Instrument = NoOpInstrument()
     private static var isInitialized = false
 
-    /// Globally select the desired ``InstrumentProtocol`` implementation.
+    /// Globally select the desired ``Instrument`` implementation.
     ///
-    /// - Parameter instrument: The ``InstrumentProtocol`` you want to share globally within your system.
+    /// - Parameter instrument: The ``Instrument`` you want to share globally within your system.
     /// - Warning: Do not call this method more than once. This will lead to a crash.
-    public static func bootstrap(_ instrument: InstrumentProtocol) {
+    public static func bootstrap(_ instrument: Instrument) {
         self.lock.withWriterLock {
             precondition(
                 !self.isInitialized, """
@@ -48,24 +48,24 @@ public enum InstrumentationSystem {
     /// For testing scenarios one may want to set instruments multiple times, rather than the set-once semantics enforced by ``bootstrap(_:)``.
     ///
     /// - Parameter instrument: the instrument to boostrap the system with, if `nil` the ``NoOpInstrument`` is bootstrapped.
-    internal static func bootstrapInternal(_ instrument: InstrumentProtocol?) {
+    internal static func bootstrapInternal(_ instrument: Instrument?) {
         self.lock.withWriterLock {
             self._instrument = instrument ?? NoOpInstrument()
         }
     }
 
-    /// Returns the globally configured ``InstrumentProtocol``.
+    /// Returns the globally configured ``Instrument``.
     ///
-    /// Defaults to a no-op ``InstrumentProtocol`` if ``bootstrap(_:)`` wasn't called before.
-    public static var instrument: InstrumentProtocol {
+    /// Defaults to a no-op ``Instrument`` if ``bootstrap(_:)`` wasn't called before.
+    public static var instrument: Instrument {
         self.lock.withReaderLock { self._instrument }
     }
 }
 
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal Baggage
 extension InstrumentationSystem {
     /// :nodoc: INTERNAL API: Do Not Use
-    public static func _findInstrument(where predicate: (InstrumentProtocol) -> Bool) -> InstrumentProtocol? {
+    public static func _findInstrument(where predicate: (Instrument) -> Bool) -> Instrument? {
         self.lock.withReaderLock {
             if let multiplex = self._instrument as? MultiplexInstrument {
                 return multiplex.firstInstrument(where: predicate)

Sources/Instrumentation/MultiplexInstrument.swift

@@ -14,27 +14,27 @@
 
 import InstrumentationBaggage
 
-/// A pseudo-``InstrumentProtocol`` that may be used to instrument using multiple other ``InstrumentProtocol``s across a
+/// A pseudo-``Instrument`` that may be used to instrument using multiple other ``Instrument``s across a
 /// common `Baggage`.
 public struct MultiplexInstrument {
-    private var instruments: [InstrumentProtocol]
+    private var instruments: [Instrument]
 
     /// Create a ``MultiplexInstrument``.
     ///
-    /// - Parameter instruments: An array of ``InstrumentProtocol``s, each of which will be used to ``InstrumentProtocol/inject(_:into:using:)`` or ``InstrumentProtocol/extract(_:into:using:)``
+    /// - Parameter instruments: An array of ``Instrument``s, each of which will be used to ``Instrument/inject(_:into:using:)`` or ``Instrument/extract(_:into:using:)``
     /// through the same `Baggage`.
-    public init(_ instruments: [InstrumentProtocol]) {
+    public init(_ instruments: [Instrument]) {
         self.instruments = instruments
     }
 }
 
 extension MultiplexInstrument {
-    func firstInstrument(where predicate: (InstrumentProtocol) -> Bool) -> InstrumentProtocol? {
+    func firstInstrument(where predicate: (Instrument) -> Bool) -> Instrument? {
         self.instruments.first(where: predicate)
     }
 }
 
-extension MultiplexInstrument: InstrumentProtocol {
+extension MultiplexInstrument: Instrument {
     public func inject<Carrier, Inject>(_ baggage: Baggage, into carrier: inout Carrier, using injector: Inject)
         where Inject: Injector, Carrier == Inject.Carrier
     {

Sources/Instrumentation/NoOpInstrument.swift

@@ -14,8 +14,8 @@
 
 import InstrumentationBaggage
 
-/// A "no op" implementation of an ``InstrumentProtocol``.
-public struct NoOpInstrument: InstrumentProtocol {
+/// A "no op" implementation of an ``Instrument``.
+public struct NoOpInstrument: Instrument {
     public init() {}
 
     public func inject<Carrier, Inject>(_ baggage: Baggage, into carrier: inout Carrier, using injector: Inject)

Sources/Tracing/Docs.docc/InDepthGuide.md

@@ -8,7 +8,7 @@ When instrumenting server applications there are typically three parties involve
 
 1. **Application developers** create server-side applications
 2. **Library/Framework developers** provide building blocks to create these applications
-3. **InstrumentProtocol developers** provide tools to collect distributed metadata about your application
+3. **Instrument developers** provide tools to collect distributed metadata about your application
 
 For applications to be instrumented correctly these three parts have to play along nicely.
 
@@ -42,7 +42,7 @@ To your main target, add a dependency on the `Instrumentation library` and the i
 
 Instead of providing each instrumented library with a specific instrument explicitly, you *bootstrap* the
 `InstrumentationSystem` which acts as a singleton that libraries/frameworks access when calling out to the configured
-`InstrumentProtocol`:
+`Instrument`:
 
 ```swift
 InstrumentationSystem.bootstrap(FancyInstrument())
@@ -63,7 +63,7 @@ This is because tracing systems may attempt to emit metrics about their status e
 
 #### Bootstrapping multiple instruments using MultiplexInstrument
 
-It is important to note that `InstrumentationSystem.bootstrap(_: InstrumentProtocol)` must only be called once. In case you
+It is important to note that `InstrumentationSystem.bootstrap(_: Instrument)` must only be called once. In case you
 want to bootstrap the system to use multiple instruments, you group them in a `MultiplexInstrument` first, which you
 then pass along to the `bootstrap` method like this:
 
@@ -225,7 +225,7 @@ func get(url: String, context: LoggingContext) {
 }
 ```
 
-On the receiving side, an HTTP server should use the following `InstrumentProtocol` API to extract the HTTP headers of the given
+On the receiving side, an HTTP server should use the following `Instrument` API to extract the HTTP headers of the given
 `HTTPRequest` into:
 
 ```swift
@@ -280,12 +280,12 @@ func get(url: String, context: LoggingContext) {
 > In the above example we used the semantic `http.method` attribute that gets exposed via the
 `TracingOpenTelemetrySupport` library.
 
-## InstrumentProtocol developers: Creating an instrument
+## Instrument developers: Creating an instrument
 
-Creating an instrument means adopting the `InstrumentProtocol` protocol (or ``Tracer`` in case you develop a tracer).
-`InstrumentProtocol` is part of the `Instrumentation` library & `Tracing` contains the ``Tracer`` protocol.
+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.
 
-`InstrumentProtocol` has two requirements:
+`Instrument` has two requirements:
 
 1. A method to inject values inside a `LoggingContext` 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 `LoggingContext`

Sources/Tracing/Docs.docc/index.md

@@ -62,7 +62,7 @@ To your main target, add a dependency on the `Tracing` library and the instrumen
 ),
 ```
 
-Then (in an application, libraries should _never_ invoke `bootstrap`), you will want to bootstrap the specific tracer you want to use in your application. A ``Tracer`` is a type of `InstrumentProtocol` and can be offered used to globally bootstrap the tracing system, like this:
+Then (in an application, libraries should _never_ invoke `bootstrap`), you will want to bootstrap the specific tracer you want to use in your application. A ``Tracer`` is a type of `Instrument` and can be offered used to globally bootstrap the tracing system, like this:
 
 
 ```swift

Sources/Tracing/Tracer.swift

@@ -81,7 +81,6 @@ public func startSpan<Clock: TracerClock>(
 ///
 /// - 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``
 ///   - 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
@@ -128,9 +127,9 @@ 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``
 ///   - 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``
 ///   - 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.
@@ -174,9 +173,9 @@ 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``
 ///   - 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``
 ///   - 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.
@@ -207,6 +206,28 @@ public func withSpan<T, Clock: TracerClock>(
     }
 }
 
+/// Start a new ``Span`` and automatically end when the `operation` completes,
+/// including recording the `error` in case the operation throws.
+///
+/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
+/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
+/// to pick up the task-local baggage is prevented. This can be useful when we know that
+/// we're about to start a top-level span, or if a span should be started from a different,
+/// stored away previously,
+///
+/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
+///   operation closure returning the span will be closed automatically.
+///
+/// - Parameters:
+///   - 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``.
+///   - 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.
+///   - operation: The operation that this span should be measuring
+/// - 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>(
     _ operationName: String,
@@ -231,6 +252,30 @@ public func withSpan<T>(
 }
 
 #if swift(>=5.7.0)
+
+/// Start a new ``Span`` and automatically end when the `operation` completes,
+/// including recording the `error` in case the operation throws.
+///
+/// The current task-local `Baggage` is picked up and provided to the underlying tracer.
+/// It is also possible to pass a specific `baggage` explicitly, in which case attempting
+/// to pick up the task-local baggage is prevented. This can be useful when we know that
+/// we're about to start a top-level span, or if a span should be started from a different,
+/// stored away previously,
+///
+/// - Warning: You MUST NOT ``Span/end()`` the span explicitly, because at the end of the `withSpan`
+///   operation closure returning the span will be closed automatically.
+///
+/// - 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``
+///   - 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.
+///   - operation: The operation that this span should be measuring
+/// - Returns: the value returned by `operation`
+/// - Throws: the error the `operation` has thrown (if any)
 public func withSpan<T>(
     _ operationName: String,
     baggage: @autoclosure () -> Baggage = .current ?? .topLevel,
@@ -271,9 +316,9 @@ 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``
 ///   - 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``
 ///   - 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.
@@ -320,7 +365,6 @@ public func withSpan<T, Clock: TracerClock>(
 ///   - 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``
 ///   - 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.

Sources/Tracing/TracerProtocol+Legacy.swift

@@ -17,7 +17,7 @@ import Dispatch
 @_exported import InstrumentationBaggage
 
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal Baggage
-public protocol LegacyTracer: InstrumentProtocol {
+public protocol LegacyTracer: Instrument {
     /// Start a new span returning an existential ``Span`` reference.
     ///
     /// - Warning: This method will be deprecated in favor of `Tracer/withSpan` as soon as this project is able to require Swift 5.7.