# monad-metrics-extensible

## tl;dr

This library simplifies using [ekg](http://hackage.haskell.org/package/ekg)
in three ways:

* It allows specifying metrics as constructors of a user-defined GADT
  carrying both the metric name (to avoid typos) and the metric kind
  (a counter, a distribution and so on — to avoid code duplication).
  Multiple GADTs in the same appplication are supported (hence
  "extensible").
* It encapsulates managing all the necessary EKG objects on-demand via
  a monadic API.
* It allows defining new kinds of metrics in the user code
  (hence "extensible" one more time).
  You want a combined distribution + counter? No prob!

`import System.Metrics.Extensible` is your entry point of choice!

## A quick example

First we enable a few extensions and import some packages:
```haskell
{-# LANGUAGE DataKinds, GADTs, StandaloneDeriving #-}

import System.Metrics.Extensible
import System.Remote.Monitoring -- for ekg stuff
```

Then we define a type that represents the possible metrics in our
application:
```haskell
data SomeMetrics ty name where
  SomeCounter     :: SomeMetrics Counter "some_counter"
  AnotherCounter  :: SomeMetrics Counter "other_counter"
  SomeGauge       :: SomeMetrics Gauge   "some_gauge"
```
The string literals is what will be shown via ekg UI.

There is a couple of requirements:

* The type shall be of the kind `* -> Symbol -> *`.
* The first type argument (`Counter` and `Gauge` in the example above)
  shall be an instance of `TrackerLike`. All ekg counters are already
  an instance of this class.
* The type shall be comparable, hence we shall also do
```haskell
deriving instance Eq (SomeMetrics ty name)
deriving instance Ord (SomeMetrics ty name)
```

Then we can write our small program!

```haskell
main :: IO ()
main = do
  ekgServer <- forkServer "localhost" 8000
  withMetricsStore ekgServer $ \store -> flip runMetricsT store $ do
    track SomeCounter
    track SomeGauge 42
```

* `withMetricsStore` creates the metrics store that's managed by this
  library and runs an `IO` computation with that store.
* `runMetricsT` is what runs the monad transformer giving access to
  the metrics.
* `track` is the function that's responsible for updating the metrics.
  Its arguments depend on the specific metric that's being tracked:
  for instance, `Counter`s have no arguments, while `Gauge`s accept
  the corresponding new value.