Control.Effects.Logging

Use this module to add logging to your monad. A log is a structured value that can hold information like severity, log message, timestamp, callstack, etc.

Logging is treated like a stream of logs comming from your application and functions that transform the logs take a stream and output a stream. Functions like logInfo push a new log into the stream and functions like setTimestampToNow take a stream of logs and attach extra info onto each log (current time in this case).

Read the documentation of individual functions to get a feel for what you can do.

Documentation

data Logging

The logging effect.

Constructors

Logging

Instances

data Effect Logging

data Effect Logging where

• LoggingMsg :: Effect Logging Logging Msg
• LoggingRes :: Effect Logging Logging Res

newtype Tag

Arbitrary piece of text. Logs contain a list of these.

Constructors

Tag Text

Instances

Eq Tag

Methods

(==) :: Tag -> Tag -> Bool

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

Ord Tag

Methods

compare :: Tag -> Tag -> Ordering

(<) :: Tag -> Tag -> Bool

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

(>) :: Tag -> Tag -> Bool

(>=) :: Tag -> Tag -> Bool

max :: Tag -> Tag -> Tag

min :: Tag -> Tag -> Tag

Read Tag

Methods

readsPrec :: Int -> ReadS Tag

readList :: ReadS [Tag]

readPrec :: ReadPrec Tag

readListPrec :: ReadPrec [Tag]

Show Tag

Methods

showsPrec :: Int -> Tag -> ShowS

show :: Tag -> String

showList :: [Tag] -> ShowS

newtype Context

A name for a "layer" of your application. Typically, a log will contain a stack of contexts. Think of it as a call stack specific for your application.

Constructors

Context

Fields

• getContext :: Text

Instances

Eq Context

Methods

(==) :: Context -> Context -> Bool

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

Ord Context

Methods

compare :: Context -> Context -> Ordering

(<) :: Context -> Context -> Bool

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

(>) :: Context -> Context -> Bool

(>=) :: Context -> Context -> Bool

max :: Context -> Context -> Context

min :: Context -> Context -> Context

Read Context

Methods

readsPrec :: Int -> ReadS Context

readList :: ReadS [Context]

readPrec :: ReadPrec Context

readListPrec :: ReadPrec [Context]

Show Context

Methods

showsPrec :: Int -> Context -> ShowS

show :: Context -> String

showList :: [Context] -> ShowS

data Level

The severity of the log.

Constructors

Fatal

Error

Warning

Info

Debug

Instances

Eq Level

Methods

(==) :: Level -> Level -> Bool

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

Ord Level

Methods

compare :: Level -> Level -> Ordering

(<) :: Level -> Level -> Bool

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

(>) :: Level -> Level -> Bool

(>=) :: Level -> Level -> Bool

max :: Level -> Level -> Level

min :: Level -> Level -> Level

Read Level

Methods

readsPrec :: Int -> ReadS Level

readList :: ReadS [Level]

readPrec :: ReadPrec Level

readListPrec :: ReadPrec [Level]

Show Level

Methods

showsPrec :: Int -> Level -> ShowS

show :: Level -> String

showList :: [Level] -> ShowS

data LogUser

If a notion of a user exists for your application, you can add this information to your logs.

Constructors

LogUser

Fields

• logUserId :: Text
• logUserEmail :: Maybe Text
• logUserUsername :: Maybe Text

Instances

Eq LogUser

Methods

(==) :: LogUser -> LogUser -> Bool

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

Ord LogUser

Methods

compare :: LogUser -> LogUser -> Ordering

(<) :: LogUser -> LogUser -> Bool

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

(>) :: LogUser -> LogUser -> Bool

(>=) :: LogUser -> LogUser -> Bool

max :: LogUser -> LogUser -> LogUser

min :: LogUser -> LogUser -> LogUser

Read LogUser

Methods

readsPrec :: Int -> ReadS LogUser

readList :: ReadS [LogUser]

readPrec :: ReadPrec LogUser

readListPrec :: ReadPrec [LogUser]

Show LogUser

Methods

showsPrec :: Int -> LogUser -> ShowS

show :: LogUser -> String

showList :: [LogUser] -> ShowS

ToJSON LogUser

Methods

toJSON :: LogUser -> Value

toEncoding :: LogUser -> Encoding

toJSONList :: [LogUser] -> Value

toEncodingList :: [LogUser] -> Encoding

addIfExists :: Text -> Maybe Value -> [(Text, Value)] -> [(Text, Value)]

data Crumb

Breadcrumbs are the steps that happened before a log.

Constructors

Crumb

Fields

• crumbTimestamp :: UTCTime
• crumbMessage :: Maybe Text
• crumbCategory :: Text
• crumbData :: CrumbData

Instances

Eq Crumb

Methods

(==) :: Crumb -> Crumb -> Bool

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

Read Crumb

Methods

readsPrec :: Int -> ReadS Crumb

readList :: ReadS [Crumb]

readPrec :: ReadPrec Crumb

readListPrec :: ReadPrec [Crumb]

Show Crumb

Methods

showsPrec :: Int -> Crumb -> ShowS

show :: Crumb -> String

showList :: [Crumb] -> ShowS

ToJSON Crumb

Methods

toJSON :: Crumb -> Value

toEncoding :: Crumb -> Encoding

toJSONList :: [Crumb] -> Value

toEncodingList :: [Crumb] -> Encoding

data CrumbData

Crumbs come in two varieties. A normal crumb is a list of key-value pairs. There's also a HttpCrumb where you can put more specific information about the processed HTTP request (if your application is a web server).

Constructors

DefaultCrumb [(Text, Value)]

HttpCrumb

Fields

• crumbUrl :: Text
• crumbMethod :: Text
• crumbStatusCode :: Int
• crumbReason :: Text

Instances

Eq CrumbData

Methods

(==) :: CrumbData -> CrumbData -> Bool

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

Read CrumbData

Methods

readsPrec :: Int -> ReadS CrumbData

readList :: ReadS [CrumbData]

readPrec :: ReadPrec CrumbData

readListPrec :: ReadPrec [CrumbData]

Show CrumbData

Methods

showsPrec :: Int -> CrumbData -> ShowS

show :: CrumbData -> String

showList :: [CrumbData] -> ShowS

ToJSON CrumbData

Methods

toJSON :: CrumbData -> Value

toEncoding :: CrumbData -> Encoding

toJSONList :: [CrumbData] -> Value

toEncodingList :: [CrumbData] -> Encoding

data Log

Constructors

Log

Fields

• logMessage :: Text
• logLevel :: Level
• logTags :: [Tag]
• logContext :: [Context]
• logUser :: Maybe LogUser
• logCrumbs :: [Crumb]
• logData :: ByteString
• logTimestamp :: Maybe UTCTime
• logCallStack :: CallStack

Instances

Show Log

Methods

showsPrec :: Int -> Log -> ShowS

show :: Log -> String

showList :: [Log] -> ShowS

newtype GenericException

A generic exception holding only a piece of text.

Constructors

GenericException Text

Instances

Eq GenericException

Methods

(==) :: GenericException -> GenericException -> Bool

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

Ord GenericException

Methods

compare :: GenericException -> GenericException -> Ordering

(<) :: GenericException -> GenericException -> Bool

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

(>) :: GenericException -> GenericException -> Bool

(>=) :: GenericException -> GenericException -> Bool

max :: GenericException -> GenericException -> GenericException

min :: GenericException -> GenericException -> GenericException

Read GenericException

Methods

readsPrec :: Int -> ReadS GenericException

readList :: ReadS [GenericException]

readPrec :: ReadPrec GenericException

readListPrec :: ReadPrec [GenericException]

Show GenericException

Methods

showsPrec :: Int -> GenericException -> ShowS

show :: GenericException -> String

showList :: [GenericException] -> ShowS

Exception GenericException

Methods

toException :: GenericException -> SomeException

fromException :: SomeException -> Maybe GenericException

displayException :: GenericException -> String

logEffect :: MonadEffect Logging m => Log -> m ()

Send a single log into the stream.

handleLogging :: Functor m => (Log -> m ()) -> EffectHandler Logging m a -> m a

A generic handler for logs. Since it's polymorphic in m you can choose to emit more logs and make it a log transformer instead.

layerLogs :: MonadEffect Logging m => Context -> EffectHandler Logging m a -> m a

Add a new context on top of every log that comes from the given computation.

originContext :: Log -> Maybe Context

Get the bottom-most context if it exists.

logInfo :: (HasCallStack, MonadEffect Logging m) => Text -> m ()

logWarning :: (HasCallStack, MonadEffect Logging m) => Text -> m ()

logError :: (HasCallStack, MonadEffect Logging m) => Text -> m ()

logAndError :: (Exception e, MonadEffect Logging m, MonadThrow m, HasCallStack) => Text -> e -> m a

Log an error and then throw the given exception.

logAndThrowsErr :: (MonadEffect Logging m, Throws e m, HasCallStack) => Text -> e -> m a

Log an error and then throw a checked exception. Read about checked exceptions in Signal.

logAndThrowGeneric :: (MonadEffect Logging m, MonadThrow m, HasCallStack) => Text -> m a

Log an error and throw a generic exception containing the text of the error message.

logMessagesToStdout :: MonadIO m => EffectHandler Logging m a -> m a

Log a stripped-down version of the logs to the console. Only contains the message and the severity.

logRawToStdout :: MonadIO m => EffectHandler Logging m a -> m a

Log everything to the console. Uses the Show instance for Log.

muteLogs :: Monad m => EffectHandler Logging m a -> m a

Discard the logs.

witherLogs :: MonadEffect Logging m => (Log -> m (Maybe Log)) -> EffectHandler Logging m a -> m a

Use the given function to transform and possibly discard logs.

filterLogs :: MonadEffect Logging m => (Log -> Bool) -> EffectHandler Logging m a -> m a

Only let through logs that satisfy the given predicate.

mapLogs :: MonadEffect Logging m => (Log -> m Log) -> EffectHandler Logging m a -> m a

Transform logs with the given function.

logIfDepthLessThan :: MonadEffect Logging m => Int -> EffectHandler Logging m a -> m a

Filter out logs that are comming from below a certain depth.

logIfDepth :: MonadEffect Logging m => (Int -> Bool) -> EffectHandler Logging m a -> m a

Filter logs whose depth satisfies the given predicate.

messagesToCrumbs :: (MonadIO m, MonadEffect Logging m) => EffectHandler Logging m a -> m a

For each log, add it's message to the logs breadcrumb list. This is useful so you don't have to manually add crumbs.

collectCrumbs :: MonadEffect Logging m => EffectHandler Logging (StateT [Crumb] m) a -> m a

Each log that passes through will get all of the crumbs of the previous logs added. If, for example, you're writing a web server, you might want to have this handler over the request handler so that if an error occurs you can see all the steps that happened before it, during the handling of that request.

addUserToLogs :: MonadEffect Logging m => LogUser -> EffectHandler Logging m a -> m a

Add a user to every log.

addCrumbToLogs :: MonadEffect Logging m => Crumb -> EffectHandler Logging m a -> m a

Add a crumb to every log.

setDataTo :: MonadEffect Logging m => ByteString -> EffectHandler Logging m a -> m a

Attach an arbitrary ByteString to every log. Typically you want to use this handler on logX functions directly like setDataTo "some data" (logInfo "some info")

setDataToJsonOf :: (MonadEffect Logging m, ToJSON v) => v -> EffectHandler Logging m a -> m a

Attach an arbitrary value to every log using it's ToJSON instance. Typically you want to use this handler on logX functions directly like setDataToJsonOf 123 (logInfo "some info")

setDataToShowOf :: (MonadEffect Logging m, Show v) => v -> EffectHandler Logging m a -> m a

Attach an arbitrary value to every log using it's Show instance. Typically you want to use this handler on logX functions directly like setDataToShowOf 123 (logInfo "some info")

setTimestampToNow :: (MonadEffect Logging m, MonadIO m) => EffectHandler Logging m a -> m a

Add the current time to every log.

prettyPrintSummary :: MonadIO m => Int -> EffectHandler Logging m a -> m a

Print out the logs in rich format. Truncates at the given length. Logs will contain: message, timestamp, data, user and the call stack.