Instrumentation by Composition

Summary

Instruments is a Go library for collecting application metrics over discrete time intervals, including request rates, latencies, data-structure sizes, and event durations. It supplies Counter, Rate, Reservoir, Gauge, Derive, and Timer instruments; values represent only the latest time-window and are read through a single-reader Snapshot operation. Composition is central: instruments implement either Discrete, returning one int64, or Sample, returning a slice, so custom instruments can wrap existing ones; the example embeds a Reservoir in an http.Handler to record upload request sizes. Derived instruments build on this model, with Derive using Rate and Timer using Reservoir, while Quantile, Mean, and reporting utilities process snapshots. An optional registry and logfmt reporter support periodic output, but applications can also send selected values to systems such as Graphite or use them for control signals.

Takeaways

1. 1

   Snapshots reflect observations from only the latest time-window, rather than prior windows, and instruments expect a single reader to request the current value.

2. 2

   Custom instruments can compose built-in instruments by implementing Discrete for one int64 value or Sample for a slice of int64 values.

3. 3

   Reporting is optional: snapshots can feed Quantile or Mean calculations, a logfmt reporter, external systems such as Graphite, or operational controls such as a circuit breaker.