---
title: "Instrumentation by Composition"
description: "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."
---

# Instrumentation by Composition

[Heroku](https://yomu.fyi/company/heroku) · Timothée Peignier · Oct 23, 2014

**Type:** Explainer

## 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.

## Context

The library is intended to let applications collect metrics such as request counts, latency, data-structure sizes, and event durations over discrete time windows. The measurements can support operational signals, including circuit breakers and health checks, as well as reporting to external metrics systems.

## Approach / What changed

Instruments provides built-in metric types, Snapshot-based Discrete and Sample interfaces, and composition for custom instruments. A custom http.Handler example wraps a Reservoir to record upload request sizes. Optional registry, logfmt reporting, and statistical helpers support collecting and selecting values for output.

## Takeaways

- Snapshots reflect observations from only the latest time-window, rather than prior windows, and instruments expect a single reader to request the current value.
- Custom instruments can compose built-in instruments by implementing Discrete for one int64 value or Sample for a slice of int64 values.
- 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.

**Tags:** [Go](https://yomu.fyi/topic/go), [Monitoring](https://yomu.fyi/topic/monitoring)

- Source: [Heroku](https://www.heroku.com/blog/instrumentation-by-composition)
- Source URL: https://www.heroku.com/blog/instrumentation-by-composition
- Ingested by Yomu: 2026-09-09T14:23:37.519Z

[Read original post](https://www.heroku.com/blog/instrumentation-by-composition)