Control.Monad.Logger

monad-logger-0.3.18: A class of monads which can log messages.

Safe Haskell | Trustworthy
Language | Haskell98

Control.Monad.Logger

Contents

- MonadLogger
- Re-export from fast-logger
- Helper transformer
- TH logging
- TH logging of showable values
- TH logging with source
- TH util
- Non-TH logging
- Non-TH logging with source
- utilities for defining your own loggers

Description

This module provides the facilities needed for a decoupled logging system.

The `MonadLogger` class is implemented by monads that give access to a logging facility. If you're defining a custom monad, then you may define an instance of `MonadLogger` that routes the log messages to the appropriate place (e.g., that's what `yesod-core`'s `GHandler` does). Otherwise, you may use the `LoggingT` monad included in this module (see `runStderrLoggingT`). To simply discard log message, use `NoLoggingT`.

As a user of the logging facility, we provide you some convenient Template Haskell splices that use the `MonadLogger` class. They will record their source file and position, which is very helpful when debugging. See `logDebug` for more information.

Synopsis

- class Monad m => MonadLogger m where
  - monadLoggerLog :: ToLogStr msg => Loc -> LogSource -> LogLevel -> msg -> m ()
- class (MonadLogger m, MonadIO m) => MonadLoggerIO m where
  - askLoggerIO :: m (Loc -> LogSource -> LogLevel -> LogStr -> IO ())
- data LogLevel
  - = LevelDebug
  - | LevelInfo
  - | LevelWarn
  - | LevelError
  - | LevelOther Text
- type LogSource = Text
- data LogStr :: *
- class ToLogStr msg where
  - toLogStr :: msg -> LogStr
- newtype LoggingT m a = LoggingT {
  - runLoggingT :: (Loc -> LogSource -> LogLevel -> LogStr -> IO ()) -> m a
  }
- runStderrLoggingT :: MonadIO m => LoggingT m a -> m a
- runStdoutLoggingT :: MonadIO m => LoggingT m a -> m a
- runChanLoggingT :: MonadIO m => Chan (Loc, LogSource, LogLevel, LogStr) -> LoggingT m a -> m a
- unChanLoggingT :: (MonadLogger m, MonadIO m) => Chan (Loc, LogSource, LogLevel, LogStr) -> m ()
- withChannelLogger :: (MonadBaseControl IO m, MonadIO m) => Int -> LoggingT m a -> LoggingT m a
- filterLogger :: (LogSource -> LogLevel -> Bool) -> LoggingT m a -> LoggingT m a
- newtype NoLoggingT m a = NoLoggingT {
  - runNoLoggingT :: m a
  }
- logDebug :: Q Exp
- logInfo :: Q Exp
- logWarn :: Q Exp
- logError :: Q Exp
- logOther :: Text -> Q Exp
- logDebugSH :: Q Exp
- logInfoSH :: Q Exp
- logWarnSH :: Q Exp
- logErrorSH :: Q Exp
- logOtherSH :: Text -> Q Exp
- logDebugS :: Q Exp
- logInfoS :: Q Exp
- logWarnS :: Q Exp
- logErrorS :: Q Exp
- logOtherS :: Q Exp
- liftLoc :: Loc -> Q Exp
- logDebugN :: MonadLogger m => Text -> m ()
- logInfoN :: MonadLogger m => Text -> m ()
- logWarnN :: MonadLogger m => Text -> m ()
- logErrorN :: MonadLogger m => Text -> m ()
- logOtherN :: MonadLogger m => LogLevel -> Text -> m ()
- logDebugNS :: MonadLogger m => Text -> Text -> m ()
- logInfoNS :: MonadLogger m => Text -> Text -> m ()
- logWarnNS :: MonadLogger m => Text -> Text -> m ()
- logErrorNS :: MonadLogger m => Text -> Text -> m ()
- logOtherNS :: MonadLogger m => Text -> LogLevel -> Text -> m ()
- defaultLogStr :: Loc -> LogSource -> LogLevel -> LogStr -> LogStr
- data Loc :: * = Loc {
  - loc_filename :: String
  - loc_package :: String
  - loc_module :: String
  - loc_start :: CharPos
  - loc_end :: CharPos
  }

# MonadLogger

class Monad m => MonadLogger m where

A `Monad` which has the ability to log messages in some manner.

Minimal complete definition

Nothing

Methods

monadLoggerLog :: ToLogStr msg => Loc -> LogSource -> LogLevel -> msg -> m ()

Instances

MonadLogger m => MonadLogger (MaybeT m) |
MonadLogger m => MonadLogger (ListT m) |
MonadLogger m => MonadLogger (ResourceT m) |
MonadLogger m => MonadLogger (IdentityT m) |
MonadIO m => MonadLogger (LoggingT m) |
Monad m => MonadLogger (NoLoggingT m) |
(MonadLogger m, Monoid w) => MonadLogger (WriterT w m) |
(MonadLogger m, Monoid w) => MonadLogger (WriterT w m) |
MonadLogger m => MonadLogger (StateT s m) |
MonadLogger m => MonadLogger (StateT s m) |
MonadLogger m => MonadLogger (ReaderT r m) |
(MonadLogger m, Error e) => MonadLogger (ErrorT e m) |
MonadLogger m => MonadLogger (ContT r m) |
MonadLogger m => MonadLogger (ExceptT e m) |
MonadLogger m => MonadLogger (ConduitM i o m) |
(MonadLogger m, Monoid w) => MonadLogger (RWST r w s m) |
(MonadLogger m, Monoid w) => MonadLogger (RWST r w s m) |
MonadLogger m => MonadLogger (Pipe l i o u m) |

class (MonadLogger m, MonadIO m) => MonadLoggerIO m where

An extension of `MonadLogger` for the common case where the logging action is a simple `IO` action. The advantage of using this typeclass is that the logging function itself can be extracted as a first-class value, which can make it easier to manipulate monad transformer stacks, as an example.

Since 0.3.10

Minimal complete definition

Nothing

Methods

askLoggerIO :: m (Loc -> LogSource -> LogLevel -> LogStr -> IO ())

Request the logging function itself.

Since 0.3.10

Instances

MonadLoggerIO m => MonadLoggerIO (MaybeT m) |
MonadLoggerIO m => MonadLoggerIO (ListT m) |
MonadLoggerIO m => MonadLoggerIO (ResourceT m) |
MonadLoggerIO m => MonadLoggerIO (IdentityT m) |
MonadIO m => MonadLoggerIO (LoggingT m) |
MonadIO m => MonadLoggerIO (NoLoggingT m) |
(MonadLoggerIO m, Monoid w) => MonadLoggerIO (WriterT w m) |
(MonadLoggerIO m, Monoid w) => MonadLoggerIO (WriterT w m) |
MonadLoggerIO m => MonadLoggerIO (StateT s m) |
MonadLoggerIO m => MonadLoggerIO (StateT s m) |
MonadLoggerIO m => MonadLoggerIO (ReaderT r m) |
(MonadLoggerIO m, Error e) => MonadLoggerIO (ErrorT e m) |
MonadLoggerIO m => MonadLoggerIO (ContT r m) |
MonadLoggerIO m => MonadLoggerIO (ExceptT e m) |
MonadLoggerIO m => MonadLoggerIO (ConduitM i o m) |
(MonadLoggerIO m, Monoid w) => MonadLoggerIO (RWST r w s m) |
(MonadLoggerIO m, Monoid w) => MonadLoggerIO (RWST r w s m) |
MonadLoggerIO m => MonadLoggerIO (Pipe l i o u m) |

data LogLevel

Constructors

LevelDebug |
LevelInfo |
LevelWarn |
LevelError |
LevelOther Text |

Instances

Eq LogLevel |
Ord LogLevel |
Read LogLevel |
Show LogLevel |
Lift LogLevel |

type LogSource = Text

# Re-export from fast-logger

data LogStr :: *

Log message builder. Use (`<>`) to append two LogStr in O(1).

Instances

IsString LogStr |
Monoid LogStr |
ToLogStr LogStr |

class ToLogStr msg where

Methods

toLogStr :: msg -> LogStr

Instances

ToLogStr String |
ToLogStr ByteString |
ToLogStr ByteString |
ToLogStr Text |
ToLogStr Text |
ToLogStr LogStr |

# Helper transformer

newtype LoggingT m a

Monad transformer that adds a new logging function.

Since 0.2.2

Constructors

LoggingT |
Fields runLoggingT :: (Loc -> LogSource -> LogLevel -> LogStr -> IO ()) -> m a

Instances

MonadTrans LoggingT |
MonadTransControl LoggingT |
MonadRWS r w s m => MonadRWS r w s (LoggingT m) |
MonadBaseControl b m => MonadBaseControl b (LoggingT m) |
MonadBase b m => MonadBase b (LoggingT m) |
MonadError e m => MonadError e (LoggingT m) |
MonadReader r m => MonadReader r (LoggingT m) |
MonadState s m => MonadState s (LoggingT m) |
MonadWriter w m => MonadWriter w (LoggingT m) |
Monad m => Monad (LoggingT m) |
Monad m => Functor (LoggingT m) |
Monad m => Applicative (LoggingT m) |
MonadActive m => MonadActive (LoggingT m) |
MonadThrow m => MonadThrow (LoggingT m) |
MonadCatch m => MonadCatch (LoggingT m) |
MonadMask m => MonadMask (LoggingT m) |
MonadIO m => MonadIO (LoggingT m) |
MonadCont m => MonadCont (LoggingT m) |
MonadResource m => MonadResource (LoggingT m) |
MonadIO m => MonadLoggerIO (LoggingT m) |
MonadIO m => MonadLogger (LoggingT m) |
type StT LoggingT a = a |
type StM (LoggingT m) a = StM m a |

runStderrLoggingT :: MonadIO m => LoggingT m a -> m a

Run a block using a `MonadLogger` instance which prints to stderr.

Since 0.2.2

runStdoutLoggingT :: MonadIO m => LoggingT m a -> m a

Run a block using a `MonadLogger` instance which prints to stdout.

Since 0.2.2

runChanLoggingT :: MonadIO m => Chan (Loc, LogSource, LogLevel, LogStr) -> LoggingT m a -> m a

Run a block using a `MonadLogger` instance which writes tuples to an unbounded channel.

The tuples can be extracted (ie. in another thread) with `unChanLoggingT` or a custom extraction funtion, and written to a destination.

Since: 0.3.17

unChanLoggingT :: (MonadLogger m, MonadIO m) => Chan (Loc, LogSource, LogLevel, LogStr) -> m ()

Read logging tuples from an unbounded channel and log them into a `MonadLoggerIO` monad, forever.

For use in a dedicated thread with a channel fed by `runChanLoggingT`.

Since: 0.3.17

withChannelLogger

Arguments

:: (MonadBaseControl IO m, MonadIO m) |
=> Int | Number of messages to keep
-> LoggingT m a |
-> LoggingT m a |

Within the `LoggingT` monad, capture all log messages to a bounded channel of the indicated size, and only actually log them if there is an exception.

Since 0.3.2

filterLogger :: (LogSource -> LogLevel -> Bool) -> LoggingT m a -> LoggingT m a

Only log messages passing the given predicate function.

This can be a convenient way, for example, to ignore debug level messages.

Since 0.3.13

newtype NoLoggingT m a

Monad transformer that disables logging.

Since 0.2.4

Constructors

NoLoggingT |
Fields runNoLoggingT :: m a

Instances

MonadTrans NoLoggingT |
MonadTransControl NoLoggingT |
MonadBaseControl b m => MonadBaseControl b (NoLoggingT m) |
MonadBase b m => MonadBase b (NoLoggingT m) |
MonadError e m => MonadError e (NoLoggingT m) |
MonadState s m => MonadState s (NoLoggingT m) |
MonadWriter w m => MonadWriter w (NoLoggingT m) |
Monad m => Monad (NoLoggingT m) |
Monad m => Functor (NoLoggingT m) |
Monad m => Applicative (NoLoggingT m) |
MonadActive m => MonadActive (NoLoggingT m) |
MonadThrow m => MonadThrow (NoLoggingT m) |
MonadCatch m => MonadCatch (NoLoggingT m) |
MonadMask m => MonadMask (NoLoggingT m) |
MonadIO m => MonadIO (NoLoggingT m) |
MonadResource m => MonadResource (NoLoggingT m) |
MonadIO m => MonadLoggerIO (NoLoggingT m) |
Monad m => MonadLogger (NoLoggingT m) |
type StT NoLoggingT a = a |
type StM (NoLoggingT m) a = StM m a |

# TH logging

logDebug :: Q Exp

Generates a function that takes a `Text` and logs a `LevelDebug` message. Usage:

    $(logDebug) "This is a debug log message"

logInfo :: Q Exp

See `logDebug`

logWarn :: Q Exp

See `logDebug`

logError :: Q Exp

See `logDebug`

logOther :: Text -> Q Exp

Generates a function that takes a `Text` and logs a `LevelOther` message. Usage:

    $(logOther "My new level") "This is a log message"

# TH logging of showable values

logDebugSH :: Q Exp

Generates a function that takes a 'Show a => a' and logs a `LevelDebug` message. Usage:

    $(logDebugSH) (Just "This is a debug log message")

Since: 0.3.18

logInfoSH :: Q Exp

See `logDebugSH`

logWarnSH :: Q Exp

See `logDebugSH`

logErrorSH :: Q Exp

See `logDebugSH`

logOtherSH :: Text -> Q Exp

Generates a function that takes a 'Show a => a' and logs a `LevelOther` message. Usage:

    $(logOtherSH "My new level") "This is a log message"

# TH logging with source

logDebugS :: Q Exp

Generates a function that takes a `LogSource` and `Text` and logs a `LevelDebug` message. Usage:

    $logDebugS "SomeSource" "This is a debug log message"

logInfoS :: Q Exp

See `logDebugS`

logWarnS :: Q Exp

See `logDebugS`

logErrorS :: Q Exp

See `logDebugS`

logOtherS :: Q Exp

Generates a function that takes a `LogSource`, a level name and a `Text` and logs a `LevelOther` message. Usage:

    $logOtherS "SomeSource" "My new level" "This is a log message"

# TH util

liftLoc :: Loc -> Q Exp

Lift a location into an Exp.

Since 0.3.1

# Non-TH logging

logDebugN :: MonadLogger m => Text -> m ()

logInfoN :: MonadLogger m => Text -> m ()

logWarnN :: MonadLogger m => Text -> m ()

logErrorN :: MonadLogger m => Text -> m ()

logOtherN :: MonadLogger m => LogLevel -> Text -> m ()

# Non-TH logging with source

logDebugNS :: MonadLogger m => Text -> Text -> m ()

logInfoNS :: MonadLogger m => Text -> Text -> m ()

logWarnNS :: MonadLogger m => Text -> Text -> m ()

logErrorNS :: MonadLogger m => Text -> Text -> m ()

logOtherNS :: MonadLogger m => Text -> LogLevel -> Text -> m ()

# utilities for defining your own loggers

defaultLogStr :: Loc -> LogSource -> LogLevel -> LogStr -> LogStr

data Loc :: *

Constructors

Loc |
Fields loc_filename :: String loc_package :: String loc_module :: String loc_start :: CharPos loc_end :: CharPos

Instances

Eq Loc |
Data Loc |
Ord Loc |
Show Loc |
Generic Loc |
type Rep Loc = D1 D1Loc (C1 C1_0Loc ((:*:) ((:*:) (S1 S1_0_0Loc (Rec0 String)) (S1 S1_0_1Loc (Rec0 String))) ((:*:) (S1 S1_0_2Loc (Rec0 String)) ((:*:) (S1 S1_0_3Loc (Rec0 CharPos)) (S1 S1_0_4Loc (Rec0 CharPos)))))) |