GitHub - tomerd/swift-server-metrics-api-proposal (original) (raw)

SSWG Metrics api

Introduction

Almost all production server software needs to emit metrics information for observability. The SSWG aims to provide a number of packages that can be shared across the whole Swift on Server ecosystem so we need some amount of standardisation. Because it's unlikely that all parties can agree on one full metrics implementation, this proposal is attempting to establish a metrics API that can be implemented by various metrics backends which then post the metrics data to backends like prometheus, graphite, publish over statsd, write to disk, etc.

Motivation

As outlined above we should standardise on an API that if well adopted would allow application owners to mix and match libraries from different vendors with a consistent metrics solution.

Proposed solution

The proposed solution is to introduce the following types that encapsulate metrics data:

Counter: A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. For example, you can use a counter to represent the number of requests served, tasks completed, or errors.

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 Recorder with a sample size of 1 and that does not perform any aggregation.

Timer: A timer collects observations within a time window (usually things like request durations) 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.

timer.recordMilliseconds(100)

How would you use counter, recorder, gauge and timer in you application or library? Here is a contrived example for request processing code that emits metrics for: total request count per url, request size and duration and response size:

func processRequest(request: Request) -> Response {
  let requestCounter = Counter("request.count", ["url": request.url])
  let requestTimer = Timer("request.duration", ["url": request.url])
  let requestSizeRecorder = Recorder("request.size", ["url": request.url])
  let responseSizeRecorder = Recorder("response.size", ["url": request.url])

  requestCounter.increment()
  requestSizeRecorder.record(request.size)

  let start = Date()
  let response = ...
  requestTimer.record(Date().timeIntervalSince(start))
  responseSizeRecorder.record(response.size)
}

Detailed design

Implementing a metrics backend (e.g. prometheus client library)

As seen above, the constructors Counter, Timer, Recorder and Gauge provides a metric object. This raises the question of what metrics backend I will actually get when calling these constructors? The answer is that it's configurable per application. The application sets up the metrics backend it wishes the whole application to use. Libraries should never change the metrics implementation as that is something owned by the application. Configuring the metrics backend is straightforward:

MetricsSystem.bootstrap(MyFavouriteMetricsImplementation.init)

This instructs the MetricsSystem to install MyFavouriteMetricsImplementation as the metrics backend (MetricsFactory) to use. This should only be done once at the beginning of the program.

Given the above, an implementation of a metric backend needs to conform to protocol MetricsFactory:

public protocol MetricsFactory { func makeCounter(label: String, dimensions: [(String, String)]) -> CounterHandler func makeRecorder(label: String, dimensions: [(String, String)], aggregate: Bool) -> RecorderHandler func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler }

The MetricsFactory is responsible for instantiating the concrete metrics classes that capture the metrics and perform aggregation and calculation of various quantiles as needed.

Counter

public protocol CounterHandler: AnyObject { func increment<DataType: BinaryInteger>(_ value: DataType) }

Timer

public protocol TimerHandler: AnyObject { func recordNanoseconds(_ duration: Int64) }

Recorder

public protocol RecorderHandler: AnyObject { func record(_ value: Int64) func record(_ value: Double) }

Here is a full example of an in-memory implementation:

class SimpleMetricsLibrary: MetricsFactory { init() {}

func makeCounter(label: String, dimensions: [(String, String)]) -> CounterHandler {
    return ExampleCounter(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)
}

func makeTimer(label: String, dimensions: [(String, String)]) -> TimerHandler {
    return ExampleTimer(label, dimensions)
}

private class ExampleCounter: CounterHandler {
    init(_: String, _: [(String, String)]) {}

    let lock = NSLock()
    var value: Int64 = 0
    func increment(_ value: Int64) {
        self.lock.withLock {
            self.value += value
        }
    }

    func reset() {
        self.lock.withLock {
            self.value = 0
        }
    }
}

private class ExampleRecorder: RecorderHandler {
    init(_: String, _: [(String, String)]) {}

    private let lock = NSLock()
    var values = [(Int64, Double)]()
    func record(_ value: Int64) {
        self.record(Double(value))
    }

    func record(_ value: Double) {
        // TODO: sliding window
        lock.withLock {
            values.append((Date().nanoSince1970, value))
            self._count += 1
            self._sum += value
            self._min = Swift.min(self._min, value)
            self._max = Swift.max(self._max, value)
        }
    }

    var _sum: Double = 0
    var sum: Double {
        return self.lock.withLock { _sum }
    }

    private var _count: Int = 0
    var count: Int {
        return self.lock.withLock { _count }
    }

    private var _min: Double = 0
    var min: Double {
        return self.lock.withLock { _min }
    }

    private var _max: Double = 0
    var max: Double {
        return self.lock.withLock { _max }
    }
}

private class ExampleGauge: RecorderHandler {
    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 }
    }
}

private class ExampleTimer: ExampleRecorder, TimerHandler {
    func recordNanoseconds(_ duration: Int64) {
        super.record(duration)
    }
}

}

State

This is an early proposal so there are still plenty of things to decide and tweak and I'd invite everybody to participate.

Feedback Wishes

Feedback that would really be great is:

Feel free to post this as message on the SSWG forum and/or github issues in this repo.

Open Questions