-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Instrument applications with metrics and publish/push to Prometheus -- -- Prometheus is an open-source systems monitoring and alerting -- toolkit originally built at SoundCloud. Since its inception in 2012, -- many companies and organizations have adopted Prometheus, and the -- project has a very active developer and user community. It is now a -- standalone open source project and maintained independently of any -- company. To emphasize this and clarify the project's governance -- structure, Prometheus joined the Cloud Native Computing Foundation in -- 2016 as the second hosted project after Kubernetes. -- -- This library provides a Haskell client to Prometheus. It supports: -- -- @package prometheus-effect @version 1.0.0 -- | Prometheus is an open-source systems monitoring and alerting -- toolkit originally built at SoundCloud. Since its inception in 2012, -- many companies and organizations have adopted Prometheus, and the -- project has a very active developer and user community. It is now a -- standalone open source project and maintained independently of any -- company. To emphasize this and clarify the project's governance -- structure, Prometheus joined the Cloud Native Computing Foundation in -- 2016 as the second hosted project after Kubernetes. -- -- This library provides a Haskell client to Prometheus. It supports: -- -- -- -- The library is intended to be easy to use, because instrumentation is -- already boring enough - the last thing you want is to be 5 pages deep -- in obscure GHC extensions just to bump a counter! -- -- Here's one example to demonstrate how you could use this library: -- -- 
--   {-# LANGUAGE OverloadedStrings #-}
--   {-# LANGUAGE RecordWildCards #-}
--   
--   import Control.Concurrent
--   import Control.Monad
--   import Network.HTTP.Types.Status
--   import Prometheus
--   import System.Random
--   import qualified Network.Wai as Wai
--   import qualified Network.Wai.Handler.Warp as Warp
--   
--   data Metrics = Metrics
--     { iterations :: Counter
--     , timePerLoop :: Histogram
--     }
--   
--   main :: IO ()
--   main = do
--     (metrics, registry) <- buildRegistry $ do
--       iterations <- register "iterations" "Total completed iterations" mempty counter
--       timePerLoop <- register "time_per_loop" "Distribution of time per loop" mempty (histogram ioDurationBuckets)
--       return Metrics{..}
--   
--     forkIO $ Warp.run 8000 $ publishRegistryMiddleware ["metrics"] registry $ \req mkRes ->
--       mkRes (Wai.responseLBS notFound404 mempty mempty)
--   
--     forever $ time (timePerLoop metrics) $ do
--       threadDelay =<< randomIO
--       incCounter (iterations metrics)
--
module Prometheus -- | Register a metric with a Registry. -- -- Throws: -- -- register :: (MonadState Registry m, MonadIO m) => MetricName -> MetricHelp -> HashMap Text Text -> Metric a -> m a -- | Failures encountered when attempting to register a metric. data RegistrationFailure -- | A metric with the given name has already been registered. MetricCollision :: MetricName -> RegistrationFailure -- | The name of the colliding metric. [collidingName] :: RegistrationFailure -> MetricName -- | The metric name specifies the general feature of a system that is -- measured (e.g. http_requests_total - the total number of HTTP -- requests received). It may contain ASCII letters and digits, as well -- as underscores and colons. It must match the regex -- [a-zA-Z_:][a-zA-Z0-9_:]*. -- -- Note that MetricName has a IsString instance. If you -- enable {-# LANGUAGE OverloadedStrings #-}, you can simply use -- string literals. -- -- See also, the best practice for metric and label naming. data MetricName -- | User readable help text describing what a given metric represents. data MetricHelp -- | Metric describes a specific type of metric, but in an -- un-registered state. Pass Metrics to registerMetric to -- construct the metric for operation. data Metric a -- | Append a dynamic label to a metric. A dynamic label is a label that -- can be assigned different values at runtime. The returned metric is a -- function from label value to a configured metric. The child metric -- inherits all of the parent metric's labels. -- -- As an example of where you might use dynamic labels, consider the -- metric http_responses_total, which counts HTTP responses. If -- you want to track the status code, you can add a dynamic label -- code: -- -- 
--   httpResponsesByCode <-
--     register "http_responses_total" "HTTP responses" mempty
--       (addLabel "code" counter)
--   
--   -- later
--   
--   okResponses <- httpResponsesByCode "200"
--   incCounter okResponses
--
addLabel :: Text -> Metric metric -> Metric (Text -> IO metric) -- | A Registry is used to build up the list of all known -- Metrics that will be reported to Prometheus. You add a -- Metric to the Registry with register. data Registry -- | Given a computation that registers metrics, assemble a final registry. -- -- This is really just runStateT, but with a name that has more -- meaning. buildRegistry :: StateT Registry m a -> m (a, Registry) -- | Build WAI middleware that responds to GET requests to -- path by streaming Prometheus metrics. This is the typical way -- to expose instrumentation, allowing Prometheus to collect metrics -- directly from the app by polling. publishRegistryMiddleware :: [Text] -> Registry -> Middleware -- | Fork a thread that collects information about the instrumentation -- process of this application itself. Specifically, the following -- metrics will be added: -- -- pushMetrics :: MonadIO m => Text -> StateT Registry IO (Registry -> m ThreadId) -- | A counter is a cumulative metric that represents a single numerical -- value that only ever goes up. A counter is typically used to count -- requests served, tasks completed, errors occurred, etc. Counters -- should not be used to expose current counts of items whose number can -- also go down, e.g. the number of currently running threads. Use gauges -- for this use case. data Counter -- | Create a new counter. counter :: Metric Counter -- | Increment a counter by 1. incCounter :: MonadIO m => Counter -> m () -- | Increment a counter by a particular amount. incCounterBy :: MonadIO m => Counter -> Double -> m () -- | Instrument some code that may throw exceptions by counting the amount -- of exceptions thrown. The exception will not be caught, only counted. countExceptions :: (MonadMask m, MonadIO m) => Counter -> m a -> m a -- | A gauge is a metric that represents a single numerical value that can -- arbitrarily go up and down. -- -- Gauges are typically used for measured values like temperatures or -- current memory usage, but also "counts" that can go up and down, like -- the number of running threads. data Gauge -- | Create a new gauge, initialising it at 0. gauge :: Metric Gauge -- | Increment a gauge by 1. incGauge :: MonadIO m => Gauge -> m () -- | Decrement a gauge by 1. decGauge :: MonadIO m => Gauge -> m () -- | Apply a function to move a gauge. adjustGauge :: MonadIO m => Gauge -> (Double -> Double) -> m () -- | Set a gauge to an exact value. setGauge :: MonadIO m => Gauge -> Double -> m () -- | A histogram samples observations (usually things like request -- durations or response sizes) and counts them in configurable buckets. -- It also provides a sum of all observed values. data Histogram -- | Create a new histogram that samples into a specific set of buckets. histogram :: Buckets -> Metric Histogram -- | The buckets (bins) that a Histrogram can sample to. data Buckets -- | linearBuckets start width numBuckets creates -- numBuckets buckets, each width wide, where the -- lowest bucket has an upper bound of start (assuming -- width is positive). linearBuckets :: Double -> Double -> Natural -> Buckets -- | exponentialBuckets start factor numBuckets creates -- numBuckets buckets, where the lowest bucket has an upper -- bound of start and each following bucket's upper bound is -- factor times the previous bucket's upper bound. exponentialBuckets :: Double -> Double -> Natural -> Buckets -- | Pre-defined buckets that are probably suitable for IO operations. -- Upper-bounds are: 1μs, 10μs, 100μs, 1ms, 10ms, 100ms, 200ms, 300ms, -- 400ms, 500ms, 600ms, 700ms, 800ms, 900ms, 1s, 2s, 4s, 8s, 16s. ioDurationBuckets :: Buckets -- | Construct Buckets from anything list-like containing bucket -- upper-bounds. -- -- The input list will be sorted, and does not need to be sorted before -- hand. mkBuckets :: Foldable f => f Double -> Buckets -- | Record an observation into the buckets of a histogram. observe :: MonadIO m => Double -> Histogram -> m () -- | Run a computation, recording how long it takes to a Histogram. time :: (MonadIO m, MonadMask m) => Histogram -> m a -> m a instance GHC.Show.Show Prometheus.RegistrationFailure instance GHC.Base.Monoid Prometheus.Registry instance GHC.Show.Show Prometheus.Sample instance GHC.Show.Show Prometheus.MetricHelp instance Data.String.IsString Prometheus.MetricHelp instance GHC.Show.Show Prometheus.MetricName instance Data.Hashable.Class.Hashable Prometheus.MetricName instance Data.String.IsString Prometheus.MetricName instance GHC.Classes.Eq Prometheus.MetricName instance GHC.Classes.Ord Prometheus.MetricName instance GHC.Exception.Exception Prometheus.RegistrationFailure instance GHC.Base.Monoid Prometheus.SumAndCount instance GHC.Base.Monoid Prometheus.Buckets module Prometheus.GHC -- | Register metrics that record internal GHC runtime metrics, and fork a -- new thread to periodically update those metrics. Returns the -- ThreadId of the monitoring thread. -- -- The following metrics will be registered: -- -- ghcStats :: (MonadState Registry m, MonadIO m) => m (IO ThreadId) module Network.Wai.Middleware.Prometheus -- | Build some very simple middleware that registers some HTTP related -- metrics: -- -- instrumentRequests :: (MonadState Registry m, MonadIO m) => m Middleware