-remove tracer(of:) instrument(of:) (#16)

* minor span docs improvement

* -remove tracer(of:) instrument(of:)

* Minor docs improvement on bootstrapInternal

* Apply suggestions from code review

Co-authored-by: Moritz Lang <[email protected]>

Co-authored-by: Moritz Lang <[email protected]>

Author: ktoso

Sources/Instrumentation/InstrumentationSystem.swift

@@ -20,18 +20,7 @@ import Baggage
 /// If you need to use more that one cross-cutting tool you can do so by using `MultiplexInstrument`.
 ///
 /// # Access the Instrument
-/// There are two ways of getting the bootstrapped instrument.
-/// 1. `InstrumentationSystem.instrument`: Returns whatever you passed to `.bootstrap` as an `Instrument`.
-/// 2. `InstrumentationSystem.instrument(of: MyInstrument.self)`: Returns the bootstrapped `Instrument` if it's
-/// an instance of the given type or the first instance of `MyInstrument` if it's part of a `MultiplexInstrument`.
-///
-/// ## What getter to use
-/// - Default to using `InstrumentationSystem.instrument`
-/// - Use `InstrumentationSystem.instrument(of: MyInstrument.self)` only if you need to use specific `MyInstrument` APIs
-///
-/// Specific instrumentation libraries may also provide their own accessors as extensions, e.g. GreatInstrumentation could provide an
-/// `InstrumentationSystem.great` convenience accessor, so prefer using them if available. These accessors should call
-/// `.instrument(of: GreatInstrument.self)` under the hood to ensure they work when being used through a `MultiplexInstrument`.
+/// `InstrumentationSystem.instrument`: Returns whatever you passed to `.bootstrap` as an `Instrument`.
 public enum InstrumentationSystem {
     private static let lock = ReadWriteLock()
     private static var _instrument: Instrument = NoOpInstrument()
@@ -54,7 +43,9 @@ public enum InstrumentationSystem {
         }
     }
 
-    // for our testing we want to allow multiple bootstrapping
+    /// 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: Instrument?) {
         self.lock.withWriterLock {
             self._instrument = instrument ?? NoOpInstrument()
@@ -67,16 +58,6 @@ public enum InstrumentationSystem {
     public static var instrument: Instrument {
         return self.lock.withReaderLock { self._instrument }
     }
-
-    /// Get an `Instrument` instance of the given type.
-    ///
-    /// When using `MultiplexInstrument`, this returns the first instance of the given type stored in the `MultiplexInstrument`.
-    ///
-    /// - Parameter instrumentType: The type of `Instrument` you want to retrieve an instance for.
-    /// - Returns: An `Instrument` instance of the given type or `nil` if no `Instrument` of that type has been bootstrapped.
-    public static func instrument<I>(of instrumentType: I.Type) -> I? where I: Instrument {
-        return self._findInstrument(where: { $0 is I }) as? I
-    }
 }
 
 extension InstrumentationSystem {

Sources/Tracing/InstrumentationSystem+Tracing.swift

@@ -14,19 +14,6 @@
 @_exported import Instrumentation
 
 extension InstrumentationSystem {
-    /// Get a `Tracer` instance of the given type.
-    ///
-    /// When using `MultiplexInstrument`, this returns the first instance of the given type stored in the `MultiplexInstrument`.
-    ///
-    /// Usually tracing libraries will provide their own convenience getter, e.g. CoolTracing could provide `InstrumentationSystem.coolTracer`;
-    /// if available, prefer using those APIs rather than relying on this general function.
-    ///
-    /// - Parameter tracerType: The type of `Tracer` you want to retrieve an instance for.
-    /// - Returns: A `Tracer` instance of the given type or `nil` if no `Tracer` of that type has been bootstrapped.
-    public static func tracer<T>(of tracerType: T.Type) -> T? where T: Tracer {
-        return self._findInstrument(where: { $0 is T }) as? T
-    }
-
     /// Returns the `Tracer` bootstrapped as part of the `InstrumentationSystem`.
     ///
     /// If the system was bootstrapped with a `MultiplexInstrument` this function attempts to locate the _first_

Tests/InstrumentationTests/InstrumentationSystemTests.swift

@@ -15,6 +15,12 @@ import Baggage
 @testable import Instrumentation
 import XCTest
 
+extension InstrumentationSystem {
+    public static func _instrument<I>(of instrumentType: I.Type) -> I? where I: Instrument {
+        return self._findInstrument(where: { $0 is I }) as? I
+    }
+}
+
 final class InstrumentationSystemTests: XCTestCase {
     override class func tearDown() {
         super.tearDown()
@@ -26,18 +32,18 @@ final class InstrumentationSystemTests: XCTestCase {
         let instrument = FakeInstrument()
         let multiplexInstrument = MultiplexInstrument([tracer, instrument])
 
-        XCTAssertNil(InstrumentationSystem.instrument(of: FakeTracer.self))
-        XCTAssertNil(InstrumentationSystem.instrument(of: FakeInstrument.self))
+        XCTAssertNil(InstrumentationSystem._instrument(of: FakeTracer.self))
+        XCTAssertNil(InstrumentationSystem._instrument(of: FakeInstrument.self))
 
         InstrumentationSystem.bootstrapInternal(multiplexInstrument)
         XCTAssert(InstrumentationSystem.instrument is MultiplexInstrument)
-        XCTAssert(InstrumentationSystem.instrument(of: FakeTracer.self) === tracer)
-        XCTAssert(InstrumentationSystem.instrument(of: FakeInstrument.self) === instrument)
+        XCTAssert(InstrumentationSystem._instrument(of: FakeTracer.self) === tracer)
+        XCTAssert(InstrumentationSystem._instrument(of: FakeInstrument.self) === instrument)
 
         InstrumentationSystem.bootstrapInternal(tracer)
         XCTAssertFalse(InstrumentationSystem.instrument is MultiplexInstrument)
-        XCTAssert(InstrumentationSystem.instrument(of: FakeTracer.self) === tracer)
-        XCTAssertNil(InstrumentationSystem.instrument(of: FakeInstrument.self))
+        XCTAssert(InstrumentationSystem._instrument(of: FakeTracer.self) === tracer)
+        XCTAssertNil(InstrumentationSystem._instrument(of: FakeInstrument.self))
     }
 }
 

Tests/TracingTests/TracingInstrumentationSystemTests.swift

@@ -15,6 +15,16 @@
 import Tracing
 import XCTest
 
+extension InstrumentationSystem {
+    public static func _tracer<T>(of tracerType: T.Type) -> T? where T: Tracer {
+        return self._findInstrument(where: { $0 is T }) as? T
+    }
+
+    public static func _instrument<I>(of instrumentType: I.Type) -> I? where I: Instrument {
+        return self._findInstrument(where: { $0 is I }) as? I
+    }
+}
+
 final class TracingInstrumentationSystemTests: XCTestCase {
     override class func tearDown() {
         super.tearDown()
@@ -24,22 +34,22 @@ final class TracingInstrumentationSystemTests: XCTestCase {
     func testItProvidesAccessToATracer() {
         let tracer = TestTracer()
 
-        XCTAssertNil(InstrumentationSystem.tracer(of: TestTracer.self))
+        XCTAssertNil(InstrumentationSystem._tracer(of: TestTracer.self))
 
         InstrumentationSystem.bootstrapInternal(tracer)
         XCTAssertFalse(InstrumentationSystem.instrument is MultiplexInstrument)
-        XCTAssert(InstrumentationSystem.instrument(of: TestTracer.self) === tracer)
-        XCTAssertNil(InstrumentationSystem.instrument(of: NoOpInstrument.self))
+        XCTAssert(InstrumentationSystem._instrument(of: TestTracer.self) === tracer)
+        XCTAssertNil(InstrumentationSystem._instrument(of: NoOpInstrument.self))
 
-        XCTAssert(InstrumentationSystem.tracer(of: TestTracer.self) === tracer)
+        XCTAssert(InstrumentationSystem._tracer(of: TestTracer.self) === tracer)
         XCTAssert(InstrumentationSystem.tracer is TestTracer)
 
         let multiplexInstrument = MultiplexInstrument([tracer])
         InstrumentationSystem.bootstrapInternal(multiplexInstrument)
         XCTAssert(InstrumentationSystem.instrument is MultiplexInstrument)
-        XCTAssert(InstrumentationSystem.instrument(of: TestTracer.self) === tracer)
+        XCTAssert(InstrumentationSystem._instrument(of: TestTracer.self) === tracer)
 
-        XCTAssert(InstrumentationSystem.tracer(of: TestTracer.self) === tracer)
+        XCTAssert(InstrumentationSystem._tracer(of: TestTracer.self) === tracer)
         XCTAssert(InstrumentationSystem.tracer is TestTracer)
     }
 }