metrics/README.md

2.5 KiB

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.

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.