-- 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.4 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: -- --
-- 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)