monad-metrics: A convenient wrapper around EKG metrics

[ library, mit, web ] [ Propose Tags ]

A convenient wrapper for collecting application metrics. Please see the for more information.

[Skip to Readme]


Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,,,,,,,, (info)
Change log
Dependencies base (>=4.8 && <5), clock (>=0.3 && <0.9), ekg-core (>= && <0.2), exceptions (>=0.6 && <0.11), hashable (>=1.2 && <1.5), microlens (>=0.2 && <0.5), mtl (>=2 && <2.3), text (<1.3), transformers (>=0.3 && <0.6), unordered-containers (>=0.2 && <0.3) [details]
License MIT
Copyright 2018 Matt Parsons, 2017 Seller Labs, 2016 Taylor Fausak
Author Matthew Parsons
Revised Revision 1 made by parsonsmatt at 2022-05-17T12:38:29Z
Category Web
Home page
Source repo head: git clone
Uploaded by parsonsmatt at 2020-12-07T17:58:00Z
Distributions LTSHaskell:, NixOS:
Reverse Dependencies 3 direct, 1 indirect [details]
Downloads 5521 total (24 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2020-12-07 [all 1 reports]

Readme for monad-metrics-

[back to package description]


Build Status

This library defines a convenient wrapper and API for using EKG metrics in your application. It's heavily inspired by the metrics code that Taylor Fausak used in his Haskell application blunt.


This README is an executable literate Haskell file. If you have stack installed, then you can run the file with:


We'll need to start with the import/pragma boilerplate:

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE NoMonomorphismRestriction #-}

import qualified Control.Monad.Metrics as Metrics
import           Control.Monad.Metrics (Metrics, Resolution(..), MonadMetrics(..))
import           Control.Monad.Reader
import qualified System.Metrics        as EKG

The Control.Monad.Metrics module is designed to be imported qualified.


First, you need to initialize the Metrics data type. You can do so using initialize (to create a new EKG store) or initializeWith if you want to pass a preexisting store.

initializing :: Bool -> EKG.Store -> IO Metrics
initializing True store = Metrics.initializeWith store
initializing False _    = Metrics.initialize


The next step is to implement an instance of the class MonadMetrics for your monad transformer stack. This library has explicitly decided not to provide a concrete monad transformer to reduce the dependency footprint. Fortunately, it's pretty easy!

Suppose you've got the following stack:

type App = ReaderT Config IO

data Config = Config { configMetrics :: Metrics }

then you can easily get the required instance with:

instance MonadMetrics (ReaderT Config IO) where
    getMetrics = asks configMetrics

Now, you're off to the races! Let's record some metrics.

If you're after a really simple embedding, you can use run or run':

simple :: Int -> IO ()
simple i = $ do
        metrics <- Metrics.getMetrics
        Metrics.gauge "Simple" i
        forM_ [1..i] $ \_ -> do
            Metrics.increment "Count!"

gettingThere :: IO ()
gettingThere =' (\metrics -> Config metrics) $ do
        liftIO $ putStrLn "it accepts a constructor"


Once your application has the required instance, you can use EKG's metrics (counters, gauges, labels, distributions).

For detailed descriptions of the various metric types, see the corresponding EKG documentation:

Generally, the library provides "sane default" functions which accept the name of the metric to work with and the value to contribute to that metric.

w = Metrics.label "Foo" "Bar"
x = Metrics.counter "MetricName" 6
y = Metrics.distribution "Distribute" 3.4
z = Metrics.gauge "Gauge" 7

Generalized versions of these functions are available with an apostrophe. Labels accept any Showable value, while gauges and counters accept any Integral value.

a = Metrics.label' "List" [1,2,3]
b = Metrics.counter' "Count" (3 :: Integer)


You can time actions with timed, which has a resolution of seconds. You can use timed' which accepts a Resolution argument to provide a different scale.

timedProcess :: App Int
timedProcess = 
    Metrics.timed "summing1" $ do
        pure $! sum [1 .. 100000]

timedInMilliseconds :: App Int
timedInMilliseconds = 
    Metrics.timed' Microseconds "summing2" $ do
        pure $! sum [1..100]

A demonstration

main :: IO ()
main = do
    metrics <- Metrics.initialize
    flip runReaderT (Config metrics) $ do
        Metrics.label "ProgramName" "README"
        forM_ [1..10] $ \_ -> do
            Metrics.increment "up-to-ten"
        Metrics.timed' Nanoseconds "Whatever" $ do
            liftIO $ putStrLn "Hello World!"