### Motivation:
To allow for things like parallel testing, it'd be useful if we can
explicitly provide a MetricsFactory to the existing Counter/... types.
### Modifications:
Added a `factory: MetricsFactory` parameter to all the initializers of
Counter/... types, and kept the existing methods that continue to
default to `MetricsSystem.factory`.
### Result:
Adopters can use a custom MetricsFactory explicitly passed in at metric
creation time. Existing adopters are not affected, unless you opt in,
you continue to use the global factory.
# Motivation
This PR supersedes https://github.com/apple/swift-metrics/pull/135. The
goal is to make it easier to measure asynchronous code when using
`Metrics`.
# Modification
This PR does:
- Deprecate the current static method for measuring synchronous code
- Add a new instance method to measure synchronous code
- Add a new instance method to measure asynchronous code
Motivation:
It's consistant with support policy (see https://github.com/apple/swift-metrics/pull/141).
It matches what's being tested.
It will make future changes adopting new features easier.
Modifications:
Bump swift tools version to 5.8
Remove linux tests and test discovery flag which are not required.
Result:
Will not longer build using swift before 5.8 - older compilers will find older
versions of this library when resolving versions.
# Motivation
Most of the server ecosystem follows the supported Swift versions from `swift-nio`. This means supporting the latest 3 Swift releases.
# Modification
This PR drops support for all Swift versions before 5.8.
# Result
This makes maintaining this repository easier and allows us to clean up some no longer needed stuff.
Motivation:
`Duration` is available starting Swift 5.7, and we
should probably support it in our convinience API.
Modifications:
- Timer.record(_ duration: Duration) implementation
- A unit test case
- Generated Linux tests
motivation: expose increment and decrement public APIs
changes:
* add increment and decrement public API to Meter
* improve the implementation of AccumulatingMeter and TestMeter
* add tests for new APIs
* refactor/modernize other tests
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
motivation: adjust to swift 5.6
changes:
* define sendable shims for protocols and structs that may be used in async context
* refactor Gauge to include rather than inherit Recorder
* adjust tests
* add a test to make sure no warning are emitted
motivation: It is not currently possible to record floating point values via the swift-metrics API even if the metrics backend supports it.
modifications: Adds a `FloatingPointCounter` type to allow users to accumulate non-integral metrics backed by a `FloatingPointCounterHandler`. Introduces a default implementation for creating and destroying `FloatingPointCounterHandler`s for metric backends that do not natively support floating point counters. On such backends, `FloatingPointCounter` is backed by a `AccumulatingRoundingFloatingPointCounter` which accumulates floating point values internally and record increments to a wrapped `CounterHandler` after crossing integer boundaries.
result: Users can create `FloatingPointCounter`s to record floating point values and get enhanced behavior for backends that support floating point values.
Motivation:
I have a metrics backend where I need to store timer values in
microseconds. The "preferred display unit" models this exactly, but it
seems to have (inadvertently?) omitted the possibility to express
microseconds. Note that among the timer "report" methods there is
already a microseconds option.
Changes:
* change TimeUnit from enum to struct with static members to support non-api breaking future evolution
* add scaleFromNanoseconds to TimeUnit to make it easy to compute the values without switching over
* add tests
Co-authored-by: Chris Burrows <cburrows@gmail.com>
motivation: adjust format to xcode format
changes:
* update .swiftformat no-indent setting and run formatter
* update test generation script to match correct format
motivation: some metrics backend prefer to be given a hint about the preferred display unit (seconds, milliseconds, etc) to drive the ux
changes: add a `preferedUnit` to TimerHandler (and `TimeUnits`) to capture the prefer display unit
Motivation:
As discussed in Issue #28, there are a few preferred lightweight APIs for getting timestamps such as `DispatchTime` but those APIs return `UInt64` types, which need to be handled for overflow.
Modifications:
Added a generic `BinaryInteger` overload method for `recordNanoseconds` that guards against accidental overflows from `UInt64` to `Int64`
Result:
Users now have access to a new method to record nanosecond measurements with `Timer` that guards against overflows.
Motivation:
`Timer.record*` methods are generic to cover all cases of `BinaryInteger` values and converts the passed value into `Int64` before doing time unit conversions and overflow checks.
Modifications:
All methods that accept `BinaryInteger` types and converts to `Int64` now guards against values higher than `Int64.max`
Result:
Users can reliably use the `Timer.record*` APIs with `BinaryInteger` types without concern for unknowing fatal errors.
motivation: highlight the need to address overflow in metric objects that are integer based
changes:
* add section in the readme about addressing woverflow
* fix timer's unit conversion to address potential overflow
motivation: allow middleware libraries better control of metric object lifecycle to reduce potential memory footprint when using metrics libraries that use some kind of registry or cache (eg polling backends)
changes:
* Introduce metric.destroy() to enable lifecycle management
* Add destroy functions to example impl in readme
motivation: use consistent formatting
changes: update generate_linux_tests to match the formatting rules we use: `swiftformat --self insert --patternlet inline --stripunusedargs unnamed-only --comments ignore`
* rename Counter::increment "value" parameter to "by"
motivation: nicer API signature
changes: rename Counter::increment and CounterHandler::increment "value" parameter to "by"
* prepare to release
motivation: the sswg voted to adopt the API. this is to prepare to a release
changes:
* rewrite readme
* add API docs
* add utilitiy scripts and docker setup for CI
* adjust linux tests
motivation: it's very beneficial for the protocols to use functions with concrete types because then there's no need for specialisation. At compile time, the compiler can often not know what concrete type will be used so it needs to create a 'generic at runtime' version of the function. If however all functions on the protocol do not use generics, there's no need for a 'generic at runtime' version of the function
changes:
* change CounterHandler::increment to take Int64 instead of <DataType: BinaryInteger>
* change RecorderHandler::record to take Int64 and Double instead of <DataType: BinaryInteger> and <DataType: BinaryFloatingPoint>
* adjust example and test implementation
* adjust docs
motivation: address feedback from community, prepare for moving api to official repo
changes:
* add reset method to counter
* do not force the user facing metric object to implement the mteric handler protocol. this was done for convinience and confuses matters
* adjust tests
* fix a few typos
motivation: after much discussion around logging API, we settled on a different API style, primairly the fact that we will use initializers instead of factories
changes:
* introduce intermediate classes for Counter, Timer and Recorder which are designed to replace the Metrics.makeCounter, Metrics.makeTimer and Metrics.makeRecorder APIs and wrap corresponding CounterHandler, TimerHandler and ReorderHandler coming from the metrics implmentation
* rename Metrics to MetricsSystem
* rename MetricsHandler -> MetricsFactory
* remove Metrics.withCounter, Metrics.withTimer and Metrics.withRecorder syntactic sugar
* rename Metrics.timed with Timer.measure
* make sure metrics system can only be initialized/bootstrapped once per process
* adjust and add tests
* add a bit of docs on key APIs
Honza Dvorsky
Franz Busch
Rick Newton-Rogers
Gustavo Cairo
Peter Adams
hamzahrmalik
Franz Busch
Natik Gadzhi
tomer doron
hamzahrmalik
Fabian Fett
Gustavo Cairo
Rauhul Varma
Moritz Lang
Konrad `ktoso` Malawski
Christian Priebe
tomer doron
Jari (LotU)
Nathan Harris
Nathan Harris
Konrad `ktoso` Malawski