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


-- | Structured logging solution with multiple backends
--   
--   A library that provides a way to record structured log messages with
--   multiple backends.
--   
--   Supported backends:
--   
--   <ul>
--   <li>standard output</li>
--   <li>Elasticsearch</li>
--   <li>PostgreSQL</li>
--   </ul>
@package log
@version 0.5.4


-- | Basic data types used throughout the package.
module Log.Data

-- | Available log levels.
data LogLevel
LogAttention :: LogLevel
LogInfo :: LogLevel
LogTrace :: LogLevel
showLogLevel :: LogLevel -> Text
readLogLevel :: Text -> LogLevel

-- | Represents message to be logged.
data LogMessage
LogMessage :: !Text -> ![Text] -> !UTCTime -> !LogLevel -> !Text -> !Value -> LogMessage

-- | Component of an application.
[lmComponent] :: LogMessage -> !Text

-- | Aplication log domain.
[lmDomain] :: LogMessage -> ![Text]

-- | Time of the logged event.
[lmTime] :: LogMessage -> !UTCTime

-- | Log level.
[lmLevel] :: LogMessage -> !LogLevel

-- | Message to be logged.
[lmMessage] :: LogMessage -> !Text

-- | Additional data associated with the message.
[lmData] :: LogMessage -> !Value

-- | Render a <a>LogMessage</a> to <tt>Text</tt>.
showLogMessage :: Maybe UTCTime -> LogMessage -> Text
instance GHC.Show.Show Log.Data.LogMessage
instance GHC.Classes.Eq Log.Data.LogMessage
instance GHC.Show.Show Log.Data.LogLevel
instance GHC.Classes.Ord Log.Data.LogLevel
instance GHC.Classes.Eq Log.Data.LogLevel
instance GHC.Enum.Bounded Log.Data.LogLevel
instance Control.DeepSeq.NFData Log.Data.LogLevel
instance Data.Aeson.Types.Class.ToJSON Log.Data.LogMessage
instance Control.DeepSeq.NFData Log.Data.LogMessage


-- | The <a>Logger</a> type of logging back-ends.
module Log.Logger

-- | An object used for communication with a logger thread that outputs
--   <a>LogMessage</a>s using e.g. PostgreSQL, Elasticsearch or stdout
--   (depending on the back-end chosen).
data Logger

-- | Start a logger thread that consumes one queued message at a time.
mkLogger :: Text -> (LogMessage -> IO ()) -> IO Logger

-- | Start an asynchronous logger thread that consumes all queued messages
--   once per second. To make sure that the messages get written out in the
--   presence of exceptions, use high-level wrappers like
--   <tt>withElasticSearchLogger</tt> or <tt>withBulkStdOutLogger</tt>
--   instead of this function directly.
--   
--   Note: some messages can be lost when the main thread shuts down
--   without making sure that all logger threads have written out all
--   messages, because in that case child threads are not given a chance to
--   clean up by the RTS. This is apparently a feature:
--   <a>https://mail.haskell.org/pipermail/haskell-cafe/2014-February/112754.html</a>
--   
--   To work around this issue, make sure that the main thread doesn't exit
--   until all its children have terminated. The <tt>async</tt> package
--   makes this easy.
--   
--   Problematic example:
--   
--   <pre>
--   import Control.Concurrent.Async
--   
--   main :: IO ()
--   main = do
--      logger &lt;- elasticSearchLogger
--      a <a>async (withElasticSearchLogger $ logger -</a>
--                  runLogT "main" logger $ logTrace_ "foo")
--      -- Main thread exits without waiting for the child
--      -- to finish and without giving the child a chance
--      -- to do proper cleanup.
--   </pre>
--   
--   Fixed example:
--   
--   <pre>
--   import Control.Concurrent.Async
--   
--   main :: IO ()
--   main = do
--      logger &lt;- elasticSearchLogger
--      a <a>async (withElasticSearchLogger $ logger -</a>
--                  runLogT "main" logger $ logTrace_ "foo")
--      wait a
--      -- Main thread waits for the child to finish, giving
--      -- it a chance to shut down properly. This works even
--      -- in the presence of exceptions in the child thread.
--   </pre>
mkBulkLogger :: Text -> ([LogMessage] -> IO ()) -> IO () -> IO Logger

-- | Execute logger to serialize a <a>LogMessage</a>.
execLogger :: Logger -> LogMessage -> IO ()

-- | Wait until all <a>LogMessage</a>s stored in the internal queue are
--   serialized.
waitForLogger :: Logger -> IO ()

-- | Shutdown the logger thread associated with this <a>Logger</a> object.
--   Subsequent attempts to write messages via this <a>Logger</a> will
--   result in an exception.
shutdownLogger :: Logger -> IO ()


-- | The <a>MonadLog</a> type class of monads with logging capabilities.
module Log.Class

-- | This is the simplest representation of UTC. It consists of the day
--   number, and a time offset from midnight. Note that if a day has a leap
--   second added to it, it will have 86401 seconds.
data UTCTime :: *

-- | Class of monads which carry the notion of the current time.
class Monad m => MonadTime (m :: * -> *)
currentTime :: MonadTime m => m UTCTime

-- | Represents the family of monads with logging capabilities. Each
--   <a>MonadLog</a> carries with it some associated state (the logging
--   environment) that can be modified locally with <a>localData</a> and
--   <a>localDomain</a>.
class MonadTime m => MonadLog m

-- | Write a message to the log.
logMessage :: MonadLog m => UTCTime -> LogLevel -> Text -> Value -> m ()

-- | Extend the additional data associated with each log message locally.
localData :: MonadLog m => [Pair] -> m a -> m a

-- | Extend the current application domain locally.
localDomain :: MonadLog m => Text -> m a -> m a

-- | Log a message and its associated data using current time as the event
--   time and the <a>LogAttention</a> log level.
logAttention :: MonadLog m => Text -> Value -> m ()

-- | Log a message and its associated data using current time as the event
--   time and the <a>LogInfo</a> log level.
logInfo :: MonadLog m => Text -> Value -> m ()

-- | Log a message and its associated data using current time as the event
--   time and the <a>LogTrace</a> log level.
logTrace :: MonadLog m => Text -> Value -> m ()

-- | Like <a>logAttention</a>, but without any additional associated data.
logAttention_ :: MonadLog m => Text -> m ()

-- | Like <a>logInfo</a>, but without any additional associated data.
logInfo_ :: MonadLog m => Text -> m ()

-- | Like <a>logTrace</a>, but without any additional associated data.
logTrace_ :: MonadLog m => Text -> m ()
instance (Log.Class.MonadLog m, GHC.Base.Monad (t m), Control.Monad.Trans.Control.MonadTransControl t) => Log.Class.MonadLog (t m)


-- | The <a>LogT</a> monad transformer for adding logging capabilities to
--   any monad.
module Log.Monad

-- | An object used for communication with a logger thread that outputs
--   <a>LogMessage</a>s using e.g. PostgreSQL, Elasticsearch or stdout
--   (depending on the back-end chosen).
data Logger

-- | The state that every <a>LogT</a> carries around.
data LoggerEnv
LoggerEnv :: !Logger -> !Text -> ![Text] -> ![Pair] -> LoggerEnv

-- | The <a>Logger</a> to use.
[leLogger] :: LoggerEnv -> !Logger

-- | Current application component.
[leComponent] :: LoggerEnv -> !Text

-- | Current application domain.
[leDomain] :: LoggerEnv -> ![Text]

-- | Additional data to be merged with the log message's data.
[leData] :: LoggerEnv -> ![Pair]
type InnerLogT = ReaderT LoggerEnv

-- | Monad transformer that adds logging capabilities to the underlying
--   monad.
newtype LogT m a
LogT :: InnerLogT m a -> LogT m a
[unLogT] :: LogT m a -> InnerLogT m a

-- | Run a <a>LogT</a> computation.
--   
--   Note that in the case of asynchronous/bulk loggers <a>runLogT</a>
--   doesn't guarantee that all messages are actually written to the log
--   once it finishes. Use <tt>withPGLogger</tt> or
--   <tt>withElasticSearchLogger</tt> for that.
runLogT :: Text -> Logger -> LogT m a -> m a

-- | Transform the computation inside a <a>LogT</a>.
mapLogT :: (m a -> n b) -> LogT m a -> LogT n b
instance Control.Monad.Trans.Class.MonadTrans Log.Monad.LogT
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Log.Monad.LogT m)
instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Log.Monad.LogT m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Log.Monad.LogT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Log.Monad.LogT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Log.Monad.LogT m)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Log.Monad.LogT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Log.Monad.LogT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Log.Monad.LogT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Log.Monad.LogT m)
instance GHC.Base.Alternative m => GHC.Base.Alternative (Log.Monad.LogT m)
instance Control.Monad.Trans.Control.MonadTransControl Log.Monad.LogT
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Log.Monad.LogT m)
instance (Control.Monad.Base.MonadBase GHC.Types.IO m, Control.Monad.Time.MonadTime m) => Log.Class.MonadLog (Log.Monad.LogT m)


-- | Bulk stdout logging back-end, useful mainly for testing.
module Log.Backend.StandardOutput.Bulk

-- | Create a <a>bulkStdoutLogger</a> for the duration of the given action,
--   and shut it down afterwards, making sure that all buffered messages
--   are actually written to stdout.
withBulkStdOutLogger :: (Logger -> IO r) -> IO r

-- | Start an asynchronous logger thread that prints messages to standard
--   output.
--   
--   Please use <tt>withBulkStdOutLogger'</tt> instead, which is more
--   exception-safe (see the note attached to <a>mkBulkLogger</a>).

-- | <i>Deprecated: Use <a>withBulkStdOutLogger</a> instead!</i>
bulkStdoutLogger :: IO Logger


-- | Stdout logging back-end.
module Log.Backend.StandardOutput

-- | Simple, synchronous logger that prints messages to standard output.

-- | <i>Deprecated: Use <tt>withSimpleStdoutLogger</tt></i>
simpleStdoutLogger :: Logger

-- | Create a logger that prints messages to standard output.

-- | <i>Deprecated: Use <tt>withSimpleStdoutLogger</tt></i>
stdoutLogger :: IO Logger

-- | Create a <tt>simpleStdoutlogger</tt> for the duration of the given
--   action, making sure that stdout is flushed afterwards.
withSimpleStdOutLogger :: (Logger -> IO r) -> IO r


-- | PostgreSQL logging back-end.
module Log.Backend.PostgreSQL

-- | Start an asynchronous logger thread that inserts log messages into a
--   PostgreSQL database.
--   
--   Please use <tt>withPglogger</tt> instead, which is more exception-safe
--   (see the note attached to <a>mkBulkLogger</a>).

-- | <i>Deprecated: Use <a>withPgLogger</a> instead!</i>
pgLogger :: ConnectionSourceM IO -> IO Logger

-- | Create a <a>pgLogger</a> for the duration of the given action, and
--   shut it down afterwards, making sure that all buffered messages are
--   actually written to the DB.
withPgLogger :: ConnectionSourceM IO -> (Logger -> IO r) -> IO r
instance GHC.Enum.Enum Log.Backend.PostgreSQL.InvalidEncodingRecoveryAttempt


-- | Structured logging solution with multiple backends.
module Log

-- | Create a <a>Value</a> from a list of name/value <a>Pair</a>s. If
--   duplicate keys arise, earlier keys and their associated values win.
object :: [Pair] -> Value
(.=) :: KeyValue kv => forall v. ToJSON v => Text -> v -> kv


-- | Elasticsearch logging back-end.
module Log.Backend.ElasticSearch

-- | Configuration for the Elasticsearch <a>Logger</a>. See
--   <a>https://www.elastic.co/guide/en/elasticsearch/reference/current/glossary.html</a>
--   for the explanation of terms.
data ElasticSearchConfig
ElasticSearchConfig :: !Text -> !Text -> !Text -> ElasticSearchConfig

-- | Elasticsearch server address.
[esServer] :: ElasticSearchConfig -> !Text

-- | Elasticsearch index name.
[esIndex] :: ElasticSearchConfig -> !Text

-- | Elasticsearch mapping name.
[esMapping] :: ElasticSearchConfig -> !Text

-- | Sensible defaults for <a>ElasticSearchConfig</a>.
defaultElasticSearchConfig :: ElasticSearchConfig

-- | Create an <a>elasticSearchLogger</a> for the duration of the given
--   action, and shut it down afterwards, making sure that all buffered
--   messages are actually written to the Elasticsearch store.
withElasticSearchLogger :: ElasticSearchConfig -> IO Word32 -> (Logger -> IO r) -> IO r

-- | Start an asynchronous logger thread that stores messages using
--   Elasticsearch.
--   
--   Please use <a>withElasticSearchLogger</a> instead, which is more
--   exception-safe (see the note attached to <a>mkBulkLogger</a>).

-- | <i>Deprecated: Use <a>withElasticSearchLogger</a> instead!</i>
elasticSearchLogger :: ElasticSearchConfig -> IO Word32 -> IO Logger
instance GHC.Show.Show Log.Backend.ElasticSearch.ElasticSearchConfig
instance GHC.Classes.Eq Log.Backend.ElasticSearch.ElasticSearchConfig
instance Data.Aeson.Types.Class.ToJSON Log.Backend.ElasticSearch.LogsMapping