-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Haskell client library for http://prometheus.io.
--   
--   Haskell client library for <a>http://prometheus.io</a>.
@package prometheus-client
@version 1.0.0


-- | This module provides the basics for instrumenting Haskell executables
--   for use with the <a>Prometheus</a> monitoring system.
module Prometheus

-- | Registers a metric with the global metric registry.
registerIO :: MonadIO m => m (Metric s) -> m s

-- | Registers a metric with the global metric registry.
register :: MonadIO m => Metric s -> m s

-- | Registers a metric with the global metric registry.
--   
--   <b>IMPORTANT</b>: This method should only be used to register metrics
--   as top level symbols, it should not be run from other pure code.
--   
--   For example,
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    {-# NOINLINE c #-}
--    let c = unsafeRegisterIO $ counter (Info "my_counter" "An example metric")
--   :}
--   ...
--   </pre>
unsafeRegisterIO :: IO (Metric s) -> s

-- | Registers a metric with the global metric registry.
--   
--   <b>IMPORTANT</b>: This method should only be used to register metrics
--   as top level symbols, it should not be run from other pure code.
unsafeRegister :: Metric s -> s

-- | Removes all currently registered metrics from the registry.
unregisterAll :: MonadIO m => m ()

-- | Collect samples from all currently registered metrics. In typical use
--   cases there is no reason to use this function, instead you should use
--   <tt>exportMetricsAsText</tt> or a convenience library.
--   
--   This function is likely only of interest if you wish to export metrics
--   in a non-supported format for use with another monitoring service.
collectMetrics :: MonadIO m => m [SampleGroup]

-- | Export all registered metrics in the Prometheus 0.0.4 text exposition
--   format.
--   
--   For the full specification of the format, see the official Prometheus
--   <a>documentation</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :m +Data.ByteString
--   
--   &gt;&gt;&gt; myCounter &lt;- register $ counter (Info "my_counter" "Example counter")
--   
--   &gt;&gt;&gt; incCounter myCounter
--   
--   &gt;&gt;&gt; exportMetricsAsText &gt;&gt;= Data.ByteString.Lazy.putStr
--   # HELP my_counter Example counter
--   # TYPE my_counter counter
--   my_counter 1.0
--   </pre>
exportMetricsAsText :: MonadIO m => m ByteString
data Counter

-- | Creates a new counter metric with a given name and help string.
counter :: Info -> Metric Counter

-- | Increments the value of a counter metric by 1.
incCounter :: MonadMonitor m => Counter -> m ()

-- | Add the given value to the counter, if it is zero or more.
addCounter :: MonadMonitor m => Counter -> Double -> m Bool

-- | Add the given value to the counter. Panic if it is less than zero.
unsafeAddCounter :: MonadMonitor m => Counter -> Double -> m ()

-- | Add the duration of an IO action (in seconds) to a counter.
--   
--   If the IO action throws, no duration is added.
addDurationToCounter :: (MonadIO m, MonadMonitor m) => Counter -> m a -> m a

-- | Count the amount of times an action throws any synchronous exception.
--   
--   <pre>
--   &gt;&gt;&gt; exceptions &lt;- register $ counter (Info "exceptions_total" "Total amount of exceptions thrown")
--   
--   &gt;&gt;&gt; countExceptions exceptions $ return ()
--   
--   &gt;&gt;&gt; getCounter exceptions
--   0.0
--   
--   &gt;&gt;&gt; countExceptions exceptions (error "Oh no!") `catch` (\SomeException{} -&gt; return ())
--   
--   &gt;&gt;&gt; getCounter exceptions
--   1.0
--   </pre>
--   
--   It's important to note that this will count *all* synchronous
--   exceptions. If you want more granular counting of exceptions, you will
--   need to write custom code using <a>incCounter</a>.
countExceptions :: (MonadCatch m, MonadMonitor m) => Counter -> m a -> m a

-- | Retrieves the current value of a counter metric.
getCounter :: MonadIO m => Counter -> m Double
data Gauge

-- | Create a new gauge metric with a given name and help string.
gauge :: Info -> Metric Gauge

-- | Increments a gauge metric by 1.
incGauge :: MonadMonitor m => Gauge -> m ()

-- | Decrements a gauge metric by 1.
decGauge :: MonadMonitor m => Gauge -> m ()

-- | Adds a value to a gauge metric.
addGauge :: MonadMonitor m => Gauge -> Double -> m ()

-- | Subtracts a value from a gauge metric.
subGauge :: MonadMonitor m => Gauge -> Double -> m ()

-- | Sets a gauge metric to a specific value.
setGauge :: MonadMonitor m => Gauge -> Double -> m ()

-- | Sets a gauge metric to the duration in seconds of an IO action.
setGaugeToDuration :: (MonadIO m, MonadMonitor m) => Gauge -> m a -> m a

-- | Retrieves the current value of a gauge metric.
getGauge :: MonadIO m => Gauge -> m Double

-- | Interface shared by <tt>Summary</tt> and <tt>Histogram</tt>.
class Observer metric

-- | Observe that a particular floating point value has occurred. For
--   example, observe that this request took 0.23s.
observe :: (Observer metric, MonadMonitor m) => metric -> Double -> m ()

-- | Adds the duration in seconds of an IO action as an observation to an
--   observer metric.
--   
--   If the IO action throws an exception no duration will be observed.
observeDuration :: (Observer metric, MonadIO m, MonadMonitor m) => metric -> m a -> m a
data Summary

-- | A quantile is a pair of a quantile value and an associated acceptable
--   error value.
type Quantile = (Rational, Rational)

-- | Creates a new summary metric with a given name, help string, and a
--   list of quantiles. A reasonable set set of quantiles is provided by
--   <a>defaultQuantiles</a>.
summary :: Info -> [Quantile] -> Metric Summary
defaultQuantiles :: [Quantile]

-- | Retrieves a list of tuples containing a quantile and its associated
--   value.
getSummary :: MonadIO m => Summary -> m [(Rational, Double)]

-- | A histogram. Counts the number of observations that fall within the
--   specified buckets.
data Histogram

-- | Create a new <a>Histogram</a> metric with a given name, help string,
--   and list of buckets. Panics if the list of buckets is not strictly
--   increasing. A good default list of buckets is <a>defaultBuckets</a>.
--   You can also create buckets with <a>linearBuckets</a> or
--   <a>exponentialBuckets</a>.
histogram :: Info -> [Bucket] -> Metric Histogram

-- | The default Histogram buckets. These are tailored to measure the
--   response time (in seconds) of a network service. You will almost
--   certainly need to customize them for your particular use case.
defaultBuckets :: [Double]

-- | Create <tt>count</tt> buckets, where the lowest bucket has an upper
--   bound of <tt>start</tt> and each bucket's upper bound is
--   <tt>factor</tt> times the previous bucket's upper bound. Use this to
--   create buckets for <a>histogram</a>.
exponentialBuckets :: Bucket -> Double -> Int -> [Bucket]

-- | Create <tt>count</tt> buckets, each <tt>width</tt> wide, where the
--   lowest bucket has an upper bound of <tt>start</tt>. Use this to create
--   buckets for <a>histogram</a>.
linearBuckets :: Bucket -> Double -> Int -> [Bucket]

-- | Retries a map of upper bounds to counts of values observed that are
--   less-than-or-equal-to that upper bound, but greater than any other
--   upper bound in the map.
getHistogram :: MonadIO m => Histogram -> m (Map Bucket Int)
data Vector l m

-- | Creates a new vector of metrics given a label.
vector :: Label l => l -> Metric m -> Metric (Vector l m)

-- | Given a label, applies an operation to the corresponding metric in the
--   vector.
withLabel :: (Label label, MonadMonitor m) => Vector label metric -> label -> (metric -> IO ()) -> m ()

-- | Removes a label from a vector.
removeLabel :: (Label label, MonadMonitor m) => Vector label metric -> label -> m ()

-- | Removes all labels from a vector.
clearLabels :: (Label label, MonadMonitor m) => Vector label metric -> m ()
getVectorWith :: Vector label metric -> (metric -> IO a) -> IO [(label, a)]

-- | Label describes a class of types that can be used to as the label of a
--   vector.
class Ord l => Label l
labelPairs :: Label l => l -> l -> LabelPairs

-- | A list of tuples where the first value is the label and the second is
--   the value of that label.
type LabelPairs = [(Text, Text)]
type Label0 = ()
type Label1 = Text
type Label2 = (Text, Text)
type Label3 = (Text, Text, Text)
type Label4 = (Text, Text, Text, Text)
type Label5 = (Text, Text, Text, Text, Text)
type Label6 = (Text, Text, Text, Text, Text, Text)
type Label7 = (Text, Text, Text, Text, Text, Text, Text)
type Label8 = (Text, Text, Text, Text, Text, Text, Text, Text)
type Label9 = (Text, Text, Text, Text, Text, Text, Text, Text, Text)

-- | MonadMonitor describes a class of Monads that are capable of
--   performing asynchronous IO operations.
class Monad m => MonadMonitor m
doIO :: MonadMonitor m => IO () -> m ()
doIO :: (MonadMonitor m, MonadTrans t, MonadMonitor n, m ~ t n) => IO () -> m ()

-- | Monitor allows the use of Prometheus metrics in pure code. When using
--   Monitor, all of the metric operations will be collected and queued
--   into a single IO () value that can be run from impure code.
--   
--   Because all of the operations are performed asynchronously use of this
--   class is not recommended for use with metrics that are time sensitive
--   (e.g. for measuring latency).
type Monitor a = MonitorT Identity a

-- | Extract a value and the corresponding monitor update value from the
--   Monitor monad. For an example use see <a>Monitor</a>.
runMonitor :: Monitor a -> (a, IO ())

-- | MonitorT is the monad transformer analog of Monitor and allows for
--   monitoring pure monad transformer stacks.
data MonitorT m a

-- | Extract a value and the corresponding monitor update value from the
--   MonitorT monad transformer.
runMonitorT :: Monad m => MonitorT m a -> m (a, IO ())

-- | Meta data about a metric including its name and a help string that
--   describes the value that the metric is measuring.
data Info
Info :: Text -> Text -> Info
[metricName] :: Info -> Text
[metricHelp] :: Info -> Text

-- | A metric represents a single value that is being monitored. It is
--   comprised of a handle value and a collect method. The handle value is
--   typically a new type wrapped value that provides access to the
--   internal state of the metric. The collect method samples the current
--   value of the metric.
newtype Metric s
Metric :: IO (s, IO [SampleGroup]) -> Metric s

-- | <a>construct</a> is an <a>IO</a> action that creates a new instance of
--   a metric. For example, in a counter, this <a>IO</a> action would
--   create a mutable reference to maintain the state of the counter.
--   
--   <a>construct</a> returns two things:
--   
--   <ol>
--   <li>The state of the metric itself, which can be used to modify the
--   metric. A counter would return state pointing to the mutable
--   reference.</li>
--   <li>An <a>IO</a> action that samples the metric and returns
--   <a>SampleGroup</a>s. This is the data that will be stored by
--   Prometheus.</li>
--   </ol>
[construct] :: Metric s -> IO (s, IO [SampleGroup])

-- | A single value recorded at a moment in time. The sample type contains
--   the name of the sample, a list of labels and their values, and the
--   value encoded as a ByteString.
data Sample
Sample :: Text -> LabelPairs -> ByteString -> Sample

-- | A Sample group is a list of samples that is tagged with meta data
--   including the name, help string, and type of the sample.
data SampleGroup
SampleGroup :: Info -> SampleType -> [Sample] -> SampleGroup

-- | The type of a sample. This corresponds to the 5 types of metrics
--   supported by Prometheus.
data SampleType
CounterType :: SampleType
GaugeType :: SampleType
SummaryType :: SampleType
HistogramType :: SampleType
UntypedType :: SampleType