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

-- | Tracking of system metrics
--   
--   This library lets you defined and track system metrics.
@package ekg-core
@version 0.1.1.6

-- | This module defines a type for mutable, integer-valued counters.
--   Counters are non-negative, monotonically increasing values and can be
--   used to track e.g. the number of requests served since program start.
--   All operations on counters are thread-safe.
module System.Metrics.Counter

-- | A mutable, integer-valued counter.
data Counter

-- | Create a new, zero initialized, counter.
new :: IO Counter

-- | Get the current value of the counter.
read :: Counter -> IO Int64

-- | Increase the counter by one.
inc :: Counter -> IO ()

-- | Add the argument to the counter.
add :: Counter -> Int64 -> IO ()

-- | Internal module used to share implementation details between the
--   family of ekg packages. DO NOT DEPEND ON THIS MODULE.
module System.Metrics.Distribution.Internal

-- | Distribution statistics
data Stats
Stats :: !Double -> !Double -> !Int64 -> !Double -> !Double -> !Double -> Stats

-- | Sample mean
[mean] :: Stats -> !Double

-- | Biased sample variance
[variance] :: Stats -> !Double

-- | Event count
[count] :: Stats -> !Int64

-- | Sum of values
[sum] :: Stats -> !Double

-- | Min value seen
[min] :: Stats -> !Double

-- | Max value seen
[max] :: Stats -> !Double
instance GHC.Show.Show System.Metrics.Distribution.Internal.Stats
instance GHC.Classes.Eq System.Metrics.Distribution.Internal.Stats

-- | This module defines a type for mutable, integer-valued gauges. Gauges
--   are variable values and can be used to track e.g. the current number
--   of concurrent connections. All operations on gauges are thread-safe.
module System.Metrics.Gauge

-- | A mutable, integer-valued gauge.
data Gauge

-- | Create a new, zero initialized, gauge.
new :: IO Gauge

-- | Get the current value of the gauge.
read :: Gauge -> IO Int64

-- | Increase the gauge by one.
inc :: Gauge -> IO ()

-- | Decrease the gauge by one.
dec :: Gauge -> IO ()

-- | Increase the gauge by the given amount.
add :: Gauge -> Int64 -> IO ()

-- | Decrease the gauge by the given amount.
subtract :: Gauge -> Int64 -> IO ()

-- | Set the gauge to the given value.
set :: Gauge -> Int64 -> IO ()

-- | This module defines a type for mutable, string-valued labels. Labels
--   are variable values and can be used to track e.g. the command line
--   arguments or other free-form values. All operations on labels are
--   thread-safe.
module System.Metrics.Label

-- | A mutable, text-valued label.
data Label

-- | Create a new empty label.
new :: IO Label

-- | Get the current value of the label.
read :: Label -> IO Text

-- | Set the label to the given value.
set :: Label -> Text -> IO ()

-- | Set the label to the result of applying the given function to the
--   value.
modify :: (Text -> Text) -> Label -> IO ()

-- | This module defines a type for tracking statistics about a series of
--   events. An event could be handling of a request and the value
--   associated with the event -- the value you'd pass to add --
--   could be the amount of time spent serving that request (e.g. in
--   milliseconds). All operations are thread safe.
module System.Metrics.Distribution

-- | An metric for tracking events.
data Distribution

-- | Create a new distribution.
new :: IO Distribution

-- | Add a value to the distribution.
add :: Distribution -> Double -> IO ()

-- | Add the same value to the distribution N times.
addN :: Distribution -> Double -> Int64 -> IO ()

-- | Get the current statistical summary for the event being tracked.
read :: Distribution -> IO Stats

-- | Distribution statistics
data Stats

-- | Sample mean
mean :: Stats -> Double

-- | Biased sample variance
variance :: Stats -> Double

-- | Event count
count :: Stats -> Int64

-- | Sum of values
sum :: Stats -> Double

-- | Min value seen
min :: Stats -> Double

-- | Max value seen
max :: Stats -> Double
instance Foreign.Storable.Storable System.Metrics.Distribution.CDistrib

-- | A module for defining metrics that can be monitored.
--   
--   Metrics are used to monitor program behavior and performance. All
--   metrics have
--   
--   
--   
- a name, and
--   
- a way to get the metric's current value.
--   
--   
--   This module provides a way to register metrics in a global "metric
--   store". The store can then be used to get a snapshot of all metrics.
--   The store also serves as a central place to keep track of all the
--   program's metrics, both user and library defined.
--   
--   Here's an example of creating a single counter, used to count the
--   number of request served by a web server:
--   
--   
--   import System.Metrics
--   import qualified System.Metrics.Counter as Counter
--   
--   main = do
--       store <- newStore
--       requests <- createCounter "myapp.request_count" store
--       -- Every time we receive a request:
--       Counter.inc requests
--   
--   
--   This module also provides a way to register a number of predefined
--   metrics that are useful in most applications. See e.g.
--   registerGcMetrics.
module System.Metrics

-- | A mutable metric store.
data Store

-- | Create a new, empty metric store.
newStore :: IO Store

-- | Register a non-negative, monotonically increasing, integer-valued
--   metric. The provided action to read the value must be thread-safe.
--   Also see createCounter.
registerCounter :: Text -> IO Int64 -> Store -> IO ()

-- | Register an integer-valued metric. The provided action to read the
--   value must be thread-safe. Also see createGauge.
registerGauge :: Text -> IO Int64 -> Store -> IO ()

-- | Register a text metric. The provided action to read the value must be
--   thread-safe. Also see createLabel.
registerLabel :: Text -> IO Text -> Store -> IO ()

-- | Register a distribution metric. The provided action to read the value
--   must be thread-safe. Also see createDistribution.
registerDistribution :: Text -> IO Stats -> Store -> IO ()

-- | Register an action that will be executed any time one of the metrics
--   computed from the value it returns needs to be sampled.
--   
--   When one or more of the metrics listed in the first argument needs to
--   be sampled, the action is executed and the provided getter functions
--   will be used to extract the metric(s) from the action's return value.
--   
--   The registered action might be called from a different thread and
--   therefore needs to be thread-safe.
--   
--   This function allows you to sample groups of metrics together. This is
--   useful if
--   
--   
--   
- you need a consistent view of several metric or
--   
- sampling the metrics together is more efficient.
--   
--   
--   For example, sampling GC statistics needs to be done atomically or a
--   GC might strike in the middle of sampling, rendering the values
--   incoherent. Sampling GC statistics is also more efficient if done in
--   "bulk", as the run-time system provides a function to sample all GC
--   statistics at once.
--   
--   Note that sampling of the metrics is only atomic if the provided
--   action computes a atomically (e.g. if a is a record,
--   the action needs to compute its fields atomically if the sampling is
--   to be atomic.)
--   
--   Example usage:
--   
--   
--   {-# LANGUAGE OverloadedStrings #-}
--   import qualified Data.HashMap.Strict as M
--   import GHC.Stats
--   import System.Metrics
--   
--   main = do
--       store <- newStore
--       let metrics =
--               [ ("num_gcs", Counter . numGcs)
--               , ("max_bytes_used", Gauge . maxBytesUsed)
--               ]
--       registerGroup (M.fromList metrics) getGCStats store
--   
registerGroup :: HashMap Text (a -> Value) -> IO a -> Store -> IO ()

-- | Create and register a zero-initialized counter.
createCounter :: Text -> Store -> IO Counter

-- | Create and register a zero-initialized gauge.
createGauge :: Text -> Store -> IO Gauge

-- | Create and register an empty label.
createLabel :: Text -> Store -> IO Label

-- | Create and register an event tracker.
createDistribution :: Text -> Store -> IO Distribution

-- | Register a number of metrics related to garbage collector behavior.
--   
--   To enable GC statistics collection, either run your program with
--   
--   
--   +RTS -T
--   
--   
--   or compile it with
--   
--   
--   -with-rtsopts=-T
--   
--   
--   The runtime overhead of -T is very small so it's safe to
--   always leave it enabled.
--   
--   Registered counters:
--   
--   
--   
- rts.gc.bytes_allocated Total number of bytes
--   allocated
--   
- rts.gc.num_gcs Number of garbage collections
--   performed
--   
- rts.gc.num_bytes_usage_samples Number of byte
--   usage samples taken
--   
- rts.gc.cumulative_bytes_used Sum of all byte usage
--   samples, can be used with numByteUsageSamples to calculate
--   averages with arbitrary weighting (if you are sampling this record
--   multiple times).
--   
- rts.gc.bytes_copied Number of bytes copied during
--   GC
--   
- rts.gc.init_cpu_ms CPU time used by the init
--   phase, in milliseconds. GHC 8.6+ only.
--   
- rts.gc.init_wall_ms Wall clock time spent running
--   the init phase, in milliseconds. GHC 8.6+ only.
--   
- rts.gc.mutator_cpu_ms CPU time spent running
--   mutator threads, in milliseconds. This does not include any profiling
--   overhead or initialization.
--   
- rts.gc.mutator_wall_ms Wall clock time spent
--   running mutator threads, in milliseconds. This does not include
--   initialization.
--   
- rts.gc.gc_cpu_ms CPU time spent running GC, in
--   milliseconds.
--   
- rts.gc.gc_wall_ms Wall clock time spent running
--   GC, in milliseconds.
--   
- rts.gc.cpu_ms Total CPU time elapsed since program
--   start, in milliseconds.
--   
- rts.gc.wall_ms Total wall clock time elapsed since
--   start, in milliseconds.
--   
--   
--   Registered gauges:
--   
--   
--   
- rts.gc.max_bytes_used Maximum number of live bytes
--   seen so far
--   
- rts.gc.current_bytes_used Current number of live
--   bytes
--   
- rts.gc.current_bytes_slop Current number of bytes
--   lost to slop
--   
- rts.gc.max_bytes_slop Maximum number of bytes lost
--   to slop at any one time so far
--   
- rts.gc.peak_megabytes_allocated Maximum number of
--   megabytes allocated
--   
- rts.gc.par_tot_bytes_copied Number of bytes copied
--   during GC, minus space held by mutable lists held by the capabilities.
--   Can be used with parMaxBytesCopied to determine how well
--   parallel GC utilized all cores.
--   
- rts.gc.par_avg_bytes_copied Deprecated alias for
--   par_tot_bytes_copied.
--   
- rts.gc.par_max_bytes_copied Sum of number of bytes
--   copied each GC by the most active GC thread each GC. The ratio of
--   par_tot_bytes_copied divided by par_max_bytes_copied
--   approaches 1 for a maximally sequential run and approaches the number
--   of threads (set by the RTS flag -N) for a maximally parallel
--   run.
--   
registerGcMetrics :: Store -> IO ()

-- | A sample of some metrics.
type Sample = HashMap Text Value

-- | Sample all metrics. Sampling is not atomic in the sense that
--   some metrics might have been mutated before they're sampled but after
--   some other metrics have already been sampled.
sampleAll :: Store -> IO Sample

-- | The value of a sampled metric.
data Value
Counter :: {-# UNPACK #-} !Int64 -> Value
Gauge :: {-# UNPACK #-} !Int64 -> Value
Label :: {-# UNPACK #-} !Text -> Value
Distribution :: !Stats -> Value
instance GHC.Show.Show System.Metrics.Value
instance GHC.Classes.Eq System.Metrics.Value
