From 8fbad5d6732f01ebe2fed30a0b50330917766821 Mon Sep 17 00:00:00 2001 From: Jef Roosens Date: Mon, 26 Dec 2022 18:32:29 +0100 Subject: [PATCH] chore: added README --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d058d83 --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# 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.