This change adds a new trait -- `Builder` -- which defines a value that
can create new recorder instances.
As we have a need to generate owned recorders, in particular for
futures-based code, the `Builder` trait provides a way to do so without
any jankiness, such as the prior Clone-based approach.
As such, all exporters now expect a builder to be passed in, rather than
the recorder itself.
We've reworked upkeep a bit to avoid any datapoint loss during upkeep,
and to make it a bit easier to grok and follow along with. We also
added a better "gauntlet" test to atempt to hit with with multiple
writers and eke out any glaring issues, as well as a bench test for it.
Originally, metrics (and `hotmic` before it was converted) was based on
an event loop that centered around `mio`'s `Poll` interface with a
custom channel to read and write metrics to. That model required a
dedicated thread to run to poll for writes, and ingest them, managing
the internal data structures in turn.
Eventually, I rewrote that portion to be based on `crossbeam-channel`
but we still depended on a background thread to pop samples off the
channel and process them.
Instead, we've rewritten the core of metrics to be based purely on
atomics, with the caveat that we still do have a background thread.
Instead of a single channel that metrics are funneled into, each
underlying metric becomes a single-track codepath: each metric is backed
by an atomic structure which means we can pass handles to that storage
as far as the callers themselves, eliminating the need to funnel metrics
into the "core" where they all contend for processing.
Counters are gauges are now, effectively, wrapped atomic integers, which
means we can process over 100 million counter/gauge updates per core.
Histograms are based on a brand-new atomic "bucket" that allows for
fast, unbounded writes and the ability to snapshot at any time.
The end result is that we can process a mixed workload (counter, gauge,
and histogram) at sample rates of up to 30 million samples per second
per core, with p999 ingest latencies of in the low hundreds of
nanoseconds. Taking snapshots also now avoids stalling the event loop
and driving up tail latencies for ingest, and writers can proceed with
no interruption.
There is still a background thread that is part of quanta's new "recent"
time support, which allows a background thread to incrementally update a
shared global time, which can be accessed more quickly than grabbing the
time directly. For our purposes, only histograms need the time to
perform the window upkeep inherent to the sliding windows we use, and
the time they need can be far less precise than what quanta is capable
of. This background thread is spawned automatically when creating a
receiver, and drops when the receiver goes away. By default, it updates
20 times a second performing an operation which itself takes less than
100ns, so all in all, this background thread should be imperceptible,
performance-wise, on all systems*.
On top of all of this, we've embraced the natural pattern of defining
metrics individually at the variable/field level, and added supported
for proxy types, which can be acquired from a sink and embedded as
fields within your existing types, which lets you directly update
metrics with the ease of accessing a field in an object. Sinks still
have the ability to have metrics pushed directly into them, but this
just opens up more possibilities.
* - famous last words
We've added two new major types to the crate:
- AtomicBucket, which allows queue-style atomic writes with atomic
snapshots, powered by crossbeam-epoch
- StreamingIntegers, a scalar delta/zigzag/variable-byte integer
compression implementation
These types are a major part of reworking metrics to be event loop-less
and may be eventually be spun out into their own standalone crates, and
they have value outside of just metrics.
We've also really leveled up our documentation and benchmarks, and these
two types now have full benchmark suites to better demonstrate their
value and their performance on a given system.
We now expose all exporters and recorders via facade modules in the
metrics crate, called metrics::exporters and metrics::recorders,
respectively. This means that the metrics crate itself has these are
optional dependencies, which are included by the default set of
features, and so can be turned off by consumers.
To curtail the issue of cyclical dependencies, we've also introduced
three new traits: MetricsSnapshot, SnapshotProvider, and
AsyncSnapshotProvider.
These traits let us represent metrics::Controller and
metrics::data::snapshot::Snapshot in the exporter, allowing us to get
around the cyclical dependency but also expose more flexibility and
modularity.