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


-- | Remote monitoring of processes
--   
--   This library lets you remotely monitor a running process over HTTP. It
--   provides a simple way to integrate a monitoring server into any
--   application.
@package ekg
@version 0.4.0.15


-- | 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.
--   
--   N.B. This module exists to maintain backwards compatibility with older
--   versions of this library. New code should use the
--   <tt>System.Metrics.Counter</tt> module from the ekg-core package
--   instead.
module System.Remote.Counter

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

-- | 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.
--   
--   N.B. This module exists to maintain backwards compatibility with older
--   versions of this library. New code should use the
--   <tt>System.Metrics.Gauge</tt> module from the ekg-core package
--   instead.
module System.Remote.Gauge

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

-- | 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.
--   
--   N.B. This module exists to maintain backwards compatibility with older
--   versions of this library. New code should use the
--   <tt>System.Metrics.Label</tt> module from the ekg-core package
--   instead.
module System.Remote.Label

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

-- | 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 provides remote monitoring of a running process over HTTP.
--   It can be used to run an HTTP server that provides both a web-based
--   user interface and a machine-readable API (e.g. JSON.) The former can
--   be used by a human to get an overview of what the program is doing and
--   the latter can be used by automated monitoring tools.
--   
--   Typical usage is to start the monitoring server at program startup
--   
--   <pre>
--   main = do
--       forkServer "localhost" 8000
--       ...
--   </pre>
--   
--   and then periodically check the stats using a web browser or a command
--   line tool (e.g. curl)
--   
--   <pre>
--   $ curl -H "Accept: application/json" http://localhost:8000/
--   </pre>
module System.Remote.Monitoring

-- | A handle that can be used to control the monitoring server. Created by
--   <a>forkServer</a>.
data Server

-- | The thread ID of the server. You can kill the server by killing this
--   thread (i.e. by throwing it an asynchronous exception.)
serverThreadId :: Server -> ThreadId

-- | The metric store associated with the server. If you want to add metric
--   to the default store created by <a>forkServer</a> you need to use this
--   function to retrieve it.
serverMetricStore :: Server -> Store

-- | Like <a>forkServerWith</a>, but creates a default metric store with
--   some predefined metrics. The predefined metrics are those given in
--   <a>registerGcMetrics</a>.
forkServer :: ByteString -> Int -> IO Server

-- | Start an HTTP server in a new thread. The server replies to GET
--   requests to the given host and port. The host argument can be either a
--   numeric network address (dotted quad for IPv4, colon-separated hex for
--   IPv6) or a hostname (e.g. "localhost".) The client can control the
--   Content-Type used in responses by setting the Accept header. At the
--   moment two content types are available: "application/json" and
--   "text/html".
--   
--   Registers the following counter, used by the UI:
--   
--   <ul>
--   <li><i><tt>ekg.server_time_ms</tt></i> The server time when the sample
--   was taken, in milliseconds.</li>
--   </ul>
--   
--   Note that this function, unlike <a>forkServer</a>, doesn't register
--   any other predefined metrics. This allows other libraries to create
--   and provide a metric store for use with this library. If the metric
--   store isn't created by you and the creator doesn't register the
--   metrics registered by <a>forkServer</a>, you might want to register
--   them yourself.
forkServerWith :: Store -> ByteString -> Int -> IO Server

-- | Return a new, zero-initialized counter associated with the given name
--   and server. Multiple calls to <a>getCounter</a> with the same
--   arguments will result in an <a>error</a>.
getCounter :: Text -> Server -> IO Counter

-- | Return a new, zero-initialized gauge associated with the given name
--   and server. Multiple calls to <a>getGauge</a> with the same arguments
--   will result in an <a>error</a>.
getGauge :: Text -> Server -> IO Gauge

-- | Return a new, empty label associated with the given name and server.
--   Multiple calls to <a>getLabel</a> with the same arguments will result
--   in an <a>error</a>.
getLabel :: Text -> Server -> IO Label

-- | Return a new distribution associated with the given name and server.
--   Multiple calls to <a>getDistribution</a> with the same arguments will
--   result in an <a>error</a>.
getDistribution :: Text -> Server -> IO Distribution
