Add LabelSanitizers (#32)

* Add s

* Add docs

* Update Sources/Prometheus/PrometheusMetrics.swift

Co-Authored-By: Konrad `ktoso` Malawski <konrad_malawski@apple.com>

* Remarks

Co-authored-by: Konrad `ktoso` Malawski <konrad_malawski@apple.com>

Author: MrLotU

Sources/Prometheus/Prometheus.swift

@@ -16,10 +16,15 @@ public class PrometheusClient {
     /// Lock used for thread safety
     private let lock: Lock
 
+    /// Sanitizers used to clean up label values provided through
+    /// swift-metrics.
+    public let sanitizer: LabelSanitizer
+    
     /// Create a PrometheusClient instance
-    public init() {
+    public init(labelSanitizer sanitizer: LabelSanitizer = PrometheusLabelSanitizer()) {
         self.metrics = []
         self.metricTypeMap = [:]
+        self.sanitizer = sanitizer
         self.lock = Lock()
     }
 

Sources/Prometheus/PrometheusMetrics.swift

@@ -86,6 +86,41 @@ private class MetricsSummary: TimerHandler {
     }
 }
 
+/// Used to sanitize labels into a format compatible with Prometheus label requirements.
+/// Useful when using `PrometheusMetrics` via `SwiftMetrics` with clients which do not necessarily know 
+/// about prometheus label formats, and may be using e.g. `.` or upper-case letters in labels (which Prometheus 
+/// does not allow).
+///
+///     let sanitizer: LabelSanitizer = ...
+///     let prometheusLabel = sanitizer.sanitize(nonPrometheusLabel)
+///
+/// By default `PrometheusLabelSanitizer` is used by `PrometheusClient`
+public protocol LabelSanitizer {
+    /// Sanitize the passed in label to a Prometheus accepted value.
+    ///
+    /// - parameters:
+    ///     - label: The created label that needs to be sanitized.
+    ///
+    /// - returns: A sanitized string that a Prometheus backend will accept.
+    func sanitize(_ label: String) -> String
+}
+
+/// Default implementation of `LabelSanitizer` that sanitizes any characters not
+/// allowed by Prometheus to an underscore (`_`).
+///
+/// See `https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels` for more info.
+public struct PrometheusLabelSanitizer: LabelSanitizer {
+    let allowedCharacters = "abcdefghijklmnopqrstuvwxyz0123456789_:"
+    
+    public init() { }
+
+    public func sanitize(_ label: String) -> String {
+        return String(label
+            .lowercased()
+            .map { (c: Character) -> Character in if allowedCharacters.contains(c) { return c }; return "_" })
+    }
+}
+
 extension PrometheusClient: MetricsFactory {
     public func destroyCounter(_ handler: CounterHandler) {
         guard let handler = handler as? MetricsCounter else { return }
@@ -107,6 +142,7 @@ extension PrometheusClient: MetricsFactory {
     }
 
     public func makeCounter(label: String, dimensions: [(String, String)]) -> CounterHandler {
+        let label = self.sanitizer.sanitize(label)
         let createHandler = { (counter: PromCounter) -> CounterHandler in
             return MetricsCounter(counter: counter, dimensions: dimensions)
         }
@@ -117,10 +153,12 @@ extension PrometheusClient: MetricsFactory {
     }
 
     public func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler {
+        let label = self.sanitizer.sanitize(label)
         return aggregate ? makeHistogram(label: label, dimensions: dimensions) : makeGauge(label: label, dimensions: dimensions)
     }
 
     private func makeGauge(label: String, dimensions: [(String, String)]) -> RecorderHandler {
+        let label = self.sanitizer.sanitize(label)
         let createHandler = { (gauge: PromGauge) -> RecorderHandler in
             return MetricsGauge(gauge: gauge, dimensions: dimensions)
         }
@@ -131,6 +169,7 @@ extension PrometheusClient: MetricsFactory {
     }
 
     private func makeHistogram(label: String, dimensions: [(String, String)]) -> RecorderHandler {
+        let label = self.sanitizer.sanitize(label)
         let createHandler = { (histogram: PromHistogram) -> RecorderHandler in
             return MetricsHistogram(histogram: histogram, dimensions: dimensions)
         }
@@ -141,6 +180,7 @@ extension PrometheusClient: MetricsFactory {
     }
 
     public func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler {
+        let label = self.sanitizer.sanitize(label)
         let createHandler = { (summary: PromSummary) -> TimerHandler in
             return MetricsSummary(summary: summary, dimensions: dimensions)
         }

Tests/SwiftPrometheusTests/SanitizerTests.swift

@@ -0,0 +1,52 @@
+import XCTest
+import NIO
+@testable import Prometheus
+@testable import CoreMetrics
+
+final class SanitizerTests: XCTestCase {
+    
+    var group: EventLoopGroup!
+    var eventLoop: EventLoop {
+        return group.next()
+    }
+    
+    override func setUp() {
+        self.group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+    }
+    
+    override func tearDown() {
+        try! self.group.syncShutdownGracefully()
+    }
+    
+    func testDefaultSanitizer() throws {
+        let sanitizer = PrometheusLabelSanitizer()
+        
+        XCTAssertEqual(sanitizer.sanitize("MyMetrics.RequestDuration"), "mymetrics_requestduration")
+        XCTAssertEqual(sanitizer.sanitize("My-Metrics.request-Duration"), "my_metrics_request_duration")
+    }
+    
+    func testCustomSanitizer() throws {
+        struct Sanitizer: LabelSanitizer {
+            func sanitize(_ label: String) -> String {
+                return String(label.reversed())
+            }
+        }
+        
+        let sanitizer = Sanitizer()
+        XCTAssertEqual(sanitizer.sanitize("MyMetrics.RequestDuration"), "noitaruDtseuqeR.scirteMyM")
+    }
+    
+    func testIntegratedSanitizer() throws {
+        let prom = PrometheusClient()
+        MetricsSystem.bootstrapInternal(prom)
+        
+        CoreMetrics.Counter(label: "Test.Counter").increment(by: 10)
+        
+        let promise = eventLoop.makePromise(of: String.self)
+        prom.collect(into: promise)
+        XCTAssertEqual(try! promise.futureResult.wait(), """
+        # TYPE test_counter counter
+        test_counter 10
+        """)
+    }
+}

Tests/SwiftPrometheusTests/XCTestManifests.swift

@@ -36,6 +36,17 @@ extension PrometheusMetricsTests {
     ]
 }
 
+extension SanitizerTests {
+    // DO NOT MODIFY: This is autogenerated, use:
+    //   `swift test --generate-linuxmain`
+    // to regenerate.
+    static let __allTests__SanitizerTests = [
+        ("testCustomSanitizer", testCustomSanitizer),
+        ("testDefaultSanitizer", testDefaultSanitizer),
+        ("testIntegratedSanitizer", testIntegratedSanitizer),
+    ]
+}
+
 extension SummaryTests {
     // DO NOT MODIFY: This is autogenerated, use:
     //   `swift test --generate-linuxmain`
@@ -63,6 +74,7 @@ public func __allTests() -> [XCTestCaseEntry] {
         testCase(GaugeTests.__allTests__GaugeTests),
         testCase(HistogramTests.__allTests__HistogramTests),
         testCase(PrometheusMetricsTests.__allTests__PrometheusMetricsTests),
+        testCase(SanitizerTests.__allTests__SanitizerTests),
         testCase(SummaryTests.__allTests__SummaryTests),
         testCase(SwiftPrometheusTests.__allTests__SwiftPrometheusTests),
     ]