katip-0.8.8.0: A structured logging framework.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Katip.Monadic

Description

Provides support for treating payloads and namespaces as composable contexts. The common pattern would be to provide a KatipContext instance for your base monad.

Synopsis

Monadic variants of logging functions from Katip.Core

logFM Source #

Arguments

:: (Applicative m, KatipContext m) 
=> Severity

Severity of the message

-> LogStr

The log message

-> m () 

Log with full context, but without any code location. Automatically supplies payload and namespace.

logTM :: ExpQ Source #

Loc-tagged logging when using template-haskell. Automatically supplies payload and namespace.

$(logTM) InfoS "Hello world"

logLocM :: (Applicative m, KatipContext m, HasCallStack) => Severity -> LogStr -> m () Source #

Loc-tagged logging when using getCallStack implicit-callstacks>. Automatically supplies payload and namespace.

Same consideration as logLoc applies.

By default, location will be logged from the module that invokes logLocM. If you want to use logLocM in a helper, wrap the entire helper in withFrozenCallStack to retain the callsite of the helper in the logs.

This function does not require template-haskell. Using GHC <= 7.8 will result in the emission of a log line without any location information. Users using GHC <= 7.8 may want to use the template-haskell function logTM for maximum compatibility.

logLocM InfoS "Hello world"

logItemM :: (Applicative m, KatipContext m, HasCallStack) => Maybe Loc -> Severity -> LogStr -> m () Source #

Log with everything, including a source code location. This is very low level and you typically can use logTM in its place. Automatically supplies payload and namespace.

logExceptionM Source #

Arguments

:: (KatipContext m, MonadCatch m, Applicative m) 
=> m a

Main action to run

-> Severity

Severity

-> m a 

Perform an action while logging any exceptions that may occur. Inspired by onException.

>>> > error "foo" `logExceptionM` ErrorS

Machinery for merging typed log payloads/contexts

class Katip m => KatipContext m where Source #

A monadic context that has an inherant way to get logging context and namespace. Examples include a web application monad or database monad. The local variants are just like local from Reader and indeed you can easily implement them with local if you happen to be using a Reader in your monad. These give us katipAddNamespace and katipAddContext that works with *any* KatipContext, as opposed to making users have to implement these functions on their own in each app.

Methods

getKatipContext :: m LogContexts Source #

localKatipContext :: (LogContexts -> LogContexts) -> m a -> m a Source #

Temporarily modify the current context for the duration of the supplied monad. Used in katipAddContext

getKatipNamespace :: m Namespace Source #

localKatipNamespace :: (Namespace -> Namespace) -> m a -> m a Source #

Temporarily modify the current namespace for the duration of the supplied monad. Used in katipAddNamespace

Instances

Instances details
(Monad m, KatipContext m) => KatipContext (KatipT m) Source # 
Instance details

Defined in Katip.Monadic

MonadIO m => KatipContext (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

MonadIO m => KatipContext (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

(KatipContext m, Katip (ResourceT m)) => KatipContext (ResourceT m) Source # 
Instance details

Defined in Katip.Monadic

(KatipContext m, Katip (MaybeT m)) => KatipContext (MaybeT m) Source # 
Instance details

Defined in Katip.Monadic

(KatipContext m, Katip (ExceptT e m)) => KatipContext (ExceptT e m) Source # 
Instance details

Defined in Katip.Monadic

(KatipContext m, Katip (IdentityT m)) => KatipContext (IdentityT m) Source # 
Instance details

Defined in Katip.Monadic

(KatipContext m, Katip (ReaderT r m)) => KatipContext (ReaderT r m) Source # 
Instance details

Defined in Katip.Monadic

(KatipContext m, Katip (StateT s m)) => KatipContext (StateT s m) Source # 
Instance details

Defined in Katip.Monadic

(KatipContext m, Katip (StateT s m)) => KatipContext (StateT s m) Source # 
Instance details

Defined in Katip.Monadic

(Monoid w, KatipContext m, Katip (WriterT w m)) => KatipContext (WriterT w m) Source # 
Instance details

Defined in Katip.Monadic

(Monoid w, KatipContext m, Katip (WriterT w m)) => KatipContext (WriterT w m) Source # 
Instance details

Defined in Katip.Monadic

(Monoid w, KatipContext m, Katip (RWST r w s m)) => KatipContext (RWST r w s m) Source # 
Instance details

Defined in Katip.Monadic

(Monoid w, KatipContext m, Katip (RWST r w s m)) => KatipContext (RWST r w s m) Source # 
Instance details

Defined in Katip.Monadic

data AnyLogContext Source #

A wrapper around a log context that erases type information so that contexts from multiple layers can be combined intelligently.

data LogContexts Source #

Heterogeneous list of log contexts that provides a smart LogContext instance for combining multiple payload policies. This is critical for log contexts deep down in a stack to be able to inject their own context without worrying about other context that has already been set. Also note that contexts are treated as a sequence and <> will be appended to the right hand side of the sequence. If there are conflicting keys in the contexts, the /right side will take precedence/, which is counter to how monoid works for Map and HashMap, so bear that in mind. The reasoning is that if the user is sequentially adding contexts to the right side of the sequence, on conflict the intent is to overwrite with the newer value (i.e. the rightmost value).

Additional note: you should not mappend LogContexts in any sort of infinite loop, as it retains all data, so that would be a memory leak.

liftPayload :: LogItem a => a -> LogContexts Source #

Lift a log context into the generic wrapper so that it can combine with the existing log context.

KatipContextT - Utility transformer that provides Katip and KatipContext instances

newtype KatipContextT m a Source #

Provides a simple transformer that defines a KatipContext instance for a fixed namespace and context. Just like KatipT, you should use this if you prefer an explicit transformer stack and don't want to (or cannot) define KatipContext for your monad . This is the slightly more powerful version of KatipT in that it provides KatipContext instead of just Katip. For instance:

  threadWithLogging = do
    le <- getLogEnv
    ctx <- getKatipContext
    ns <- getKatipNamespace
    forkIO $ runKatipContextT le ctx ns $ do
      $(logTM) InfoS "Look, I can log in IO and retain context!"
      doOtherStuff

Instances

Instances details
MonadTransControl KatipContextT Source # 
Instance details

Defined in Katip.Monadic

Associated Types

type StT KatipContextT a #

Methods

liftWith :: Monad m => (Run KatipContextT -> m a) -> KatipContextT m a #

restoreT :: Monad m => m (StT KatipContextT a) -> KatipContextT m a #

MonadTrans KatipContextT Source # 
Instance details

Defined in Katip.Monadic

Methods

lift :: Monad m => m a -> KatipContextT m a #

MonadBaseControl b m => MonadBaseControl b (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Associated Types

type StM (KatipContextT m) a #

MonadError e m => MonadError e (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

throwError :: e -> KatipContextT m a #

catchError :: KatipContextT m a -> (e -> KatipContextT m a) -> KatipContextT m a #

MonadReader r m => MonadReader r (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

ask :: KatipContextT m r #

local :: (r -> r) -> KatipContextT m a -> KatipContextT m a #

reader :: (r -> a) -> KatipContextT m a #

MonadState s m => MonadState s (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

get :: KatipContextT m s #

put :: s -> KatipContextT m () #

state :: (s -> (a, s)) -> KatipContextT m a #

MonadWriter w m => MonadWriter w (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

writer :: (a, w) -> KatipContextT m a #

tell :: w -> KatipContextT m () #

listen :: KatipContextT m a -> KatipContextT m (a, w) #

pass :: KatipContextT m (a, w -> w) -> KatipContextT m a #

MonadBase b m => MonadBase b (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

liftBase :: b α -> KatipContextT m α #

MonadFail m => MonadFail (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

fail :: String -> KatipContextT m a #

MonadFix m => MonadFix (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

mfix :: (a -> KatipContextT m a) -> KatipContextT m a #

MonadIO m => MonadIO (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

liftIO :: IO a -> KatipContextT m a #

Alternative m => Alternative (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Applicative m => Applicative (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

pure :: a -> KatipContextT m a #

(<*>) :: KatipContextT m (a -> b) -> KatipContextT m a -> KatipContextT m b #

liftA2 :: (a -> b -> c) -> KatipContextT m a -> KatipContextT m b -> KatipContextT m c #

(*>) :: KatipContextT m a -> KatipContextT m b -> KatipContextT m b #

(<*) :: KatipContextT m a -> KatipContextT m b -> KatipContextT m a #

Functor m => Functor (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

fmap :: (a -> b) -> KatipContextT m a -> KatipContextT m b #

(<$) :: a -> KatipContextT m b -> KatipContextT m a #

Monad m => Monad (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

(>>=) :: KatipContextT m a -> (a -> KatipContextT m b) -> KatipContextT m b #

(>>) :: KatipContextT m a -> KatipContextT m b -> KatipContextT m b #

return :: a -> KatipContextT m a #

MonadPlus m => MonadPlus (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

MonadCatch m => MonadCatch (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

catch :: Exception e => KatipContextT m a -> (e -> KatipContextT m a) -> KatipContextT m a #

MonadMask m => MonadMask (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

mask :: ((forall a. KatipContextT m a -> KatipContextT m a) -> KatipContextT m b) -> KatipContextT m b #

uninterruptibleMask :: ((forall a. KatipContextT m a -> KatipContextT m a) -> KatipContextT m b) -> KatipContextT m b #

generalBracket :: KatipContextT m a -> (a -> ExitCase b -> KatipContextT m c) -> (a -> KatipContextT m b) -> KatipContextT m (b, c) #

MonadThrow m => MonadThrow (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

throwM :: Exception e => e -> KatipContextT m a #

MonadIO m => Katip (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

MonadIO m => KatipContext (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

MonadResource m => MonadResource (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

MonadUnliftIO m => MonadUnliftIO (KatipContextT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

withRunInIO :: ((forall a. KatipContextT m a -> IO a) -> IO b) -> KatipContextT m b #

type StT KatipContextT a Source # 
Instance details

Defined in Katip.Monadic

type StM (KatipContextT m) a Source # 
Instance details

Defined in Katip.Monadic

katipAddNamespace :: KatipContext m => Namespace -> m a -> m a Source #

Append a namespace segment to the current namespace for the given monadic action, then restore the previous state afterwards. Works with anything implementing KatipContext.

katipAddContext :: (LogItem i, KatipContext m) => i -> m a -> m a Source #

Append some context to the current context for the given monadic action, then restore the previous state afterwards. Important note: be careful using this in a loop. If you're using something like forever or replicateM_ that does explicit sharing to avoid a memory leak, youll be fine as it will *sequence* calls to katipAddNamespace, so each loop will get the same context added. If you instead roll your own recursion and you're recursing in the action you provide, you'll instead accumulate tons of redundant contexts and even if they all merge on log, they are stored in a sequence and will leak memory. Works with anything implementing KatipContext.

newtype NoLoggingT m a Source #

Constructors

NoLoggingT 

Fields

Instances

Instances details
MonadTransControl NoLoggingT Source # 
Instance details

Defined in Katip.Monadic

Associated Types

type StT NoLoggingT a #

Methods

liftWith :: Monad m => (Run NoLoggingT -> m a) -> NoLoggingT m a #

restoreT :: Monad m => m (StT NoLoggingT a) -> NoLoggingT m a #

MonadTrans NoLoggingT Source # 
Instance details

Defined in Katip.Monadic

Methods

lift :: Monad m => m a -> NoLoggingT m a #

MonadBaseControl b m => MonadBaseControl b (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Associated Types

type StM (NoLoggingT m) a #

Methods

liftBaseWith :: (RunInBase (NoLoggingT m) b -> b a) -> NoLoggingT m a #

restoreM :: StM (NoLoggingT m) a -> NoLoggingT m a #

MonadError e m => MonadError e (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

throwError :: e -> NoLoggingT m a #

catchError :: NoLoggingT m a -> (e -> NoLoggingT m a) -> NoLoggingT m a #

MonadReader r m => MonadReader r (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

ask :: NoLoggingT m r #

local :: (r -> r) -> NoLoggingT m a -> NoLoggingT m a #

reader :: (r -> a) -> NoLoggingT m a #

MonadState s m => MonadState s (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

get :: NoLoggingT m s #

put :: s -> NoLoggingT m () #

state :: (s -> (a, s)) -> NoLoggingT m a #

MonadWriter w m => MonadWriter w (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

writer :: (a, w) -> NoLoggingT m a #

tell :: w -> NoLoggingT m () #

listen :: NoLoggingT m a -> NoLoggingT m (a, w) #

pass :: NoLoggingT m (a, w -> w) -> NoLoggingT m a #

MonadBase b m => MonadBase b (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

liftBase :: b α -> NoLoggingT m α #

MonadFix m => MonadFix (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

mfix :: (a -> NoLoggingT m a) -> NoLoggingT m a #

MonadIO m => MonadIO (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

liftIO :: IO a -> NoLoggingT m a #

Alternative m => Alternative (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

empty :: NoLoggingT m a #

(<|>) :: NoLoggingT m a -> NoLoggingT m a -> NoLoggingT m a #

some :: NoLoggingT m a -> NoLoggingT m [a] #

many :: NoLoggingT m a -> NoLoggingT m [a] #

Applicative m => Applicative (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

pure :: a -> NoLoggingT m a #

(<*>) :: NoLoggingT m (a -> b) -> NoLoggingT m a -> NoLoggingT m b #

liftA2 :: (a -> b -> c) -> NoLoggingT m a -> NoLoggingT m b -> NoLoggingT m c #

(*>) :: NoLoggingT m a -> NoLoggingT m b -> NoLoggingT m b #

(<*) :: NoLoggingT m a -> NoLoggingT m b -> NoLoggingT m a #

Functor m => Functor (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

fmap :: (a -> b) -> NoLoggingT m a -> NoLoggingT m b #

(<$) :: a -> NoLoggingT m b -> NoLoggingT m a #

Monad m => Monad (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

(>>=) :: NoLoggingT m a -> (a -> NoLoggingT m b) -> NoLoggingT m b #

(>>) :: NoLoggingT m a -> NoLoggingT m b -> NoLoggingT m b #

return :: a -> NoLoggingT m a #

MonadPlus m => MonadPlus (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

mzero :: NoLoggingT m a #

mplus :: NoLoggingT m a -> NoLoggingT m a -> NoLoggingT m a #

MonadCatch m => MonadCatch (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

catch :: Exception e => NoLoggingT m a -> (e -> NoLoggingT m a) -> NoLoggingT m a #

MonadMask m => MonadMask (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

mask :: ((forall a. NoLoggingT m a -> NoLoggingT m a) -> NoLoggingT m b) -> NoLoggingT m b #

uninterruptibleMask :: ((forall a. NoLoggingT m a -> NoLoggingT m a) -> NoLoggingT m b) -> NoLoggingT m b #

generalBracket :: NoLoggingT m a -> (a -> ExitCase b -> NoLoggingT m c) -> (a -> NoLoggingT m b) -> NoLoggingT m (b, c) #

MonadThrow m => MonadThrow (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

throwM :: Exception e => e -> NoLoggingT m a #

MonadIO m => Katip (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

MonadIO m => KatipContext (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

MonadUnliftIO m => MonadUnliftIO (NoLoggingT m) Source # 
Instance details

Defined in Katip.Monadic

Methods

withRunInIO :: ((forall a. NoLoggingT m a -> IO a) -> IO b) -> NoLoggingT m b #

type StT NoLoggingT a Source # 
Instance details

Defined in Katip.Monadic

type StT NoLoggingT a = a
type StM (NoLoggingT m) a Source # 
Instance details

Defined in Katip.Monadic

type StM (NoLoggingT m) a = StM m a

askLoggerIO :: (Applicative m, KatipContext m) => m (Severity -> LogStr -> IO ()) Source #

Convenience function for when you have to integrate with a third party API that takes a generic logging function as an argument.