yet-another-logger-0.3.0: Yet Another Logger

CopyrightCopyright (c) 2014-2015 PivotCloud, Inc.
LicenseApache License, Version 2.0
MaintainerLars Kuhtz <lkuhtz@pivotmail.com>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

System.Logger.Types

Contents

Description

 

Synopsis

LogLevel

data LogLevel Source

Constructors

Quiet 
Error 
Warn 
Info 
Debug 

Instances

logLevelText :: IsString a => LogLevel -> a Source

readLogLevel :: (MonadError e m, Eq a, Show a, FoldCase a, IsString a, IsString e, Monoid e) => a -> m LogLevel Source

pLogLevel :: Parser LogLevel Source

pLogLevel_ Source

Arguments

:: Text

prefix for the command line options.

-> Parser LogLevel 

A version of pLogLevel that takes a prefix for the command line option.

Since: 0.2

LogPolicy

data LogPolicy Source

Policy that determines how the case of a congested logging pipeline is addressed.

Constructors

LogPolicyDiscard 
LogPolicyRaise 
LogPolicyBlock 

Instances

logPolicyText :: IsString s => LogPolicy -> s Source

readLogPolicy :: (MonadError e m, Eq a, Show a, FoldCase a, IsText a, IsString e, Monoid e) => a -> m LogPolicy Source

pLogPolicy :: Parser LogPolicy Source

pLogPolicy_ Source

Arguments

:: Text

prefix for the command line options.

-> Parser LogPolicy 

A version of pLogPolicy that takes a prefix for the command line option.

Since: 0.2

LogLabel

type LogLabel = (Text, Text) Source

type LogScope = [LogLabel] Source

Logger Exception

data LoggerException a where Source

Exceptions that are thrown by the logger

QueueFullException
thrown when the queue is full and the logger policy is set to throw exceptions on a full queue
BackendTerminatedException
a backend can throw this exception to force the logger immediately
BackendTooManyExceptions
thrown when the backend has thrown unexpected exceptions more than loggerConfigExceptionLimit times

Since: 0.2

Constructors

QueueFullException :: LogMessage a -> LoggerException a 
BackendTerminatedException :: SomeException -> LoggerException Void 
BackendTooManyExceptions :: [SomeException] -> LoggerException Void 

Instances

Logger Backend

data LogMessage a Source

The Internal log message type.

The type parameter a is expected to provide intances of Show, Typeable, and NFData.

If we need to support different backends, we may consider including the backend here...

Constructors

LogMessage 

Fields

_logMsg :: !a
 
_logMsgLevel :: !LogLevel
 
_logMsgScope :: !LogScope

efficiency of this depends on whether this is shared between log messsages. Usually this should be just a pointer to a shared list.

_logMsgTime :: !TimeSpec

a POSIX timestamp

UTC seconds elapsed since UNIX Epoch as returned by clock_gettime on the respective system. NOTE that POSIX is ambigious with regard to treatment of leap seconds, and some implementations may actually return TAI.

Since: 0.2

Instances

logMsg :: Lens (LogMessage a) (LogMessage b) a b Source

logMsgLevel :: Lens' (LogMessage a) LogLevel Source

logMsgScope :: Lens' (LogMessage a) LogScope Source

logMsgTime :: Lens' (LogMessage a) TimeSpec Source

Since: 0.2

type LoggerBackend a = Either (LogMessage Text) (LogMessage a) -> IO () Source

This is given to logger when it is created. It formats and delivers individual log messages synchronously. The backend is called once for each log message (that meets the required log level).

The type parameter a is expected to provide instances for Show Typeable, and NFData.

The Left values of the argument allows the generation of log messages that are independent of the parameter a. The motivation for this is reporting issues in Logging system itself, like a full logger queue or providing statistics about the fill level of the queue. There may be other uses of this, too.

Backends that can fail are encouraged (but not forced) to take into account the LogPolicy that is effective for a message. For instance, a backend may implement a reasonable retry logic for each message and then raise a BackendTerminatedException in case the policy is LogPolicyBlock or LogPolicyRaise (thus causing the logger to exit immediately) and raise some other exception otherwise (thus discarding the message without causing the logger to not exit immediately). In addition a backend might retry harder in case of LogPolicyBlock.

TODO there may be scenarios where chunked processing is beneficial. While this can be done in a closure of this function, more direct support might be desirable.

Logger Frontend

type LogFunction a m = LogLevel -> a -> m () Source

type LogFunctionIO a = LogLevel -> a -> IO () Source

This function is provided by the logger.

LoggerCtx

class LoggerCtx ctx msg | ctx -> msg where Source

Abstraction of a logger context that can be used without dependening on a specific monadic context.

The loggerFunIO incorporates a LoggerBackend. An instance of a LoggerCtx is free to use a hard coded LoggerBackend or to be usable with different LoggerBackend functions. The latter is recommended but not required.

You don't have to provide an instance of this for your logger. Instead you may just provide an instance of MonadLog directly.

If this doesn't fit your needs you may use a newtype wrapper and define your own instances.

Minimal complete definition

loggerFunIO, setLoggerLevel, setLoggerScope, setLoggerPolicy

Methods

loggerFunIO :: (Show msg, Typeable msg, NFData msg) => ctx -> LogFunctionIO msg Source

setLoggerLevel :: Setter' ctx LogLevel Source

setLoggerScope :: Setter' ctx LogScope Source

setLoggerPolicy :: Setter' ctx LogPolicy Source

withLoggerLevel :: LogLevel -> ctx -> (ctx -> α) -> α Source

withLoggerLabel :: LogLabel -> ctx -> (ctx -> α) -> α Source

withLoggerPolicy :: LogPolicy -> ctx -> (ctx -> α) -> α Source

Instances

data LoggerCtxT ctx m α Source

Instances

runLoggerCtxT :: LoggerCtxT ctx m α -> ctx -> m α Source

MonadLog

class Monad m => MonadLog a m | m -> a where Source

Methods

logg :: LogFunction a m Source

Log a message.

withLevel :: LogLevel -> m α -> m α Source

Run the inner computation with the given LogLevel

withPolicy :: LogPolicy -> m α -> m α Source

Run the inner computation with the given LogPolicy.

localScope :: (LogScope -> LogScope) -> m α -> m α Source

Run the inner computation with a modified LogScope.

Since: 0.1

Instances

(Show a, Typeable * a, NFData a, MonadIO m, LoggerCtx ctx a) => MonadLog a (LoggerCtxT ctx m) Source 
MonadLog a m => MonadLog a (StateT σ m) Source 
MonadLog a m => MonadLog a (ExceptT ε m) Source 
(Monoid σ, MonadLog a m) => MonadLog a (WriterT σ m) Source 

withLabel :: MonadLog a m => LogLabel -> m α -> m α Source

Append a LogLabel to the current LogScope when executing the inner computation. The LogScope of the outer computation is unchanged.

Since: 0.1

clearScope :: MonadLog a m => m α -> m α Source

Executing the inner computation with an empty LogScope. The LogScope of the outer computation is unchanged.

Since: 0.1

popLabel :: MonadLog a m => m α -> m α Source

Remove the last LogLabel from the current LogScope when executing the inner computation. The LogScope of the outer computation is unchanged.

Since: 0.1