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.

Instances

Effect Logging

Associated Types

data EffMethods Logging (m :: * -> *) :: *

type CanLift Logging (t :: (* -> *) -> * -> *) :: Constraint

Methods

liftThrough :: (CanLift Logging t, Monad m, Monad (t m)) => EffMethods Logging m -> EffMethods Logging (t m)

mergeContext :: Monad m => m (EffMethods Logging m) -> EffMethods Logging m

Generic (EffMethods Logging m)

Associated Types

type Rep (EffMethods Logging m) :: * -> *

Methods

from :: EffMethods Logging m -> Rep (EffMethods Logging m) x

to :: Rep (EffMethods Logging m) x -> EffMethods Logging m

data EffMethods Logging

data EffMethods Logging = LoggingMethods {

• _logEffect :: Log -> m ()

}

type CanLift Logging t

type CanLift Logging t = MonadTrans t

type Rep (EffMethods Logging m)

type Rep (EffMethods Logging m) = D1 * (MetaData "EffMethods" "Control.Effects.Logging" "simple-logging-0.2.0.3-CSJtz8g3p9k9oLX7pC4gHa" False) (C1 * (MetaCons "LoggingMethods" PrefixI True) (S1 * (MetaSel (Just Symbol "_logEffect") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (Log -> m ()))))

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

Send a single log into the stream.

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

Debug

Info

Warning

Error

Fatal

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 LogData

Logs can hold arbitrary data serialized as a ByteString. Additionally, a summary can be provided which is intended to be displayed fully in log summaries.

Constructors

LogData

Fields

• dataPayload :: ByteString
• dataSummary :: Text

Instances

Eq LogData

Methods

(==) :: LogData -> LogData -> Bool

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

Ord LogData

Methods

compare :: LogData -> LogData -> Ordering

(<) :: LogData -> LogData -> Bool

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

(>) :: LogData -> LogData -> Bool

(>=) :: LogData -> LogData -> Bool

max :: LogData -> LogData -> LogData

min :: LogData -> LogData -> LogData

Read LogData

Methods

readsPrec :: Int -> ReadS LogData

readList :: ReadS [LogData]

readPrec :: ReadPrec LogData

readListPrec :: ReadPrec [LogData]

Show LogData

Methods

showsPrec :: Int -> LogData -> ShowS

show :: LogData -> String

showList :: [LogData] -> ShowS

IsString LogData

Methods

fromString :: String -> LogData

data Log

Constructors

Log

Fields

• logMessage :: Text
• logLevel :: Level
• logTags :: [Tag]
• logContext :: [Context]
• logUser :: Maybe LogUser
• logCrumbs :: [Crumb]
• logData :: LogData
• 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

handleLogging :: Functor m => (Log -> m ()) -> RuntimeImplemented 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 :: (HasCallStack, MonadEffect Logging m) => Context -> RuntimeImplemented 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.

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

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

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

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

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

logFatal :: (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 :: (MonadEffects '[Logging, Signal e Void] 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 => RuntimeImplemented 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 => RuntimeImplemented Logging m a -> m a

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

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

Discard the logs.

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

Use the given function to transform and possibly discard logs.

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

Only let through logs that satisfy the given predicate.

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

Transform logs with the given function.

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

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

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

Filter logs whose depth satisfies the given predicate.

messagesToCrumbs :: (MonadIO m, MonadEffect Logging m) => RuntimeImplemented 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 => RuntimeImplemented 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 -> RuntimeImplemented Logging m a -> m a

Add a user to every log.

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

Add a crumb to every log.

setDataWithSummary :: MonadEffect Logging m => LogData -> RuntimeImplemented Logging m a -> m a

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

setDataTo :: MonadEffect Logging m => ByteString -> RuntimeImplemented 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 -> RuntimeImplemented 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 -> RuntimeImplemented 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) => RuntimeImplemented Logging m a -> m a

Add the current time to every log.

highlightT :: [Highlight] -> Text -> Text

yellow :: Text -> Text

colorFromLevel :: Level -> [Highlight]

writeDataToFiles :: (MonadEffect Logging m, MonadIO m) => FilePath -> RuntimeImplemented Logging m a -> m a

Puts data of each log into a separate file inside of a given directory. Replaces the data of the logs with the path to the files.

truncate :: Int -> Text -> Text

manyLines :: Int -> Text -> Text

prettyPrintSummary :: MonadIO m => Int -> RuntimeImplemented 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.

logIOExceptions :: (MonadEffect Logging m, MonadCatch m) => m a -> m a

Catches all IO exceptions, logs them and throws them back. The callstack in the log is not the callstack of the exception.