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


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


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


-- | 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 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 <a>add</a> --
--   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
--   
--   <ul>
--   <li>a name, and</li>
--   <li>a way to get the metric's current value.</li>
--   </ul>
--   
--   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:
--   
--   <pre>
--   import System.Metrics
--   import qualified System.Metrics.Counter as Counter
--   
--   main = do
--       store &lt;- newStore
--       requests &lt;- createCounter "myapp.request_count" store
--       -- Every time we receive a request:
--       Counter.inc requests
--   </pre>
--   
--   This module also provides a way to register a number of predefined
--   metrics that are useful in most applications. See e.g.
--   <a>registerGcMetrics</a>.
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 <a>createCounter</a>.
registerCounter :: Text -> IO Int64 -> Store -> IO ()

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

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

-- | Register a distribution metric. The provided action to read the value
--   must be thread-safe. Also see <a>createDistribution</a>.
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
--   
--   <ul>
--   <li>you need a consistent view of several metric or</li>
--   <li>sampling the metrics together is more efficient.</li>
--   </ul>
--   
--   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 <tt>a</tt> atomically (e.g. if <tt>a</tt> is a record,
--   the action needs to compute its fields atomically if the sampling is
--   to be atomic.)
--   
--   Example usage:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   import qualified Data.HashMap.Strict as M
--   import GHC.Stats
--   import System.Metrics
--   
--   main = do
--       store &lt;- newStore
--       let metrics =
--               [ ("num_gcs", Counter . numGcs)
--               , ("max_bytes_used", Gauge . maxBytesUsed)
--               ]
--       registerGroup (M.fromList metrics) getGCStats store
--   </pre>
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
--   
--   <pre>
--   +RTS -T
--   </pre>
--   
--   or compile it with
--   
--   <pre>
--   -with-rtsopts=-T
--   </pre>
--   
--   The runtime overhead of <tt>-T</tt> is very small so it's safe to
--   always leave it enabled.
--   
--   Registered counters:
--   
--   <ul>
--   <li><i><tt>rts.gc.bytes_allocated</tt></i> Total number of bytes
--   allocated</li>
--   <li><i><tt>rts.gc.num_gcs</tt></i> Number of garbage collections
--   performed</li>
--   <li><i><tt>rts.gc.num_bytes_usage_samples</tt></i> Number of byte
--   usage samples taken</li>
--   <li><i><tt>rts.gc.cumulative_bytes_used</tt></i> Sum of all byte usage
--   samples, can be used with <tt>numByteUsageSamples</tt> to calculate
--   averages with arbitrary weighting (if you are sampling this record
--   multiple times).</li>
--   <li><i><tt>rts.gc.bytes_copied</tt></i> Number of bytes copied during
--   GC</li>
--   <li><i><tt>rts.gc.mutator_cpu_ms</tt></i> CPU time spent running
--   mutator threads, in milliseconds. This does not include any profiling
--   overhead or initialization.</li>
--   <li><i><tt>rts.gc.mutator_wall_ms</tt></i> Wall clock time spent
--   running mutator threads, in milliseconds. This does not include
--   initialization.</li>
--   <li><i><tt>rts.gc.gc_cpu_ms</tt></i> CPU time spent running GC, in
--   milliseconds.</li>
--   <li><i><tt>rts.gc.gc_wall_ms</tt></i> Wall clock time spent running
--   GC, in milliseconds.</li>
--   <li><i><tt>rts.gc.cpu_ms</tt></i> Total CPU time elapsed since program
--   start, in milliseconds.</li>
--   <li><i><tt>rts.gc.wall_ms</tt></i> Total wall clock time elapsed since
--   start, in milliseconds.</li>
--   </ul>
--   
--   Registered gauges:
--   
--   <ul>
--   <li><i><tt>rts.gc.max_bytes_used</tt></i> Maximum number of live bytes
--   seen so far</li>
--   <li><i><tt>rts.gc.current_bytes_used</tt></i> Current number of live
--   bytes</li>
--   <li><i><tt>rts.gc.current_bytes_slop</tt></i> Current number of bytes
--   lost to slop</li>
--   <li><i><tt>rts.gc.max_bytes_slop</tt></i> Maximum number of bytes lost
--   to slop at any one time so far</li>
--   <li><i><tt>rts.gc.peak_megabytes_allocated</tt></i> Maximum number of
--   megabytes allocated</li>
--   <li><i><tt>rts.gc.par_tot_bytes_copied</tt></i> Number of bytes copied
--   during GC, minus space held by mutable lists held by the capabilities.
--   Can be used with <tt>parMaxBytesCopied</tt> to determine how well
--   parallel GC utilized all cores.</li>
--   <li><i><tt>rts.gc.par_avg_bytes_copied</tt></i> Deprecated alias for
--   <tt>par_tot_bytes_copied</tt>.</li>
--   <li><i><tt>rts.gc.par_max_bytes_copied</tt></i> Sum of number of bytes
--   copied each GC by the most active GC thread each GC. The ratio of
--   <tt>par_tot_bytes_copied</tt> divided by <tt>par_max_bytes_copied</tt>
--   approaches 1 for a maximally sequential run and approaches the number
--   of threads (set by the RTS flag <tt>-N</tt>) for a maximally parallel
--   run.</li>
--   </ul>
registerGcMetrics :: Store -> IO ()

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

-- | Sample all metrics. Sampling is <i>not</i> 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
