monad-metrics-extensible 0.1.0.0 → 0.1.0.1

raw patch · 3 files changed

+79/−3 lines, 3 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• ChangeLog.md +7/−1
• README.md +70/−0
• monad-metrics-extensible.cabal +2/−2

@@ -1,3 +1,9 @@ # Changelog for monad-metrics-extensible -## Unreleased changes+## v. 0.1.0.1++A very brief documentation in README++## v. 0.1.0.0++Initial release: no documentation, no PV bounds, but at least looks like it works!

@@ -1,1 +1,71 @@ # 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.

@@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack ----- hash: bb9eb3e4722acb9d4fdca6657d73f6bd0989b7a3a4b7039ab5d09b4304702e73+-- hash: 79c192bfb089d6da408408ac335a54cc76caffb9f9520888b58754d4981712fe  name:           monad-metrics-extensible-version:        0.1.0.0+version:        0.1.0.1 synopsis:       An extensible and type-safe wrapper around EKG metrics description:    Please see the README on GitHub at <https://github.com/0xd34df00d/monad-metrics-extensible#readme> category:       Web