-- 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 0.3.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 :: IO (Metric s) -> IO (Metric s)

-- | Registers a metric with the global metric registry.
register :: Metric s -> IO (Metric 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) -> Metric 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 -> Metric s

-- | Removes all currently registered metrics from the registry.
unregisterAll :: IO ()

-- | 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 :: IO [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;- registerIO $ counter (Info "my_counter" "Example counter")
--   
--   &gt;&gt;&gt; incCounter myCounter
--   
--   &gt;&gt;&gt; exportMetricsAsText &gt;&gt;= Data.ByteString.putStr
--   # HELP my_counter Example counter
--   # TYPE my_counter counter
--   my_counter 1.0
--   </pre>
exportMetricsAsText :: IO ByteString
data Counter

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

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

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

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

-- | Add the duration of an IO action (in seconds) to a counter.
addDurationToCounter :: IO a -> Metric Counter -> IO a

-- | Retrieves the current value of a counter metric.
getCounter :: Metric Counter -> IO Double
data Gauge

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

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

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

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

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

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

-- | Sets a gauge metric to the duration in seconds of an IO action.
setGaugeToDuration :: IO a -> Metric Gauge -> IO a

-- | Retrieves the current value of a gauge metric.
getGauge :: Metric Gauge -> IO 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) => Double -> Metric metric -> m ()

-- | Adds the duration in seconds of an IO action as an observation to an
--   observer metric.
observeDuration :: Observer metric => IO a -> Metric metric -> IO 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] -> IO (Metric Summary)
defaultQuantiles :: [Quantile]

-- | Retrieves a list of tuples containing a quantile and its associated
--   value.
getSummary :: Metric Summary -> IO [(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] -> IO (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 :: Metric Histogram -> IO (Map Bucket Int)
data Vector l m

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

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

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

-- | Removes all labels from a vector.
clearLabels :: (Label label, MonadMonitor m) => Metric (Vector label metric) -> m ()
getVectorWith :: (Metric metric -> IO a) -> Metric (Vector label metric) -> 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 = [(String, String)]
type Label0 = ()
type Label1 = String
type Label2 = (String, String)
type Label3 = (String, String, String)
type Label4 = (String, String, String, String)
type Label5 = (String, String, String, String, String)
type Label6 = (String, String, String, String, String, String)
type Label7 = (String, String, String, String, String, String, String)
type Label8 = (String, String, String, String, String, String, String, String)
type Label9 = (String, String, String, String, String, String, String, String, String)

-- | MonadMonitor describes a class of Monads that are capable of
--   performing asynchronous IO operations.
class Monad m => MonadMonitor m
doIO :: MonadMonitor m => 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 :: String -> String -> Info
[metricName] :: Info -> String
[metricHelp] :: Info -> String

-- | 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.
data Metric s
Metric :: s -> IO [SampleGroup] -> Metric s
[handle] :: Metric s -> s
[collect] :: Metric 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 :: String -> 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