Merge pull request #100 from slashmo/refactor/tracing-instrumentation

Move TracingInstrument & related types to separate library

Author: slashmo

Package.resolved

@@ -6,6 +6,7 @@ let package = Package(
     products: [
         .library(name: "BaggageLogging", targets: ["BaggageLogging"]),
         .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "TracingInstrumentation", targets: ["TracingInstrumentation"]),
         .library(name: "NIOInstrumentation", targets: ["NIOInstrumentation"])
     ],
     dependencies: [
@@ -52,6 +53,21 @@ let package = Package(
             ]
         ),
 
+        .target(
+            name: "TracingInstrumentation",
+            dependencies: [
+                "Instrumentation"
+            ]
+        ),
+        .testTarget(
+            name: "TracingInstrumentationTests",
+            dependencies: [
+                "Instrumentation",
+                "TracingInstrumentation",
+                "BaggageLogging"
+            ]
+        ),
+
         .target(
             name: "NIOInstrumentation",
             dependencies: [

Package.swift

@@ -67,14 +67,3 @@ public protocol Instrument {
         Injector.Carrier == Carrier
 }
 
-public struct NoOpInstrument: Instrument {
-    public func inject<Carrier, Injector>(_ baggage: BaggageContext, into carrier: inout Carrier, using injector: Injector)
-        where
-        Injector: InjectorProtocol,
-        Carrier == Injector.Carrier {}
-
-    public func extract<Carrier, Extractor>(_ carrier: Carrier, into baggage: inout BaggageContext, using extractor: Extractor)
-        where
-        Extractor: ExtractorProtocol,
-        Carrier == Extractor.Carrier {}
-}

Sources/Instrumentation/Instrument.swift

@@ -14,13 +14,27 @@
 import Baggage
 
 /// `InstrumentationSystem` is a global facility where the default cross-cutting tool can be configured.
-/// It is set up just once in a given program select the desired `Instrument` implementation.
+/// It is set up just once in a given program to select the desired `Instrument` implementation.
 ///
-/// - Note: If you need to use more that one cross-cutting tool you can do so by using `MultiplexInstrument`.
+/// # Bootstrap multiple Instruments
+/// 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`.
 public enum InstrumentationSystem {
     private static let lock = ReadWriteLock()
     private static var _instrument: Instrument = NoOpInstrument()
-    private static var _tracer: TracingInstrument?
     private static var isInitialized = false
 
     /// Globally select the desired `Instrument` implementation.
@@ -35,36 +49,48 @@ public enum InstrumentationSystem {
                 you need to use multiple instruments.
                 """
             )
-            if let tracer = instrument as? TracingInstrument {
-                self._tracer = tracer
-            }
             self._instrument = instrument
-
             self.isInitialized = true
         }
     }
 
     // for our testing we want to allow multiple bootstrapping
     internal static func bootstrapInternal(_ instrument: Instrument) {
         self.lock.withWriterLock {
-            if let tracer = instrument as? TracingInstrument {
-                self._tracer = tracer
-            }
             self._instrument = instrument
         }
     }
 
-    /// Returns the globally configured `Instrument`. Defaults to a no-op `Instrument` if `boostrap` wasn't called before.
+    /// Returns the globally configured `Instrument`.
+    ///
+    /// Defaults to a no-op `Instrument` if `boostrap` wasn't called before.
     public static var instrument: Instrument {
         self.lock.withReaderLock { self._instrument }
     }
 
-    // FIXME: smarter impl
-    public static var tracer: TracingInstrument {
+    /// 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 {
+        self._findInstrument(where: { $0 is I }) as? I
+    }
+
+}
+
+extension InstrumentationSystem {
+    /// :nodoc: INTERNAL API: Do Not Use
+    public static func _findInstrument(where predicate: (Instrument) -> Bool) -> Instrument? {
         self.lock.withReaderLock {
-            let tracer: TracingInstrument? = self._tracer
-            let res: TracingInstrument = tracer ?? NoOpTracingInstrument()
-            return res
+            if let multiplex = self._instrument as? MultiplexInstrument {
+                return multiplex.firstInstrument(where: predicate)
+            } else if predicate(self._instrument) {
+                return self._instrument
+            } else {
+                return nil
+            }
         }
     }
 }

Sources/Instrumentation/InstrumentationSystem.swift

@@ -27,6 +27,12 @@ public struct MultiplexInstrument {
     }
 }
 
+extension MultiplexInstrument {
+    func firstInstrument(where predicate: (Instrument) -> Bool) -> Instrument? {
+        self.instruments.first(where: predicate)
+    }
+}
+
 extension MultiplexInstrument: Instrument {
     public func inject<Carrier, Injector>(
         _ baggage: BaggageContext, into carrier: inout Carrier, using injector: Injector

Sources/Instrumentation/MultiplexInstrument.swift

@@ -0,0 +1,30 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020 Moritz Lang and the Swift Tracing project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import Baggage
+
+/// A "no op" implementation of an `Instrument`.
+public struct NoOpInstrument: Instrument {
+
+    public init() {}
+
+    public func inject<Carrier, Injector>(_ baggage: BaggageContext, into carrier: inout Carrier, using injector: Injector)
+        where
+        Injector: InjectorProtocol,
+        Carrier == Injector.Carrier {}
+
+    public func extract<Carrier, Extractor>(_ carrier: Carrier, into baggage: inout BaggageContext, using extractor: Extractor)
+        where
+        Extractor: ExtractorProtocol,
+        Carrier == Extractor.Carrier {}
+}

Sources/Instrumentation/NoOpInstrument.swift

@@ -0,0 +1,42 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Distributed Tracing open source project
+//
+// Copyright (c) 2020 Moritz Lang and the Swift Tracing project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import Baggage
+import Instrumentation
+
+
+extension InstrumentationSystem {
+
+    /// Get a `TracingInstrument` 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 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 tracingInstrument<T>(of instrumentType: T.Type) -> T? where T: TracingInstrument {
+        self._findInstrument(where: { $0 is T }) as? T
+    }
+
+    /// Returns the `TracingInstrument` bootstrapped as part of the `InstrumentationSystem`.
+    ///
+    /// If the system was bootstrapped with a `MultiplexInstrument` this function attempts to locate the _first_
+    /// tracing instrument as passed to the multiplex instrument. If none is found, a `NoOpTracingInstrument` is returned.
+    ///
+    /// - Returns: A `TracingInstrument` if the system was bootstrapped with one, and `NoOpTracingInstrument` otherwise.
+    public static var tracingInstrument: TracingInstrument {
+        (self._findInstrument(where: { $0 is TracingInstrument }) as? TracingInstrument) ?? NoOpTracingInstrument()
+    }
+}

Sources/TracingInstrumentation/InstrumentationSystem+Tracing.swift

@@ -12,6 +12,7 @@
 //===----------------------------------------------------------------------===//
 
 import Baggage
+import Instrumentation
 
 /// No operation TracingInstrument, used when no tracing is required.
 public struct NoOpTracingInstrument: TracingInstrument {