61 lines
2.5 KiB
Markdown
61 lines
2.5 KiB
Markdown
|
# V metrics
|
||
|
|
|
||
|
|
This library defines an interface for implementing a metrics collector & an
|
||
|
|
accompanying exporter interface for serializing the data in some way. A
|
||
|
|
thread-safe implementation of the collector interface is provided, which
|
||
|
|
utilizes a combination of atomic operations & `lock`/`rlock` to ensure the data
|
||
|
|
structure can be safely used concurrently. An implementation of a
|
||
|
|
Prometheus-compatible exporter is planned.
|
||
|
|
|
||
|
|
This library takes a lot of inspiration from the Rust
|
||
|
|
[metrics crate](https://docs.rs/metrics/latest/metrics/index.html).
|
||
|
|
|
||
|
|
Note that this library is still in development, and stuff might still change.
|
||
|
|
|
||
|
|
## Metric types
|
||
|
|
|
||
|
|
Just like the Rust crate, this library defines three types of metrics.
|
||
|
|
|
||
|
|
### Counter
|
||
|
|
|
||
|
|
A counter is a `u64` value that can only be monotonically incremented. One
|
||
|
|
example of such value is the amount of requests a web server has processed.
|
||
|
|
|
||
|
|
### Gauge
|
||
|
|
|
||
|
|
A gauge is an `f64` value describing a metric that can arbitrarily increase or
|
||
|
|
decrease over time. It can be freely added to, subtracted from or plainly set
|
||
|
|
to an absolute value. This could for example be used to track memory usage.
|
||
|
|
|
||
|
|
### Histogram
|
||
|
|
|
||
|
|
A histogram is an arbitrarily growing list of `f64` values. These values can
|
||
|
|
then be used to provide statistical analysis over time. The processing of these
|
||
|
|
values is left to the exporter to decide. The metrics collector solely stores
|
||
|
|
these values.
|
||
|
|
|
||
|
|
## Interfaces
|
||
|
|
|
||
|
|
As mentioned above, this library defines two interfaces. These can either be
|
||
|
|
used by using one of the provided implementations, or a user can freely
|
||
|
|
implement their own versions.
|
||
|
|
|
||
|
|
### `MetricsCollector`
|
||
|
|
|
||
|
|
A metrics collector is responsible for receiving and storing the types of
|
||
|
|
metrics. Two implementations are provided, namely `DefaultCollector` and
|
||
|
|
`NullCollector`. The former is the above-mentioned thread-safe implementation,
|
||
|
|
while the latter is an implementation that does absolutely nothing. The usecase
|
||
|
|
I have in mind for this seemingly useless version is when it's configurable
|
||
|
|
whether a piece of software should collect metrics or not. If the answer is no,
|
||
|
|
the developer could simply use a `NullCollector`, without having to change any
|
||
|
|
of the other code. All calls to the metrics collector will just get silently
|
||
|
|
ignored.
|
||
|
|
|
||
|
|
### `MetricsExporter`
|
||
|
|
|
||
|
|
A metrics exporter is responsible for converting the data stored in a metrics
|
||
|
|
collector into some format that can then be processed by some other means. The
|
||
|
|
classic example would be exporting to a Prometheus-compatible text format,
|
||
|
|
which could then be ingressed by Prometheus and processed further.
|