Lumberjack

This module defines a general logging facility that can be used to output log messages to various targets.

The LogAction is the fundamental operation that decides how to log a provided message.

Code wishing to output a logged message simply uses the LogAction object:

writeLog action msg

For convenience, the LogAction can be stored in the local operating monad context, from which it can be retrieved (and modified). A monad which can supply a LogAction is a member of the HasLog class, and the writeLogM function will automatically retrieve the LogAction from the monad and write to it:

writeLogM msg

LogActions can be combined via Semigroup operations (<>) and the resulting LogAction will perform both actions with each message. The Monoidal mempty LogAction simply does nothing. For example, logging to both a file and stdout can be done by logToFile <> logToStdout.

LogActions are also Contravariant (and Divisible and Decidable) to allow easy conversion of a LogAction for the base message type into a LogAction for a different message type (or types) that can be converted to (and combined into) the base message type.

Interface for Logging

newtype LogAction m msg

The LogAction holds the ability to log a message of type msg (the second parameter) via a monad m (the first parameter).

LogActions are semigroup and monoid combineable, which results in both LogActions being taken (or no action in the case of mempty), and contravariant to allow the msg to be modified via function prior to being logged (as well as Divisible and Decidable).

Constructors

LogAction

Fields

• writeLog :: msg -> m ()

Instances

Contravariant (LogAction m)

Defined in Lumberjack

Methods

contramap :: (a' -> a) -> LogAction m a -> LogAction m a'

(>$) :: b -> LogAction m b -> LogAction m a

Applicative m => Decidable (LogAction m)

Defined in Lumberjack

Methods

lose :: (a -> Void) -> LogAction m a

choose :: (a -> Either b c) -> LogAction m b -> LogAction m c -> LogAction m a

Applicative m => Divisible (LogAction m)

Defined in Lumberjack

Methods

divide :: (a -> (b, c)) -> LogAction m b -> LogAction m c -> LogAction m a

conquer :: LogAction m a

Applicative m => Monoid (LogAction m a)

Defined in Lumberjack

Methods

mempty :: LogAction m a

mappend :: LogAction m a -> LogAction m a -> LogAction m a

mconcat :: [LogAction m a] -> LogAction m a

Applicative m => Semigroup (LogAction m a)

Defined in Lumberjack

Methods

(<>) :: LogAction m a -> LogAction m a -> LogAction m a

sconcat :: NonEmpty (LogAction m a) -> LogAction m a

stimes :: Integral b => b -> LogAction m a -> LogAction m a

class Monad m => HasLog msg m where

Any monad which will support retrieving a LogAction from the Monad's environment should support the HasLog class.

Methods

getLogAction :: m (LogAction m msg)

class (Monad m, HasLog msg m) => LoggingMonad msg m where

An instance of the LoggingMonad class can be defined for the base monadic logging action to allow adjusting that logging action. This class can only be instantiated (and only needs to be instantiated) for the base message type; all other message types will use contramapping to convert their message type to the LoggingMonad base message type.

Methods

adjustLogAction :: (forall k. LogAction k msg -> LogAction k msg) -> m a -> m a

writeLogM :: HasLog msg m => msg -> m ()

This obtains the LogAction from the current monad's environment to use for outputting the log message. Most code will use this function.

Logging Utilities

safeLogAction :: MonadCatch m => LogAction m msg -> LogAction m msg

Ensures that the LogAction does not fail if the logging operation itself throws an exception (the exception is ignored).

logFilter :: Applicative m => (msg -> Bool) -> LogAction m msg -> LogAction m msg

The logFilter can be used on a LogAction to determine which messages the LogAction should be invoked for (only those for which the filter function returns True).

LogMessage rich logging type

This is an enhanced message type for the LogAction, containing various auxiliary information associated with the log message. While Lumberjack can be used with other message types, this message type should provide support for most of the common logging auxiliary data and can therefore be used "out of the box".

data Severity

The Severity indicates the relative importance of the logging message. This can be useful for filtering log messages.

Constructors

Debug

Info

Warning

Error

Instances

Show Severity

Defined in Lumberjack

Methods

showsPrec :: Int -> Severity -> ShowS

show :: Severity -> String

showList :: [Severity] -> ShowS

Eq Severity

Defined in Lumberjack

Methods

(==) :: Severity -> Severity -> Bool

(/=) :: Severity -> Severity -> Bool

Ord Severity

Defined in Lumberjack

Methods

compare :: Severity -> Severity -> Ordering

(<) :: Severity -> Severity -> Bool

(<=) :: Severity -> Severity -> Bool

(>) :: Severity -> Severity -> Bool

(>=) :: Severity -> Severity -> Bool

max :: Severity -> Severity -> Severity

min :: Severity -> Severity -> Severity

Pretty Severity

Defined in Lumberjack

Methods

pretty :: Severity -> Doc ann

prettyList :: [Severity] -> Doc ann

data LogType

The LogType indicates what type of message this is. These are printed on the log line and can be used for filtering different types of log messages.

Constructors

Progress

FuncEntry

FuncExit

MiscLog

UserOp

Instances

Show LogType

Defined in Lumberjack

Methods

showsPrec :: Int -> LogType -> ShowS

show :: LogType -> String

showList :: [LogType] -> ShowS

Eq LogType

Defined in Lumberjack

Methods

(==) :: LogType -> LogType -> Bool

(/=) :: LogType -> LogType -> Bool

Pretty LogType

Defined in Lumberjack

Methods

pretty :: LogType -> Doc ann

prettyList :: [LogType] -> Doc ann

data LogMessage

Each logged output is described by a LogMessage object.

Constructors

LogMessage

Fields

• logType :: LogType
• logLevel :: Severity
• logTime :: UTCTime
• logTags :: [(Text, Text)]
• logText :: Text

Instances

Monoid LogMessage

Defined in Lumberjack

Methods

mempty :: LogMessage

mappend :: LogMessage -> LogMessage -> LogMessage

mconcat :: [LogMessage] -> LogMessage

Semigroup LogMessage

Defined in Lumberjack

Methods

(<>) :: LogMessage -> LogMessage -> LogMessage

sconcat :: NonEmpty LogMessage -> LogMessage

stimes :: Integral b => b -> LogMessage -> LogMessage

Pretty LogMessage

Defined in Lumberjack

Methods

pretty :: LogMessage -> Doc ann

prettyList :: [LogMessage] -> Doc ann

msgWith :: LogMessage

Helper routine to return an empty LogMessage, whose fields can then be updated.

type WithLog msg m = HasLog msg m

This type is a Constraint that should be applied to any client function that will perform logging in a monad context. The msg is the type of message that will be logged, and the m is the monad under which the logging is performed.

withLogTag :: LoggingMonad LogMessage m => Text -> Text -> m a -> m a

Log messages can have any number of key/value tags applied to them. This function establishes a new key/value tag pair that will be in effect for the monadic operation passed as the third argument. withLogTag tname tval op = local (adjustLogAction $ addLogTag tname tval) op

addLogActionTime :: MonadIO m => LogAction m LogMessage -> LogAction m LogMessage

Add the current timestamp to the LogMessage being logged

Output formatting for LogMessage

When the LogMessage logging type is used, Lumberjack provides a standard set of output formatting functions. The output uses the prettyprinter package to generate Doc output with annotations specifying the type of markup to be applied to various portions of the output.

There are multiple rendering functions that can be supplied as contramap converters to the base LogAction. One rendering function outputs a log message in plain text, while the other uses the prettyprinter-ansi-terminal package to generate various ANSI highlighting and color codes for writing enhanced output to a TTY.

cvtLogMessageToPlainText :: LogMessage -> Text

Standard LogMessage rendering function for converting a LogMessage into plain Text (no colors or other highlighting). This can be used as the default converter for a logger (via contramap).

cvtLogMessageToANSITermText :: LogMessage -> Text

Standard LogMessage rendering function to convert a LogMessage into Text with ANSI terminal colors and bolding and other styling. This can be used as the default converter for a logger (via contramap).

Helpers and convenience functions

These functions are not part of the core Logging implementation, but can be useful to clients to perform common or default operations.

(|#) :: (LogMessage -> a) -> Text -> a infixr 0

This operator is a convenient infix operator for logging a Text message. This is especially useful when used in conjunction with the OverloadedStrings language pragma:

>>> warning|# "This is your last warning"
>>> error|# "Failure has occurred"

logFunctionCall :: MonadIO m => LogAction m LogMessage -> Text -> m a -> m a

A wrapper for a function call that will call the provided LogAction with a Debug log on entry to the function and an Info log on exit from the function. The total amount of time taken during execution of the function will be included in the exit log message. No strictness is applied to the invoked monadic operation, so the time taken may be misleading. Like logFunctionCallM but needs an explicit LogAction whereas logFunctionCallM will retrieve the LogAction from the current monadic context.

logFunctionCallM :: (MonadIO m, WithLog LogMessage m) => Text -> m a -> m a

A wrapper for a monadic function call that will Debug log on entry to and Info log on exit from the function. The exit log will also note the total amount of time taken during execution of the function. Be advised that no strictness is applied to the internal monadic operation, so the time taken may be misleading.

logProgress :: MonadIO m => LogAction m LogMessage -> Text -> m ()

Called to output a log message to indicate that some progress in the current activity has been made.

logProgressM :: (MonadIO m, WithLog LogMessage m) => Text -> m ()

Called to output a log message within a HasLog monad to indicate that some progress in the current activity has been made.

tshow :: Show a => a -> Text

This is a helper function. The LogMessage normally wants a Text, but show delivers a String, so tshow can be used to get the needed format.

defaultGetIOLogAction :: MonadIO m => LogAction m Text

When using a simple IO monad, there is no ability to store a LogAction in the base monad. The client can specify a specific HasLog instance for IO that is appropriate to that client, and that HasLog can optionally use the defaultGetIOLogAction as the getLogAction implementation to log pretty messages with ANSI styling to stdout.

instance HasLog Env Text IO where
    getLogAction = return defaultGetIOLogAction

Orphan instances

Pretty UTCTime

Methods

pretty :: UTCTime -> Doc ann

prettyList :: [UTCTime] -> Doc ann