-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A mtl-style monad transformer for general purpose & compositional logging -- -- A mtl-style monad transformer for general purpose & compositional -- logging @package logging-effect @version 1.2.2 module Control.Monad.Log -- | Append a message to the log for this computation. logMessage :: MonadLog message m => message -> m () -- | Re-interpret the log messages in one computation. This can be useful -- to embed a computation with one log type in a larger general -- computation. mapLogMessage :: MonadLog message' m => (message -> message') -> LoggingT message m a -> m a -- | Monadic version of mapLogMessage. This can be used to annotate -- a message with something that can only be computed in a monad. See -- e.g. timestamp. mapLogMessageM :: MonadLog message' m => (message -> m message') -> LoggingT message m a -> m a -- | The class of monads that support logging. -- -- Laws: -- -- Monoid homomorphism: -- --
--   logMessageFree a *> logMessageFree b = logMessageFree (a <> b)
--   
class Monad m => MonadLog message m | m -> message -- | Fold log messages into this computation. Looking to just log a -- message? You probably want logMessage. -- -- The perhaps strange type here allows us to construct a monoid out of -- any type of log message. You can think of this as the simpler -- type: -- --
--   logMessageFree :: [message] -> m ()
--   
logMessageFree :: MonadLog message m => (forall n. Monoid n => (message -> n) -> n) -> m () -- | Fold log messages into this computation. Looking to just log a -- message? You probably want logMessage. -- -- The perhaps strange type here allows us to construct a monoid out of -- any type of log message. You can think of this as the simpler -- type: -- --
--   logMessageFree :: [message] -> m ()
--   
logMessageFree :: (MonadLog message m, m ~ t n, MonadTrans t, MonadLog message n) => (forall mon. Monoid mon => (message -> mon) -> mon) -> m () -- |
--   logDebug = logMessage . WithSeverity Debug
--   
logDebug :: MonadLog (WithSeverity a) m => a -> m () -- |
--   logInfo = logMessage . WithSeverity Informational
--   
logInfo :: MonadLog (WithSeverity a) m => a -> m () -- |
--   logNotice = logMessage . WithSeverity Notice
--   
logNotice :: MonadLog (WithSeverity a) m => a -> m () -- |
--   logWarning = logMessage . WithSeverity Warning
--   
logWarning :: MonadLog (WithSeverity a) m => a -> m () -- |
--   logError = logMessage . WithSeverity Error
--   
logError :: MonadLog (WithSeverity a) m => a -> m () -- |
--   logCritical = logMessage . WithSeverity Critical
--   
logCritical :: MonadLog (WithSeverity a) m => a -> m () -- |
--   logAlert = logMessage . WithSeverity Alert
--   
logAlert :: MonadLog (WithSeverity a) m => a -> m () -- |
--   logEmergency = logMessage . WithSeverity Emergency
--   
logEmergency :: MonadLog (WithSeverity a) m => a -> m () -- | This is the default pretty printer which is used by show, -- putDoc and hPutDoc. (renderPretty ribbonfrac width -- x) renders document x with a page width of -- width and a ribbon width of (ribbonfrac * width) -- characters. The ribbon width is the maximal amount of non-indentation -- characters on a line. The parameter ribbonfrac should be -- between 0.0 and 1.0. If it is lower or higher, the -- ribbon width will be 0 or width respectively. renderPretty :: Float -> Int -> Doc -> SimpleDoc -- | Add a timestamp to log messages. -- -- Note that while most log message transformers are designed to be used -- at the point of logging, this transformer is best applied within the -- handler. This is advised as timestamps are generally applied -- uniformly, so doing it in the handler is fine (no extra information or -- context of the program is required). The other reason is that logging -- with a timestamp requires MonadIO - while the rest of your -- computation is free to use MonadIO, it's best to avoid -- incurring this constraint as much as possible, as it is generally -- untestable. data WithTimestamp a WithTimestamp :: a -> UTCTime -> WithTimestamp a -- | View the underlying message. [discardTimestamp] :: WithTimestamp a -> a -- | Retireve the time a message was logged. [msgTimestamp] :: WithTimestamp a -> UTCTime -- | Add the current time as a timestamp to a message. timestamp :: (MonadIO m) => a -> m (WithTimestamp a) -- | Given a way to render the underlying message a and a way to -- format UTCTime, render a message with its timestamp. -- --
--   >>> renderWithTimestamp (formatTime defaultTimeLocale rfc822DateFormat) id timestamppedLogMessage
--   [Tue, 19 Jan 2016 11:29:42 UTC] Setting target speed to plaid
--   
renderWithTimestamp :: (UTCTime -> String) -> (a -> Doc) -> (WithTimestamp a -> Doc) -- | Add "Severity" information to a log message. This is often used to -- convey how significant a log message is. data WithSeverity a WithSeverity :: Severity -> a -> WithSeverity a -- | Retrieve the Severity a message. [msgSeverity] :: WithSeverity a -> Severity -- | View the underlying message. [discardSeverity] :: WithSeverity a -> a -- | Classes of severity for log messages. These have been chosen to match -- syslog severity levels data Severity -- | System is unusable. By syslog convention, this level should -- not be used by applications. Emergency :: Severity -- | Should be corrected immediately. Alert :: Severity -- | Critical conditions. Critical :: Severity -- | Error conditions. Error :: Severity -- | May indicate that an error will occur if action is not taken. Warning :: Severity -- | Events that are unusual, but not error conditions. Notice :: Severity -- | Normal operational messages that require no action. Informational :: Severity -- | Information useful to developers for debugging the application. Debug :: Severity -- | Given a way to render the underlying message a, render a -- message with its severity. -- --
--   >>> renderWithSeverity id (WithSeverity Informational "Flux capacitor is functional")
--   [Informational] Flux capacitor is functional
--   
renderWithSeverity :: (a -> Doc) -> (WithSeverity a -> Doc) -- | Add call stack information to log lines. -- -- This functional requires that you pass around the call stack via -- implicit parameters. For more information, see the GHC manual (section -- 9.14.4.5). data WithCallStack a WithCallStack :: CallStack -> a -> WithCallStack a [msgCallStack] :: WithCallStack a -> CallStack [discardCallStack] :: WithCallStack a -> a -- | Construct a WithCallStack log message. -- -- This should normally be preferred over just using WithCallStack -- as it will append a new entry to the stack - pointing to this exact -- log line. However, if you are creating a combinator (such as a wrapper -- that logs and throws an exception), you may be better manually -- capturing the CallStack and using WithCallStack. withCallStack :: (?stack :: CallStack) => a -> WithCallStack a -- | Given a way to render the underlying message a render a -- message with a callstack. -- -- The callstack will be pretty-printed underneath the log message -- itself. renderWithCallStack :: (a -> Doc) -> WithCallStack a -> Doc -- | LoggingT is a very general handler for the MonadLog -- effect. Whenever a log entry is emitted, the given Handler is -- invoked, producing some side-effect (such as writing to -- stdout, or appending a database table). newtype LoggingT message m a LoggingT :: (ReaderT (Handler m message) m a) -> LoggingT message m a -- | Given a Handler for a given message, interleave this -- Handler into the underlying m computation whenever -- logMessage is called. runLoggingT :: LoggingT message m a -> Handler m message -> m a -- | LoggingT unfortunately does admit an instance of the -- MFunctor type class, which provides the hoist method -- to change the monad underneath a monad transformer. However, it is -- possible to do this with LoggingT provided that you have a way -- to re-interpret a log handler in the original monad. mapLoggingT :: (forall x. (Handler m message -> m x) -> (Handler n message' -> n x)) -> LoggingT message m a -> LoggingT message' n a -- | Handlers are mechanisms to interpret the meaning of logging as an -- action in the underlying monad. They are simply functions from log -- messages to m-actions. type Handler m message = message -> m () -- | withFDHandler creates a new Handler that will append a -- given file descriptor (or Handle, as it is known in the "base" -- library). Note that this Handler requires log messages to be of -- type Doc. This abstractly specifies a pretty-printing for log -- lines. The two arguments two withFDHandler determine how this -- pretty-printing should be realised when outputting log lines. -- -- These Handlers asynchronously log messages to the given file -- descriptor, rather than blocking. withFDHandler :: (MonadIO io, MonadMask io) => BatchingOptions -> Handle -> Float -> Int -> (Handler io Doc -> io a) -> io a -- | Create a new batched handler. Batched handlers take batches of -- messages to log at once, which can be more performant than logging -- each individual message. -- -- A batched handler flushes under three criteria: -- --
    --
  1. The flush interval has elapsed and the queue is not empty.
  2. --
  3. The queue has become full and needs to be flushed.
  4. --
  5. The scope of withBatchedHandler is exited.
  6. --
-- -- Batched handlers queue size and flush period can be configured via -- BatchingOptions. withBatchedHandler :: (MonadIO io, MonadMask io) => BatchingOptions -> (NonEmpty message -> IO ()) -> (Handler io message -> io a) -> io a -- | Options that be used to configure withBatchingHandler. data BatchingOptions BatchingOptions :: Int -> Int -> Bool -> BatchingOptions -- | The maximum amount of time to wait between flushes [flushMaxDelay] :: BatchingOptions -> Int -- | The maximum amount of messages to hold in memory between flushes} [flushMaxQueueSize] :: BatchingOptions -> Int -- | If the Handler becomes full, logMessage will block until -- the queue is flushed if blockWhenFull is True, otherwise -- it will drop that message and continue. [blockWhenFull] :: BatchingOptions -> Bool -- | Defaults for BatchingOptions -- --
--   defaultBatchingOptions = BatchingOptions {flushMaxDelay = 1000000
--                                            ,flushMaxQueueSize = 100
--                                            ,blockWhenFull = True}
--   
defaultBatchingOptions :: BatchingOptions -- | A MonadLog handler optimised for pure usage. Log messages are -- accumulated strictly, given that messasges form a Monoid. newtype PureLoggingT log m a MkPureLoggingT :: (StateT log m a) -> PureLoggingT log m a -- | Run a computation with access to logging by accumulating a log under -- its Monoid instance. runPureLoggingT :: Monoid log => PureLoggingT log m a -> m (a, log) -- | A MonadLog handler that throws messages away. -- -- The documentation may appear a bit confusing, but note that the full -- type of discardLogging is: -- --
--   discardLogging :: DiscardLoggingT messsage m a -> m a
--   
newtype DiscardLoggingT message m a DiscardLoggingT :: m a -> DiscardLoggingT message m a -- | Run a MonadLog computation by throwing away all log requests. [discardLogging] :: DiscardLoggingT message m a -> m a instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Control.Monad.Log.DiscardLoggingT message m) instance (Control.Monad.State.Class.MonadState s m, Control.Monad.Writer.Class.MonadWriter w m, Control.Monad.Reader.Class.MonadReader r m) => Control.Monad.RWS.Class.MonadRWS r w s (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Log.DiscardLoggingT message m) instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Control.Monad.Log.DiscardLoggingT message m) instance GHC.Base.Alternative m => GHC.Base.Alternative (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Log.DiscardLoggingT message m) instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Log.DiscardLoggingT message m) instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.Log.DiscardLoggingT message m) instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Log.DiscardLoggingT message m) instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Control.Monad.Log.PureLoggingT log m) instance GHC.Base.MonadPlus m => GHC.Base.Alternative (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Log.PureLoggingT log m) instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Log.PureLoggingT log m) instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Log.PureLoggingT log m) instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Log.PureLoggingT log m) instance GHC.Show.Show Control.Monad.Log.BatchingOptions instance GHC.Read.Read Control.Monad.Log.BatchingOptions instance GHC.Classes.Ord Control.Monad.Log.BatchingOptions instance GHC.Classes.Eq Control.Monad.Log.BatchingOptions instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Log.LoggingT message m) instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Log.LoggingT message m) instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Log.LoggingT message m) instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Log.LoggingT message m) instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Control.Monad.Log.LoggingT message m) instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Log.LoggingT message m) instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Log.LoggingT message m) instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Log.LoggingT message m) instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Control.Monad.Log.LoggingT message m) instance GHC.Base.Alternative m => GHC.Base.Alternative (Control.Monad.Log.LoggingT message m) instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Log.LoggingT message m) instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Log.LoggingT message m) instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.Log.LoggingT message m) instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Log.LoggingT message m) instance GHC.Show.Show a => GHC.Show.Show (Control.Monad.Log.WithCallStack a) instance Data.Foldable.Foldable Control.Monad.Log.WithCallStack instance Data.Traversable.Traversable Control.Monad.Log.WithCallStack instance GHC.Base.Functor Control.Monad.Log.WithCallStack instance Data.Foldable.Foldable Control.Monad.Log.WithTimestamp instance Data.Traversable.Traversable Control.Monad.Log.WithTimestamp instance GHC.Base.Functor Control.Monad.Log.WithTimestamp instance GHC.Show.Show a => GHC.Show.Show (Control.Monad.Log.WithTimestamp a) instance GHC.Read.Read a => GHC.Read.Read (Control.Monad.Log.WithTimestamp a) instance GHC.Classes.Ord a => GHC.Classes.Ord (Control.Monad.Log.WithTimestamp a) instance GHC.Classes.Eq a => GHC.Classes.Eq (Control.Monad.Log.WithTimestamp a) instance Data.Foldable.Foldable Control.Monad.Log.WithSeverity instance Data.Traversable.Traversable Control.Monad.Log.WithSeverity instance GHC.Base.Functor Control.Monad.Log.WithSeverity instance GHC.Show.Show a => GHC.Show.Show (Control.Monad.Log.WithSeverity a) instance GHC.Read.Read a => GHC.Read.Read (Control.Monad.Log.WithSeverity a) instance GHC.Classes.Ord a => GHC.Classes.Ord (Control.Monad.Log.WithSeverity a) instance GHC.Classes.Eq a => GHC.Classes.Eq (Control.Monad.Log.WithSeverity a) instance GHC.Classes.Ord Control.Monad.Log.Severity instance GHC.Show.Show Control.Monad.Log.Severity instance GHC.Read.Read Control.Monad.Log.Severity instance GHC.Enum.Bounded Control.Monad.Log.Severity instance GHC.Enum.Enum Control.Monad.Log.Severity instance GHC.Classes.Eq Control.Monad.Log.Severity instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Log.DiscardLoggingT message) instance (GHC.Base.Functor f, Control.Monad.Free.Class.MonadFree f m) => Control.Monad.Free.Class.MonadFree f (Control.Monad.Log.DiscardLoggingT message m) instance GHC.Base.Monad m => Control.Monad.Log.MonadLog message (Control.Monad.Log.DiscardLoggingT message m) instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Control.Monad.Log.PureLoggingT message m) instance Control.Monad.Trans.Control.MonadTransControl (Control.Monad.Log.PureLoggingT message) instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Log.PureLoggingT message m) instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Log.PureLoggingT log) instance (GHC.Base.Functor f, Control.Monad.Free.Class.MonadFree f m) => Control.Monad.Free.Class.MonadFree f (Control.Monad.Log.PureLoggingT log m) instance (GHC.Base.Monad m, GHC.Base.Monoid log) => Control.Monad.Log.MonadLog log (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.RWS.Class.MonadRWS r w s m => Control.Monad.RWS.Class.MonadRWS r w s (Control.Monad.Log.PureLoggingT message m) instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Log.PureLoggingT log m) instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Control.Monad.Log.LoggingT message m) instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Control.Monad.Log.LoggingT message m) instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Log.LoggingT message) instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Log.LoggingT message m) instance GHC.Base.Monad m => Control.Monad.Log.MonadLog message (Control.Monad.Log.LoggingT message m) instance Control.Monad.RWS.Class.MonadRWS r w s m => Control.Monad.RWS.Class.MonadRWS r w s (Control.Monad.Log.LoggingT message m) instance (GHC.Base.Functor f, Control.Monad.Free.Class.MonadFree f m) => Control.Monad.Free.Class.MonadFree f (Control.Monad.Log.LoggingT message m) instance GHC.Base.Applicative m => GHC.Base.Monoid (Control.Monad.Log.Ap m) instance Text.PrettyPrint.Leijen.Text.Pretty Control.Monad.Log.Severity instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Identity.IdentityT m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Reader.ReaderT r m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.State.Strict.StateT s m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.State.Lazy.StateT s m) instance (GHC.Base.Monoid w, Control.Monad.Log.MonadLog message m) => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Writer.Strict.WriterT w m) instance (GHC.Base.Monoid w, Control.Monad.Log.MonadLog message m) => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Writer.Lazy.WriterT w m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Maybe.MaybeT m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Except.ExceptT e m) instance (Control.Monad.Trans.Error.Error e, Control.Monad.Log.MonadLog message m) => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Error.ErrorT e m) instance (GHC.Base.Monoid w, Control.Monad.Log.MonadLog message m) => Control.Monad.Log.MonadLog message (Control.Monad.Trans.RWS.Strict.RWST r w s m) instance (GHC.Base.Monoid w, Control.Monad.Log.MonadLog message m) => Control.Monad.Log.MonadLog message (Control.Monad.Trans.RWS.Lazy.RWST r w s m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Cont.ContT r m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Trans.List.ListT m) instance (GHC.Base.Functor f, Control.Monad.Log.MonadLog message m) => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Free.FreeT f m) instance (GHC.Base.Functor f, Control.Monad.Log.MonadLog message m) => Control.Monad.Log.MonadLog message (Control.Monad.Trans.Free.Church.FT f m) instance Control.Monad.Log.MonadLog message m => Control.Monad.Log.MonadLog message (Control.Monad.Catch.Pure.CatchT m)