Control.Monad.Metrics

This module presents an easy interface that you can use to collect metrics about your application. It uses EKG from System.Metrics under the hood and is inspired by Taylor Fausak's blunt application.

This module is designed to be imported qualified.

The Type Class

class Monad m => MonadMetrics m where

A type can be an instance of MonadMetrics if it can provide a Metrics somehow. Commonly, this will be implemented as a ReaderT where some field in the environment is the Metrics data.

• Since v0.1.0.0

Minimal complete definition

getMetrics

Methods

getMetrics :: m Metrics

Instances

(MonadMetrics m, MonadTrans t, Monad (t m)) => MonadMetrics (t m)

Methods

getMetrics :: t m Metrics

Monad m => MonadMetrics (ReaderT * Metrics m)

Methods

getMetrics :: ReaderT * Metrics m Metrics

Initializing

This library tends to provide simple functions with plain names and generalized functions with apostrophes. When initializing the metrics, you can use initialize if you don't need fine control over the store, or you can use initializeWith if your application already has a store that it uses.

Likewise, we provide run for the simplest case, and run' for the more complex case where you have some larger type.

The most flexible way to use the library is to implement the MonadMetrics class.

initialize :: IO Metrics

Initializes a Metrics value, creating a new Store for it.

• Since v0.1.0.0

initializeWith :: Store -> IO Metrics

Initializes a Metrics value with the given Store.

• Since v0.1.0.0

run :: MonadIO m => ReaderT Metrics m a -> m a

Enhances the base monad with metrics. This works for very simple cases, where you don't have a Reader involved yet. If your stack already has a Reader, then you'll get some annoying type problems with this. Switch over to run', or alternatively, define your own MonadMetrics instance.

• Since v0.1.0.0

run' :: MonadIO m => (Metrics -> r) -> ReaderT r m a -> m a

Adds metric recording capabilities to the given action. The first parameter is a function which accepts a Metrics value and creates the final r value to be used in the action. This is useful when you have a preexisting ReaderT in your stack, and you want to enhance it with metrics.

data Config = Config { size :: Int, metrics' :: Metrics }

main = runWithMetrics (Config 10) $ do
    num <- asks size
    forM_ [1 .. size] _ -> Metrics.increment "foo"

• Since v0.1.0.0

Collecting Metrics

As with initialization, the library provides "common case" functions with a plain name and generalized functions with an apostrophe.

• increment, counter, counter'
• gauge, gauge'
• timed, timed'
• label, label'

Only distribution isn't generalized.

increment :: (MonadIO m, MonadMetrics m) => Text -> m ()

Increment the named counter by 1.

• Since v0.1.0.0

counter :: (MonadIO m, MonadMetrics m) => Text -> Int -> m ()

A type specialized version of counter' to avoid ambiguous type errors.

• Since v0.1.0.0

counter' :: (MonadIO m, MonadMetrics m, Integral int) => Text -> int -> m ()

Adds the value to the named Counter.

• Since v0.1.0.0

gauge :: (MonadIO m, MonadMetrics m) => Text -> Int -> m ()

A type specialized version of gauge' to avoid ambiguous types.

• Since v0.1.0.0

gauge' :: (MonadIO m, MonadMetrics m, Integral int) => Text -> int -> m ()

Set the value of the named Gauge.

• Since v0.1.0.0

distribution :: (MonadIO m, MonadMetrics m) => Text -> Double -> m ()

Add the value to the named Distribution.

• Since v0.1.0.0

timed :: (MonadIO m, MonadMetrics m, MonadMask m) => Text -> m a -> m a

Record the time of executing the given action in seconds. Defers to timed'.

• Since v0.1.0.0

timed' :: (MonadIO m, MonadMetrics m, MonadMask m) => Resolution -> Text -> m a -> m a

Record the time taken to perform the named action. The number is stored in a Distribution and is converted to the specified Resolution.

• Since v0.1.0.0

timedList :: (MonadIO m, MonadMetrics m, MonadMask m) => Resolution -> [Text] -> m a -> m a

Record the time taken to perform the action, under several names at once. The number is stored in a Distribution and is converted to the specified Resolution.

This is useful to store the same durations data sectioned by different criteria, e.g.:

timedList Seconds ["request.byUser." <> userName, "request.byType." <> requestType] $ do
    ...

So you will have "request.byUser.someuser" storing duration distribution for requests of user "someuser" of any type; and "request.byType.sometype" storing duration distribution for requests of type "sometype" from any user.

label :: (MonadIO m, MonadMetrics m) => Text -> Text -> m ()

Set the Label to the given Text value.

• Since v0.1.0.0

label' :: (MonadIO m, MonadMetrics m, Show a) => Text -> a -> m ()

Set the Label to the Shown value of whatever you pass in.

• Since v0.1.0.0

data Resolution

A type representing the resolution of time to use for the timed metric.

• Since v0.1.0.0

Constructors

Nanoseconds

Microseconds

Milliseconds

Seconds

Minutes

Hours

Days

Instances

Enum Resolution

Methods

succ :: Resolution -> Resolution

pred :: Resolution -> Resolution

toEnum :: Int -> Resolution

fromEnum :: Resolution -> Int

enumFrom :: Resolution -> [Resolution]

enumFromThen :: Resolution -> Resolution -> [Resolution]

enumFromTo :: Resolution -> Resolution -> [Resolution]

enumFromThenTo :: Resolution -> Resolution -> Resolution -> [Resolution]

Eq Resolution

Methods

(==) :: Resolution -> Resolution -> Bool

(/=) :: Resolution -> Resolution -> Bool

Ord Resolution

Methods

compare :: Resolution -> Resolution -> Ordering

(<) :: Resolution -> Resolution -> Bool

(<=) :: Resolution -> Resolution -> Bool

(>) :: Resolution -> Resolution -> Bool

(>=) :: Resolution -> Resolution -> Bool

max :: Resolution -> Resolution -> Resolution

min :: Resolution -> Resolution -> Resolution

Show Resolution

Methods

showsPrec :: Int -> Resolution -> ShowS

show :: Resolution -> String

showList :: [Resolution] -> ShowS

The Metrics Type

The Metric type contains an IORef to a HashMap from Text labels to the various counters, and a Store to register them with. If you must use the Metric value directly, then you are recommended to use the lenses provided for compatibility.

data Metrics

A container for metrics used by the MonadMetrics class.

• Since v0.1.0.0

Instances

Monad m => MonadMetrics (ReaderT * Metrics m)

Methods

getMetrics :: ReaderT * Metrics m Metrics

metricsCounters :: Lens' Metrics (IORef (HashMap Text Counter))

A lens into the Counters provided by the Metrics.

• Since v0.1.0.0

metricsGauges :: Lens' Metrics (IORef (HashMap Text Gauge))

A lens into the Gauges provided by the Metrics.

• Since v0.1.0.0

metricsLabels :: Lens' Metrics (IORef (HashMap Text Label))

A lens into the Labels provided by the Metrics.

• Since v0.1.0.0

metricsStore :: Lens' Metrics Store

A lens into the Store provided by the Metrics.

• Since v0.1.0.0