add "meter" - a new type of metric and metric handler (#123)

motivation: seperate gauge from recorder in a backwards compatible way

changes:
* add new meter and meter handler pair
* add increment and decrement to meter handler
* add default implementation based on recorder for backwards compatibility
* add and adjust tests

Author: tomerd

.swiftformat

@@ -10,4 +10,7 @@
 --stripunusedargs unnamed-only
 --ifdef no-indent
 
+# Configure the placement of an extension's access control keyword.
+--extensionacl on-declarations
+
 # rules

Package.swift

@@ -28,8 +28,7 @@ let package = Package(
     ],
     targets: [
         .target(
-            name: "CoreMetrics",
-            dependencies: []
+            name: "CoreMetrics"
         ),
         .target(
             name: "Metrics",

README.md

@@ -98,16 +98,22 @@ The API supports four metric types:
 counter.increment(by: 100)
 ```
 
-`Recorder`: A recorder collects observations within a time window (usually things like response sizes) and *can* provide aggregated information about the data sample, for example count, sum, min, max and various quantiles.
+ `Gauge`: A Gauge is a metric that represents a single numerical value that can arbitrarily go up and down. Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of active threads. Gauges are modeled as a `Recorder` with a sample size of 1 that does not perform any aggregation.
 
 ```swift
-recorder.record(100)
+gauge.record(100)
 ```
 
-`Gauge`: A Gauge is a metric that represents a single numerical value that can arbitrarily go up and down. Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of active threads. Gauges are modeled as a `Recorder` with a sample size of 1 that does not perform any aggregation.
+`Meter`: A Meter is similar to `Gauge` - a metric that represents a single numerical value that can arbitrarily go up and down. Meters are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of active threads. Unlike `Gauge`, `Meter` also supports atomic incerements and decerements.
 
 ```swift
-gauge.record(100)
+meter.record(100)
+```
+
+`Recorder`: A recorder collects observations within a time window (usually things like response sizes) and *can* provide aggregated information about the data sample, for example count, sum, min, max and various quantiles.
+
+```swift
+recorder.record(100)
 ```
 
 `Timer`: A timer collects observations within a time window (usually things like request duration) and provides aggregated information about the data sample, for example min, max and various quantiles. It is similar to a `Recorder` but specialized for values that represent durations.
@@ -120,7 +126,7 @@ timer.recordMilliseconds(100)
 
 Note: Unless you need to implement a custom metrics backend, everything in this section is likely not relevant, so please feel free to skip.
 
-As seen above, each constructor for `Counter`, `Timer`, `Recorder` and `Gauge` provides a metric object. This uncertainty obscures the selected metrics backend calling these constructors by design. _Each application_ can select and configure its desired backend. The application sets up the metrics backend it wishes to use. Configuring the metrics backend is straightforward:
+As seen above, each constructor for `Counter`, `Gauge`, `Meter`, `Recorder` and `Timer` provides a metric object. This uncertainty obscures the selected metrics backend calling these constructors by design. _Each application_ can select and configure its desired backend. The application sets up the metrics backend it wishes to use. Configuring the metrics backend is straightforward:
 
 ```swift
 let metricsImplementation = MyFavoriteMetricsImplementation()
@@ -134,10 +140,12 @@ Given the above, an implementation of a metric backend needs to conform to `prot
 ```swift
 public protocol MetricsFactory {
     func makeCounter(label: String, dimensions: [(String, String)]) -> CounterHandler
-    func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler
+    func makeMeter(label: String, dimensions: [(String, String)]) -> MeterHandler
+    func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler    
     func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler
 
     func destroyCounter(_ handler: CounterHandler)
+    func destroyMeter(_ handler: MeterHandler)
     func destroyRecorder(_ handler: RecorderHandler)
     func destroyTimer(_ handler: TimerHandler)
 }
@@ -154,11 +162,14 @@ public protocol CounterHandler: AnyObject {
 }
 ```
 
-**Timer**
+**Meter**
 
 ```swift
-public protocol TimerHandler: AnyObject {
-    func recordNanoseconds(_ duration: Int64)
+public protocol MeterHandler: AnyObject {
+    func set(_ value: Int64)
+    func set(_ value: Double)
+    func increment(by: Double)
+    func decrement(by: Double)
 }
 ```
 
@@ -171,9 +182,17 @@ public protocol RecorderHandler: AnyObject {
 }
 ```
 
+**Timer**
+
+```swift
+public protocol TimerHandler: AnyObject {
+    func recordNanoseconds(_ duration: Int64)
+}
+```
+
 #### Dealing with Overflows
 
-Implementaton of metric objects that deal with integers, like `Counter` and `Timer` should be careful with overflow. The expected behavior is to cap at `.max`, and never crash the program due to overflow . For example:
+Implementation of metric objects that deal with integers, like `Counter` and `Timer` should be careful with overflow. The expected behavior is to cap at `.max`, and never crash the program due to overflow . For example:
 
 ```swift
 class ExampleCounter: CounterHandler {
@@ -201,9 +220,12 @@ class SimpleMetricsLibrary: MetricsFactory {
         return ExampleCounter(label, dimensions)
     }
 
+    func makeMeter(label: String, dimensions: [(String, String)]) -> MeterHandler {
+        return ExampleMeter(label, dimensions)
+    }
+
     func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler {
-        let maker: (String, [(String, String)]) -> RecorderHandler = aggregate ? ExampleRecorder.init : ExampleGauge.init
-        return maker(label, dimensions)
+        return ExampleRecorder(label, dimensions, aggregate)
     }
 
     func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler {
@@ -212,7 +234,8 @@ class SimpleMetricsLibrary: MetricsFactory {
 
     // implementation is stateless, so nothing to do on destroy calls
     func destroyCounter(_ handler: CounterHandler) {}
-    func destroyRecorder(_ handler: RecorderHandler) {}
+    func destroyMeter(_ handler: TimerHandler) {}
+    func destroyRecorder(_ handler: RecorderHandler) {}    
     func destroyTimer(_ handler: TimerHandler) {}
 
     private class ExampleCounter: CounterHandler {
@@ -233,9 +256,32 @@ class SimpleMetricsLibrary: MetricsFactory {
         }
     }
 
-    private class ExampleRecorder: RecorderHandler {
+    private class ExampleMeter: MeterHandler {
         init(_: String, _: [(String, String)]) {}
 
+        let lock = NSLock()
+        var _value: Double = 0
+
+        func set(_ value: Int64) {
+            self.set(Double(value))
+        }
+
+        func set(_ value: Double) {
+            self.lock.withLock { _value = value }
+        }
+
+        func increment(by value: Double) {
+            self.lock.withLock { self._value += value }
+        }
+
+        func decrement(by value: Double) {
+            self.lock.withLock { self._value -= value }
+        }
+    }
+
+    private class ExampleRecorder: RecorderHandler {
+        init(_: String, _: [(String, String)], _: Bool) {}
+
         private let lock = NSLock()
         var values = [(Int64, Double)]()
         func record(_ value: Int64) {
@@ -274,23 +320,14 @@ class SimpleMetricsLibrary: MetricsFactory {
         }
     }
 
-    private class ExampleGauge: RecorderHandler {
+    private class ExampleTimer: TimerHandler {
         init(_: String, _: [(String, String)]) {}
 
         let lock = NSLock()
-        var _value: Double = 0
-        func record(_ value: Int64) {
-            self.record(Double(value))
-        }
-
-        func record(_ value: Double) {
-            self.lock.withLock { _value = value }
-        }
-    }
+        var _value: Int64 = 0
 
-    private class ExampleTimer: ExampleRecorder, TimerHandler {
         func recordNanoseconds(_ duration: Int64) {
-            super.record(duration)
+            self.lock.withLock { _value = duration }
         }
     }
 }

Sources/CoreMetrics/Docs.docc/index.md

@@ -27,7 +27,7 @@ and to your application/library target, add "Metrics" to your dependencies:
 .target(
     name: "BestExampleApp",
     dependencies: [
-        // ... 
+        // ...
         .product(name: "Metrics", package: "swift-metrics"),
     ]
 ),
@@ -90,7 +90,8 @@ This API was designed with the contributors to the Swift on Server community and
 
 ### Metric types
 
-- ``Gauge``
-- ``Recorder``
 - ``Counter``
+- ``Meter``
+- ``Recorder``
 - ``Timer``
+

Sources/CoreMetrics/Locks.swift

@@ -114,7 +114,7 @@ extension Lock {
     /// - Parameter body: The block to execute while holding the lock.
     /// - Returns: The value returned by the block.
     @inlinable
-    internal func withLock<T>(_ body: () throws -> T) rethrows -> T {
+    func withLock<T>(_ body: () throws -> T) rethrows -> T {
         self.lock()
         defer {
             self.unlock()
@@ -124,7 +124,7 @@ extension Lock {
 
     // specialise Void return (for performance)
     @inlinable
-    internal func withLockVoid(_ body: () throws -> Void) rethrows {
+    func withLockVoid(_ body: () throws -> Void) rethrows {
         try self.withLock(body)
     }
 }
@@ -234,7 +234,7 @@ extension ReadWriteLock {
     /// - Parameter body: The block to execute while holding the reader lock.
     /// - Returns: The value returned by the block.
     @inlinable
-    internal func withReaderLock<T>(_ body: () throws -> T) rethrows -> T {
+    func withReaderLock<T>(_ body: () throws -> T) rethrows -> T {
         self.lockRead()
         defer {
             self.unlock()
@@ -251,7 +251,7 @@ extension ReadWriteLock {
     /// - Parameter body: The block to execute while holding the writer lock.
     /// - Returns: The value returned by the block.
     @inlinable
-    internal func withWriterLock<T>(_ body: () throws -> T) rethrows -> T {
+    func withWriterLock<T>(_ body: () throws -> T) rethrows -> T {
         self.lockWrite()
         defer {
             self.unlock()
@@ -261,13 +261,13 @@ extension ReadWriteLock {
 
     // specialise Void return (for performance)
     @inlinable
-    internal func withReaderLockVoid(_ body: () throws -> Void) rethrows {
+    func withReaderLockVoid(_ body: () throws -> Void) rethrows {
         try self.withReaderLock(body)
     }
 
     // specialise Void return (for performance)
     @inlinable
-    internal func withWriterLockVoid(_ body: () throws -> Void) rethrows {
+    func withWriterLockVoid(_ body: () throws -> Void) rethrows {
         try self.withWriterLock(body)
     }
 }