Control.Eff.Log.Handler

A memory efficient, streaming, logging effect with support for efficiently not logging when no logs are required.

Good support for logging to a file or to the network, as well as asynchronous logging in another thread.

Logging API

Sending Log Messages

logMsg :: forall e. (HasCallStack, Member Logs e) => LogMessage -> Eff e ()

Log a message.

All logging goes through this function.

This function is the only place where the LogPredicate is applied.

Also, LogMessages are evaluated using deepseq, after they pass the LogPredicate.

logWithSeverity :: forall e. (HasCallStack, Member Logs e) => Severity -> Text -> Eff e ()

Log a Text as LogMessage with a given Severity.

logWithSeverity' :: forall e. (HasCallStack, Member Logs e) => Severity -> String -> Eff e ()

Log a Text as LogMessage with a given Severity.

logEmergency :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a String as emergencySeverity.

logEmergency' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a String as emergencySeverity.

logAlert :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a message with alertSeverity.

logAlert' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a message with alertSeverity.

logCritical :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a criticalSeverity message.

logCritical' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a criticalSeverity message.

logError :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a errorSeverity message.

logError' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a errorSeverity message.

logWarning :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a warningSeverity message.

logWarning' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a warningSeverity message.

logNotice :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a noticeSeverity message.

logNotice' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a noticeSeverity message.

logInfo :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a informationalSeverity message.

logInfo' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a informationalSeverity message.

logDebug :: forall e. (HasCallStack, Member Logs e) => Text -> Eff e ()

Log a debugSeverity message.

logDebug' :: forall e. (HasCallStack, Member Logs e) => String -> Eff e ()

Log a debugSeverity message.

Log Message Pre-Filtering

includeLogMessages :: forall e a. Member Logs e => LogPredicate -> Eff e a -> Eff e a

Include LogMessages that match a LogPredicate.

excludeLogMessages p allows log message to be logged if p m

Although it is enough if the previous predicate holds. See excludeLogMessages and modifyLogPredicate.

See Control.Eff.Log

excludeLogMessages :: forall e a. Member Logs e => LogPredicate -> Eff e a -> Eff e a

Exclude LogMessages that match a LogPredicate.

excludeLogMessages p discards logs if p m

Also the previous predicate must also hold for a message to be logged. See excludeLogMessages and modifyLogPredicate.

See Control.Eff.Log

setLogPredicate :: forall r b. (Member Logs r, HasCallStack) => LogPredicate -> Eff r b -> Eff r b

Keep only those messages, for which a predicate holds.

E.g. to keep only messages which begin with OMG:

exampleLogPredicate :: IO Int
exampleLogPredicate =
    runLift
  $ withLogging consoleLogWriter
  $ do logMsg "test"
       setLogPredicate (\ msg -> case view lmMessage msg of
                                  'O':'M':'G':_ -> True
                                  _             -> False)
                         (do logMsg "this message will not be logged"
                             logMsg "OMG logged"
                             return 42)

In order to also delegate to the previous predicate, use modifyLogPredicate

See Control.Eff.Log

modifyLogPredicate :: forall e b. (Member Logs e, HasCallStack) => (LogPredicate -> LogPredicate) -> Eff e b -> Eff e b

Change the LogPredicate.

Other than setLogPredicate this function allows to include the previous predicate, too.

For to discard all messages currently no satisfying the predicate and also all messages that are to long:

modifyLogPredicate (previousPredicate msg -> previousPredicate msg && length (lmMessage msg) < 29 )
                   (do logMsg "this message will not be logged"
                       logMsg "this message might be logged")

See Control.Eff.Log

askLogPredicate :: forall e. Member Logs e => Eff e LogPredicate

Get the current Logs filter/transformer function.

See Control.Eff.Log

Log Handling API

Writing Logs

setLogWriter :: forall h e a. LogsTo h e => LogWriter h -> Eff e a -> Eff e a

Replace the current LogWriter. To add an additional log message consumer use addLogWriter

addLogWriter :: forall h e a. (HasCallStack, LogsTo h e, Monad h) => LogWriter h -> Eff e a -> Eff e a

Combine the effects of a given LogWriter and the existing one.

import Data.Text    as T
import Data.Text.IO as T

exampleAddLogWriter :: IO ()
exampleAddLogWriter = go >>= T.putStrLn
 where go = fmap (unlines . map renderLogMessageConsoleLog . snd)
              $  runLift
              $  runCaptureLogWriter
              $  withLogging captureLogWriter
              $  addLogWriter (mappingLogWriter (lmMessage %~ ("CAPTURED "++)) captureLogWriter)
              $  addLogWriter (filteringLogWriter severeMessages (mappingLogWriter (lmMessage %~ ("TRACED "++)) debugTraceLogWriter))
              $  do
                    logEmergency "test emergencySeverity 1"
                    logCritical "test criticalSeverity 2"
                    logAlert "test alertSeverity 3"
                    logError "test errorSeverity 4"
                    logWarning "test warningSeverity 5"
                    logInfo "test informationalSeverity 6"
                    logDebug "test debugSeverity 7"
       severeMessages = view (lmSeverity . to (<= errorSeverity))

modifyLogWriter :: forall h e a. LogsTo h e => (LogWriter h -> LogWriter h) -> Eff e a -> Eff e a

Change the current LogWriter.

Log Message Modification

censorLogs :: LogsTo h e => (LogMessage -> LogMessage) -> Eff e a -> Eff e a

Modify the the LogMessages written in the given sub-expression.

Note: This is equivalent to modifyLogWriter . mappingLogWriter

censorLogsM :: (LogsTo h e, Monad h) => (LogMessage -> h LogMessage) -> Eff e a -> Eff e a

Modify the the LogMessages written in the given sub-expression, as in censorLogs but with a effectful function.

Note: This is equivalent to modifyLogWriter . mappingLogWriterM

Logs Effect Handling

data Logs v

This effect sends LogMessages and is a reader for a LogPredicate.

Logs are sent via logMsg; for more information about log predicates, see Control.Eff.Log

This effect is handled via withLogging.

Instances

Handle Logs e a (LogPredicate -> k)

Defined in Control.Eff.Log.Handler

Methods

handle :: (Eff e a -> LogPredicate -> k) -> Arrs e v a -> Logs v -> LogPredicate -> k

handle_relay :: (e ~ (Logs ': r'), Relay (LogPredicate -> k) r') => (a -> LogPredicate -> k) -> (Eff e a -> LogPredicate -> k) -> Eff e a -> LogPredicate -> k

respond_relay :: (a -> LogPredicate -> k) -> (Eff e a -> LogPredicate -> k) -> Eff e a -> LogPredicate -> k

(MonadBase m m, LiftedBase m e, LogsTo m (Logs ': e)) => MonadBaseControl m (Eff (Logs ': e))

This instance allows lifting the Logs effect into a base monad, e.g. IO. This instance needs a LogWriterReader in the base monad, that is capable to handle logMsg invocations.

Defined in Control.Eff.Log.Handler

Associated Types

type StM (Eff (Logs ': e)) a :: Type

Methods

liftBaseWith :: (RunInBase (Eff (Logs ': e)) m -> m a) -> Eff (Logs ': e) a

restoreM :: StM (Eff (Logs ': e)) a -> Eff (Logs ': e) a

(LiftedBase m e, MonadThrow (Eff e)) => MonadThrow (Eff (Logs ': e))

Defined in Control.Eff.Log.Handler

Methods

throwM :: Exception e0 => e0 -> Eff (Logs ': e) a

(Applicative m, LiftedBase m e, MonadCatch (Eff e), LogsTo m (Logs ': e)) => MonadCatch (Eff (Logs ': e))

Defined in Control.Eff.Log.Handler

Methods

catch :: Exception e0 => Eff (Logs ': e) a -> (e0 -> Eff (Logs ': e) a) -> Eff (Logs ': e) a

(Applicative m, LiftedBase m e, MonadMask (Eff e), LogsTo m (Logs ': e)) => MonadMask (Eff (Logs ': e))

Defined in Control.Eff.Log.Handler

Methods

mask :: ((forall a. Eff (Logs ': e) a -> Eff (Logs ': e) a) -> Eff (Logs ': e) b) -> Eff (Logs ': e) b

uninterruptibleMask :: ((forall a. Eff (Logs ': e) a -> Eff (Logs ': e) a) -> Eff (Logs ': e) b) -> Eff (Logs ': e) b

generalBracket :: Eff (Logs ': e) a -> (a -> ExitCase b -> Eff (Logs ': e) c) -> (a -> Eff (Logs ': e) b) -> Eff (Logs ': e) (b, c)

type StM (Eff (Logs ': e)) a

Defined in Control.Eff.Log.Handler

type StM (Eff (Logs ': e)) a = StM (Eff e) a

type LogsTo h e = (Member Logs e, HandleLogWriter h, LogWriterEffects h <:: e, SetMember LogWriterReader (LogWriterReader h) e)

A constraint alias for effects that requires a LogWriterReader, as well as that the contained LogWriterReader has a HandleLogWriter instance.

The requirements of this constraint are provided by:

• withIoLogging
• withLogging
• withSomeLogging

withLogging :: forall h e a. (Applicative h, LogsTo h (Logs ': (LogWriterReader h ': e))) => LogWriter h -> Eff (Logs ': (LogWriterReader h ': e)) a -> Eff e a

Handle the Logs and LogWriterReader effects.

It installs the given LogWriter, which determines the underlying LogWriter type parameter.

Example:

exampleWithLogging :: IO ()
exampleWithLogging =
    runLift
  $ withLogging consoleLogWriter
  $ logDebug "Oh, hi there"

withSomeLogging :: forall h e a. (Applicative h, LogsTo h (Logs ': (LogWriterReader h ': e))) => Eff (Logs ': (LogWriterReader h ': e)) a -> Eff e a

Handles the Logs and LogWriterReader effects.

By default it uses the noOpLogWriter, but using setLogWriter the LogWriter can be replaced.

This is like withLogging applied to noOpLogWriter

Example:

exampleWithSomeLogging :: ()
exampleWithSomeLogging =
    run
  $ withSomeLogging @PureLogWriter
  $ logDebug "Oh, hi there"

Low-Level API for Custom Extensions

Log Message Interception

runLogs :: forall h e b. LogsTo h (Logs ': e) => LogPredicate -> Eff (Logs ': e) b -> Eff e b

Raw handling of the Logs effect. Exposed for custom extensions, if in doubt use withLogging.

respondToLogMessage :: forall r b. Member Logs r => (LogMessage -> Eff r ()) -> Eff r b -> Eff r b

Consume log messages.

Exposed for custom extensions, if in doubt use withLogging.

Respond to all LogMessages logged from the given action, up to any MonadBaseControl liftings.

Note that all logging is done through logMsg and that means only messages passing the LogPredicate are received.

The LogMessages are consumed once they are passed to the given callback function, previous respondToLogMessage invocations further up in the call stack will not get the messages anymore.

Use interceptLogMessages if the messages shall be passed any previous handler.

NOTE: The effects of this function are lost when using MonadBaseControl, MonadMask, MonadCatch and MonadThrow.

In contrast the functions based on modifying the LogWriter, such as addLogWriter or censorLogs, are save to use in combination with the aforementioned liftings.

interceptLogMessages :: forall r b. Member Logs r => (LogMessage -> Eff r LogMessage) -> Eff r b -> Eff r b

Change the LogMessages using an effectful function.

Exposed for custom extensions, if in doubt use withLogging.

This differs from respondToLogMessage in that the intercepted messages will be written either way, albeit in altered form.

NOTE: The effects of this function are lost when using MonadBaseControl, MonadMask, MonadCatch and MonadThrow.

In contrast the functions based on modifying the LogWriter, such as addLogWriter or censorLogs, are save to use in combination with the aforementioned liftings.