Prometheus

This module provides the basics for instrumenting Haskell executables for use with the Prometheus monitoring system.

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.

unsafeRegisterIO :: IO (Metric s) -> s

Registers a metric with the global metric registry.

IMPORTANT: This method should only be used to register metrics as top level symbols, it should not be run from other pure code.

For example,

>>> :{
 {-# NOINLINE c #-}
 let c = unsafeRegisterIO $ counter (Info "my_counter" "An example metric")
:}
...

unsafeRegister :: Metric s -> s

Registers a metric with the global metric registry.

IMPORTANT: This method should only be used to register metrics as top level symbols, it should not be run from other pure code.

unregisterAll :: MonadIO m => m ()

Removes all currently registered metrics from the registry.

collectMetrics :: MonadIO m => m [SampleGroup]

Collect samples from all currently registered metrics. In typical use cases there is no reason to use this function, instead you should use exportMetricsAsText 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.

Exporting

exportMetricsAsText :: MonadIO m => m ByteString

Export all registered metrics in the Prometheus 0.0.4 text exposition format.

For the full specification of the format, see the official Prometheus documentation.

>>> :m +Data.ByteString
>>> myCounter <- register $ counter (Info "my_counter" "Example counter")
>>> incCounter myCounter
>>> exportMetricsAsText >>= Data.ByteString.Lazy.putStr
# HELP my_counter Example counter
# TYPE my_counter counter
my_counter 1.0

Metrics

A metric represents a single value that is being monitored. For example a metric could be the number of open files, the current CPU temperature, the elapsed time of execution, and the latency of HTTP requests.

This module provides 4 built-in metric types: counters, gauges, summaries, and metric vectors. These types of metrics should cover most typical use cases. However, for more specialized use cases it is also possible to write custom metrics.

Counter

A counter models a monotonically increasing value. It is the simplest type of metric provided by this library.

A Counter is typically used to count requests served, tasks completed, errors occurred, etc.

>>> myCounter <- register $ counter (Info "my_counter" "An example counter")
>>> replicateM_ 47 (incCounter myCounter)
>>> getCounter myCounter
47.0
>>> void $ addCounter myCounter 10
>>> getCounter myCounter
57.0

data Counter

Instances

NFData Counter

Defined in Prometheus.Metric.Counter

Methods

rnf :: Counter -> ()

counter :: Info -> Metric Counter

Creates a new counter metric with a given name and help string.

incCounter :: MonadMonitor m => Counter -> m ()

Increments the value of a counter metric by 1.

addCounter :: MonadMonitor m => Counter -> Double -> m Bool

Add the given value to the counter, if it is zero or more.

unsafeAddCounter :: MonadMonitor m => Counter -> Double -> m ()

Add the given value to the counter. Panic if it is less than zero.

addDurationToCounter :: (MonadIO m, MonadMonitor m) => Counter -> m a -> m a

Add the duration of an IO action (in seconds) to a counter.

If the IO action throws, no duration is added.

countExceptions :: (MonadCatch m, MonadMonitor m) => Counter -> m a -> m a

Count the amount of times an action throws any synchronous exception.

>>> exceptions <- register $ counter (Info "exceptions_total" "Total amount of exceptions thrown")
>>> countExceptions exceptions $ return ()
>>> getCounter exceptions
0.0
>>> countExceptions exceptions (error "Oh no!") `catch` (\SomeException{} -> return ())
>>> getCounter exceptions
1.0

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 incCounter.

getCounter :: MonadIO m => Counter -> m Double

Retrieves the current value of a counter metric.

Gauge

A gauge models an arbitrary floating point value. There are operations to set the value of a gauge as well as add and subtract arbitrary values.

>>> myGauge <- register $ gauge (Info "my_gauge" "An example gauge")
>>> setGauge myGauge 100
>>> addGauge myGauge 50
>>> subGauge myGauge 25
>>> getGauge myGauge
125.0

data Gauge

Instances

NFData Gauge

Defined in Prometheus.Metric.Gauge

Methods

rnf :: Gauge -> ()

gauge :: Info -> Metric Gauge

Create a new gauge metric with a given name and help string.

incGauge :: MonadMonitor m => Gauge -> m ()

Increments a gauge metric by 1.

decGauge :: MonadMonitor m => Gauge -> m ()

Decrements a gauge metric by 1.

addGauge :: MonadMonitor m => Gauge -> Double -> m ()

Adds a value to a gauge metric.

subGauge :: MonadMonitor m => Gauge -> Double -> m ()

Subtracts a value from a gauge metric.

setGauge :: MonadMonitor m => Gauge -> Double -> m ()

Sets a gauge metric to a specific value.

setGaugeToDuration :: (MonadIO m, MonadMonitor m) => Gauge -> m a -> m a

Sets a gauge metric to the duration in seconds of an IO action.

getGauge :: MonadIO m => Gauge -> m Double

Retrieves the current value of a gauge metric.

Summaries and histograms

An Observer is a generic metric that captures observations of a floating point value over time. Different implementations can store and summarise these value in different ways.

The two main observers are summaries and histograms. A Summary allows you to get a precise estimate of a particular quantile, but cannot be meaningfully aggregated across processes. A Histogram packs requests into user-supplied buckets, which can be aggregated meaningfully, but provide much less precise information on particular quantiles.

class Observer metric where

Interface shared by Summary and Histogram.

Methods

observe :: MonadMonitor m => metric -> Double -> m ()

Observe that a particular floating point value has occurred. For example, observe that this request took 0.23s.

Instances

Observer Summary

Defined in Prometheus.Metric.Summary

Methods

observe :: MonadMonitor m => Summary -> Double -> m ()

Observer Histogram

Defined in Prometheus.Metric.Histogram

Methods

observe :: MonadMonitor m => Histogram -> Double -> m ()

observeDuration :: (Observer metric, MonadIO m, MonadMonitor m) => metric -> m a -> m a

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.

Summary

A summary is an Observer that summarizes the observations as a count, sum, and rank estimations. A typical use case for summaries is measuring HTTP request latency.

>>> mySummary <- register $ summary (Info "my_summary" "") defaultQuantiles
>>> observe mySummary 0
>>> getSummary mySummary
[(1 % 2,0.0),(9 % 10,0.0),(99 % 100,0.0)]

data Summary

Instances

NFData Summary

Defined in Prometheus.Metric.Summary

Methods

rnf :: Summary -> ()

Observer Summary

Defined in Prometheus.Metric.Summary

Methods

observe :: MonadMonitor m => Summary -> Double -> m ()

type Quantile = (Rational, Rational)

A quantile is a pair of a quantile value and an associated acceptable error value.

summary :: Info -> [Quantile] -> Metric Summary

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 defaultQuantiles.

defaultQuantiles :: [Quantile]

getSummary :: MonadIO m => Summary -> m [(Rational, Double)]

Retrieves a list of tuples containing a quantile and its associated value.

Histogram

A histogram captures observations of a floating point value over time and stores those observations in a user-supplied histogram. A typical use case for histograms is measuring HTTP request latency. Histograms are unlike summaries in that they can be meaningfully aggregated across processes.

>>> myHistogram <- register $ histogram (Info "my_histogram" "") defaultBuckets
>>> observe myHistogram 0
>>> getHistogram myHistogram
fromList [(5.0e-3,1),(1.0e-2,0),(2.5e-2,0),(5.0e-2,0),(0.1,0),(0.25,0),(0.5,0),(1.0,0),(2.5,0),(5.0,0),(10.0,0)]

data Histogram

A histogram. Counts the number of observations that fall within the specified buckets.

Instances

NFData Histogram

Defined in Prometheus.Metric.Histogram

Methods

rnf :: Histogram -> ()

Observer Histogram

Defined in Prometheus.Metric.Histogram

Methods

observe :: MonadMonitor m => Histogram -> Double -> m ()

type Bucket = Double

Upper-bound for a histogram bucket.

histogram :: Info -> [Bucket] -> Metric Histogram

Create a new Histogram 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 defaultBuckets. You can also create buckets with linearBuckets or exponentialBuckets.

defaultBuckets :: [Double]

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.

exponentialBuckets :: Bucket -> Double -> Int -> [Bucket]

Create count buckets, where the lowest bucket has an upper bound of start and each bucket's upper bound is factor times the previous bucket's upper bound. Use this to create buckets for histogram.

linearBuckets :: Bucket -> Double -> Int -> [Bucket]

Create count buckets, each width wide, where the lowest bucket has an upper bound of start. Use this to create buckets for histogram.

getHistogram :: MonadIO m => Histogram -> m (Map Bucket Int)

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.

Vector

A vector models a collection of metrics that share the same name but are partitioned across a set of dimensions.

>>> myVector <- register $ vector ("method", "code") $ counter (Info "http_requests" "")
>>> withLabel myVector ("GET", "200") incCounter
>>> withLabel myVector ("GET", "200") incCounter
>>> withLabel myVector ("GET", "404") incCounter
>>> withLabel myVector ("POST", "200") incCounter
>>> getVectorWith myVector getCounter
[(("GET","200"),2.0),(("GET","404"),1.0),(("POST","200"),1.0)]
>>> exportMetricsAsText >>= Data.ByteString.Lazy.putStr
# HELP http_requests
# TYPE http_requests counter
http_requests{method="GET",code="200"} 2.0
http_requests{method="GET",code="404"} 1.0
http_requests{method="POST",code="200"} 1.0

data Vector l m

Instances

NFData (Vector l m)

Defined in Prometheus.Metric.Vector

Methods

rnf :: Vector l m -> ()

vector :: Label l => l -> Metric m -> Metric (Vector l m)

Creates a new vector of metrics given a label.

withLabel :: (Label label, MonadMonitor m) => Vector label metric -> label -> (metric -> IO ()) -> m ()

Given a label, applies an operation to the corresponding metric in the vector.

removeLabel :: (Label label, MonadMonitor m) => Vector label metric -> label -> m ()

Removes a label from a vector.

clearLabels :: (Label label, MonadMonitor m) => Vector label metric -> m ()

Removes all labels from a vector.

getVectorWith :: Vector label metric -> (metric -> IO a) -> IO [(label, a)]

Labels

The labels of a vector metric are types of the class Label. This module defines all n-tupes of Strings for n <= 9 to be Labels. Additionally, the type aliases LabelN is defined for each of these tuple types to make specifying the types of vectors more concise.

>>> :{
>>> let myVector :: Metric (Vector Label3 Counter);
>>> myVector = vector ("a", "b", "c") $ counter (Info "some_counter" "")
>>> :}

class Ord l => Label l where

Label describes a class of types that can be used to as the label of a vector.

Methods

labelPairs :: l -> l -> LabelPairs

Instances

Label ()

Defined in Prometheus.Label

Methods

labelPairs :: () -> () -> LabelPairs

Label Text

Defined in Prometheus.Label

Methods

labelPairs :: Text -> Text -> LabelPairs

(a ~ Text, b ~ a) => Label (a, b)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b) -> (a, b) -> LabelPairs

(a ~ Text, b ~ a, c ~ a) => Label (a, b, c)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b, c) -> (a, b, c) -> LabelPairs

(a ~ Text, b ~ a, c ~ a, d ~ a) => Label (a, b, c, d)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b, c, d) -> (a, b, c, d) -> LabelPairs

(a ~ Text, b ~ a, c ~ a, d ~ a, e ~ a) => Label (a, b, c, d, e)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b, c, d, e) -> (a, b, c, d, e) -> LabelPairs

(a ~ Text, b ~ a, c ~ a, d ~ a, e ~ a, f ~ a) => Label (a, b, c, d, e, f)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b, c, d, e, f) -> (a, b, c, d, e, f) -> LabelPairs

(a ~ Text, b ~ a, c ~ a, d ~ a, e ~ a, f ~ a, g ~ a) => Label (a, b, c, d, e, f, g)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b, c, d, e, f, g) -> (a, b, c, d, e, f, g) -> LabelPairs

(a ~ Text, b ~ a, c ~ a, d ~ a, e ~ a, f ~ a, g ~ a, h ~ a) => Label (a, b, c, d, e, f, g, h)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b, c, d, e, f, g, h) -> (a, b, c, d, e, f, g, h) -> LabelPairs

(a ~ Text, b ~ a, c ~ a, d ~ a, e ~ a, f ~ a, g ~ a, h ~ a, i ~ a) => Label (a, b, c, d, e, f, g, h, i)

Defined in Prometheus.Label

Methods

labelPairs :: (a, b, c, d, e, f, g, h, i) -> (a, b, c, d, e, f, g, h, i) -> LabelPairs

type LabelPairs = [(Text, Text)]

A list of tuples where the first value is the label and the second is the value of that label.

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)

Custom metrics

Custom metrics can be created by directly creating a new Metric type. There are two parts of any metric, the handle and the collect method.

The handle is a value embedded in the metric that is intended to allow for communication with the metric from instrumented code. For example, all of the metrics provided by this library use a newtype wrapped TVar of some underlying data type as their handle. When defining a new metric, it is recommended that you use a newtype wrapper around your handle type as it will allow users of your metric to succinctly identify your metric in type signatures.

The collect method is responsible for serializing the current value of a metric into a list of SampleGroups.

The following is an example of a custom metric that models the current CPU time. It uses a newtype wrapped unit as the handler type since it doesn't need to maintain any state.

>>> :m +System.CPUTime
>>> :m +Data.ByteString.UTF8
>>> newtype CPUTime = MkCPUTime ()
>>> let info = Info "cpu_time" "The current CPU time"
>>> let toValue = Data.ByteString.UTF8.fromString . show
>>> let toSample = Sample "cpu_time" [] . toValue
>>> let toSampleGroup = (:[]) . SampleGroup info GaugeType . (:[]) . toSample
>>> let collectCPUTime = fmap toSampleGroup getCPUTime
>>> let cpuTimeMetric = Metric (return (MkCPUTime (), collectCPUTime))
>>> register cpuTimeMetric
>>> exportMetricsAsText >>= Data.ByteString.Lazy.putStr
# HELP cpu_time The current CPU time
# TYPE cpu_time gauge
cpu_time ...

Instrumenting pure code

Pure code can be instrumented through the use of the Monitor monad and MonitorT monad transformer. These constructs work by queueing all operations on metrics. In order for the operations to actually be performed, the queue must be evaluated within the IO monad.

The following is a contrived example that defines an add function that records the number of times it was invoked.

add :: Int -> Int -> Monitor Int

Note that the changes to numAdds are not reflected until the updateMetrics value has been evaluated in the IO monad.

>>> numAdds <- register $ counter (Info "num_adds" "The number of additions")
>>> let add x y = incCounter numAdds >> return (x + y)
>>> let (3, updateMetrics) = runMonitor $ (add 1 1) >>= (add 1)
>>> getCounter numAdds
0.0
>>> updateMetrics
>>> getCounter numAdds
2.0

class Monad m => MonadMonitor m where

MonadMonitor describes a class of Monads that are capable of performing asynchronous IO operations.

Minimal complete definition

Nothing

Methods

doIO :: IO () -> m ()

doIO :: (MonadTrans t, MonadMonitor n, m ~ t n) => IO () -> m ()

Instances

MonadMonitor IO

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> IO ()

MonadMonitor m => MonadMonitor (MaybeT m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> MaybeT m ()

Monad m => MonadMonitor (MonitorT m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> MonitorT m ()

MonadMonitor m => MonadMonitor (ExceptT e m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> ExceptT e m ()

MonadMonitor m => MonadMonitor (IdentityT m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> IdentityT m ()

(Error e, MonadMonitor m) => MonadMonitor (ErrorT e m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> ErrorT e m ()

MonadMonitor m => MonadMonitor (StateT s m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> StateT s m ()

MonadMonitor m => MonadMonitor (StateT s m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> StateT s m ()

(MonadMonitor m, Monoid w) => MonadMonitor (WriterT w m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> WriterT w m ()

(MonadMonitor m, Monoid w) => MonadMonitor (WriterT w m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> WriterT w m ()

MonadMonitor m => MonadMonitor (ReaderT r m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> ReaderT r m ()

(MonadMonitor m, Monoid w) => MonadMonitor (RWST r w s m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> RWST r w s m ()

(MonadMonitor m, Monoid w) => MonadMonitor (RWST r w s m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> RWST r w s m ()

type Monitor a = MonitorT Identity a

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).

runMonitor :: Monitor a -> (a, IO ())

Extract a value and the corresponding monitor update value from the Monitor monad. For an example use see Monitor.

data MonitorT m a

MonitorT is the monad transformer analog of Monitor and allows for monitoring pure monad transformer stacks.

Instances

MonadTrans MonitorT

Defined in Prometheus.MonadMonitor

Methods

lift :: Monad m => m a -> MonitorT m a

Monad m => Monad (MonitorT m)

Defined in Prometheus.MonadMonitor

Methods

(>>=) :: MonitorT m a -> (a -> MonitorT m b) -> MonitorT m b

(>>) :: MonitorT m a -> MonitorT m b -> MonitorT m b

return :: a -> MonitorT m a

fail :: String -> MonitorT m a

Functor m => Functor (MonitorT m)

Defined in Prometheus.MonadMonitor

Methods

fmap :: (a -> b) -> MonitorT m a -> MonitorT m b

(<$) :: a -> MonitorT m b -> MonitorT m a

Applicative m => Applicative (MonitorT m)

Defined in Prometheus.MonadMonitor

Methods

pure :: a -> MonitorT m a

(<*>) :: MonitorT m (a -> b) -> MonitorT m a -> MonitorT m b

liftA2 :: (a -> b -> c) -> MonitorT m a -> MonitorT m b -> MonitorT m c

(*>) :: MonitorT m a -> MonitorT m b -> MonitorT m b

(<*) :: MonitorT m a -> MonitorT m b -> MonitorT m a

Monad m => MonadMonitor (MonitorT m)

Defined in Prometheus.MonadMonitor

Methods

doIO :: IO () -> MonitorT m ()

runMonitorT :: Monad m => MonitorT m a -> m (a, IO ())

Extract a value and the corresponding monitor update value from the MonitorT monad transformer.

Base data types

data Info

Meta data about a metric including its name and a help string that describes the value that the metric is measuring.

Constructors

Info

Fields

• metricName :: Text
• metricHelp :: Text

Instances

Eq Info

Defined in Prometheus.Info

Methods

(==) :: Info -> Info -> Bool

(/=) :: Info -> Info -> Bool

Ord Info

Defined in Prometheus.Info

Methods

compare :: Info -> Info -> Ordering

(<) :: Info -> Info -> Bool

(<=) :: Info -> Info -> Bool

(>) :: Info -> Info -> Bool

(>=) :: Info -> Info -> Bool

max :: Info -> Info -> Info

min :: Info -> Info -> Info

Read Info

Defined in Prometheus.Info

Methods

readsPrec :: Int -> ReadS Info

readList :: ReadS [Info]

readPrec :: ReadPrec Info

readListPrec :: ReadPrec [Info]

Show Info

Defined in Prometheus.Info

Methods

showsPrec :: Int -> Info -> ShowS

show :: Info -> String

showList :: [Info] -> ShowS

newtype Metric s

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.

Constructors

Metric

Fields

• construct :: IO (s, IO [SampleGroup])

  construct is an IO action that creates a new instance of a metric. For example, in a counter, this IO action would create a mutable reference to maintain the state of the counter.

  construct returns two things:

  1. The state of the metric itself, which can be used to modify the metric. A counter would return state pointing to the mutable reference.
  2. An IO action that samples the metric and returns SampleGroups. This is the data that will be stored by Prometheus.

Instances

NFData a => NFData (Metric a)

Defined in Prometheus.Metric

Methods

rnf :: Metric a -> ()

data Sample

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.

Constructors

Sample Text LabelPairs ByteString

Instances

Show Sample

Defined in Prometheus.Metric

Methods

showsPrec :: Int -> Sample -> ShowS

show :: Sample -> String

showList :: [Sample] -> ShowS

data SampleGroup

A Sample group is a list of samples that is tagged with meta data including the name, help string, and type of the sample.

Constructors

SampleGroup Info SampleType [Sample]

Instances

Show SampleGroup

Defined in Prometheus.Metric

Methods

showsPrec :: Int -> SampleGroup -> ShowS

show :: SampleGroup -> String

showList :: [SampleGroup] -> ShowS

data SampleType

The type of a sample. This corresponds to the 5 types of metrics supported by Prometheus.

Constructors

CounterType

GaugeType

SummaryType

HistogramType

UntypedType

Instances

Show SampleType

Defined in Prometheus.Metric

Methods

showsPrec :: Int -> SampleType -> ShowS

show :: SampleType -> String

showList :: [SampleType] -> ShowS