Add reset function to Histogram

CHANGELOG.md

@@ -1,4 +1,12 @@
 
+## 2.4.0
+
+*   Add a `reset` function to the
+    `System.Metrics.Prometheus.Metric.Histogram` module, which zeroes the
+    bucket counts, sum, and observation count while leaving the bucket bounds
+    unchanged. This is useful for resetting metrics between tests.
+    [#55](https://github.com/bitnomial/prometheus/issues/55)
+
 ## 2.3.1
 
 *   Relax the `http-client-tls` upper bound to allow `0.4.*`.

prometheus.cabal

@@ -1,5 +1,5 @@
 name:                prometheus
-version:             2.3.1
+version:             2.4.0
 synopsis:            Prometheus Haskell Client
 homepage:            http://github.com/bitnomial/prometheus
 bug-reports:         http://github.com/bitnomial/prometheus/issues

src/System/Metrics/Prometheus/Metric/Histogram.hs

@@ -9,9 +9,10 @@
     observe,
     sample,
     observeAndSample,
+    reset,
 ) where
 
 import Control.Applicative ((<$>))
 import Control.Monad (void)
 import Data.Bool (bool)
 import Data.IORef (
@@ -71,3 +72,24 @@
 
 sample :: Histogram -> IO HistogramSample
 sample = readIORef . unHistogram
+
+
+-- | Reset the histogram back to its initial state: every bucket count, the
+-- sum, and the observation count return to 0. The bucket upper bounds are left
+-- unchanged.
+--
+-- This is /not/ part of the Prometheus client library specification, which
+-- only defines @observe@ for histograms. It is intended for resetting metrics
+-- between tests when they are defined as top-level values. On a live, scraped
+-- metric a reset looks like a counter reset (e.g. a process restart) to
+-- Prometheus, which its @rate@/@increase@ functions handle, so prefer
+-- 'observe' there and reserve 'reset' for test isolation.
+reset :: Histogram -> IO ()
+reset (Histogram ref) = atomicModifyIORef' ref $ \histData ->
+    ( histData
+        { histBuckets = 0 <$ histBuckets histData
+        , histSum = 0
+        , histCount = 0
+        }
+    , ()
+    )