Safe Haskell | None |
---|---|
Language | Haskell2010 |
Includes all of the API's youll need to use Katip. Be sure to
check out the included examples
directory for an example of
usage.
To get up and running, the workflow is generally:
- Set up a
LogEnv
usinginitLogEnv
. - Add
Scribe
s usingregisterScribe
. - Either use
KatipT
orKatipContextT
for a pre-built transformer stack or addKatip
andKatipContext
instances to your own transformer stack. If you do the latter, you may want to look in theexamples
dir for some tips on composing contexts and namespaces. - Define some structured log data throughout your application and
implement
ToObject
andLogItem
for them. - Begin logging with
logT
,logTM
, etc. - Define your own
Scribe
if you need to output to some as-yet unsupported format or service. If you think it would be useful to others, consider releasing your own package.
- class MonadIO m => Katip m where
- newtype Namespace = Namespace {
- unNamespace :: [Text]
- newtype Environment = Environment {
- getEnvironment :: Text
- data Severity
- renderSeverity :: Severity -> Text
- severityText :: Prism' Text Severity
- data Verbosity
- class ToJSON a => ToObject a where
- toObject :: a -> Object
- class ToObject a => LogItem a where
- payloadKeys :: Verbosity -> a -> PayloadSelection
- data Item a = Item {
- _itemApp :: Namespace
- _itemEnv :: Environment
- _itemSeverity :: Severity
- _itemThread :: ThreadIdText
- _itemHost :: HostName
- _itemProcess :: ProcessID
- _itemPayload :: a
- _itemMessage :: LogStr
- _itemTime :: UTCTime
- _itemNamespace :: Namespace
- _itemLoc :: Maybe Loc
- itemApp :: forall a. Lens' (Item a) Namespace
- itemEnv :: forall a. Lens' (Item a) Environment
- itemSeverity :: forall a. Lens' (Item a) Severity
- itemThread :: forall a. Lens' (Item a) ThreadIdText
- itemHost :: forall a. Lens' (Item a) HostName
- itemProcess :: forall a. Lens' (Item a) ProcessID
- itemPayload :: forall a a. Lens (Item a) (Item a) a a
- itemMessage :: forall a. Lens' (Item a) LogStr
- itemTime :: forall a. Lens' (Item a) UTCTime
- itemNamespace :: forall a. Lens' (Item a) Namespace
- itemLoc :: forall a. Lens' (Item a) (Maybe Loc)
- newtype ThreadIdText = ThreadIdText {
- getThreadIdText :: Text
- data PayloadSelection
- data Scribe = Scribe {}
- data LogEnv = LogEnv {
- _logEnvHost :: HostName
- _logEnvPid :: ProcessID
- _logEnvNs :: Namespace
- _logEnvEnv :: Environment
- _logEnvTimer :: IO UTCTime
- _logEnvScribes :: Map Text Scribe
- logEnvHost :: Lens' LogEnv HostName
- logEnvPid :: Lens' LogEnv ProcessID
- logEnvNs :: Lens' LogEnv Namespace
- logEnvEnv :: Lens' LogEnv Environment
- logEnvTimer :: Lens' LogEnv (IO UTCTime)
- logEnvScribes :: Lens' LogEnv (Map Text Scribe)
- class Katip m => KatipContext m where
- data AnyLogContext
- data LogContexts
- liftPayload :: LogItem a => a -> LogContexts
- data SimpleLogPayload
- sl :: ToJSON a => Text -> a -> SimpleLogPayload
- newtype KatipT m a = KatipT {}
- runKatipT :: LogEnv -> KatipT m a -> m a
- initLogEnv :: Namespace -> Environment -> IO LogEnv
- registerScribe :: Text -> Scribe -> LogEnv -> LogEnv
- unregisterScribe :: Text -> LogEnv -> LogEnv
- clearScribes :: LogEnv -> LogEnv
- newtype LogStr = LogStr {
- unLogStr :: Builder
- logStr :: StringConv a Text => a -> LogStr
- ls :: StringConv a Text => a -> LogStr
- showLS :: Show a => a -> LogStr
- logF :: (Applicative m, LogItem a, Katip m) => a -> Namespace -> Severity -> LogStr -> m ()
- logMsg :: (Applicative m, Katip m) => Namespace -> Severity -> LogStr -> m ()
- logT :: ExpQ
- logItem :: (Applicative m, LogItem a, Katip m) => a -> Namespace -> Maybe Loc -> Severity -> LogStr -> m ()
- logException :: (Katip m, LogItem a, MonadCatch m, Applicative m) => a -> Namespace -> Severity -> m b -> m b
- logFM :: (Applicative m, KatipContext m, Katip m) => Severity -> LogStr -> m ()
- logTM :: ExpQ
- logItemM :: (Applicative m, KatipContext m, Katip m) => Maybe Loc -> Severity -> LogStr -> m ()
- logExceptionM :: (KatipContext m, MonadCatch m, Applicative m) => m a -> Severity -> m a
- mkHandleScribe :: ColorStrategy -> Handle -> Severity -> Verbosity -> IO Scribe
- data ColorStrategy
- permitItem :: Severity -> Item a -> Bool
- payloadObject :: LogItem a => Verbosity -> a -> Object
- itemJson :: LogItem a => Verbosity -> Item a -> Value
- data KatipContextT m a
- runKatipContextT :: LogItem c => LogEnv -> c -> Namespace -> KatipContextT m a -> m a
Framework Types
Represents a heirarchy of namespaces going from general to specific. For instance: ["processname", "subsystem"]. Note that single-segment namespaces can be created using IsString/OverloadedStrings, so "foo" will result in Namespace ["foo"].
Namespace | |
|
newtype Environment Source
Application environment, like prod
, devel
, testing
.
Environment | |
|
Eq Environment | |
Ord Environment | |
Read Environment | |
Show Environment | |
IsString Environment | |
Generic Environment | |
ToJSON Environment | |
FromJSON Environment | |
type Rep Environment |
renderSeverity :: Severity -> Text Source
severityText :: Prism' Text Severity Source
class ToJSON a => ToObject a where Source
Katip requires JSON objects to be logged as context. This
typeclass provides a default instance which uses ToJSON and
produces an empty object if toJSON
results in any type other than
object. If you have a type you want to log that produces an Array
or Number for example, you'll want to write an explicit instance
here. You can trivially add a ToObject instance for something with
a ToJSON instance like:
instance ToObject Foo
Nothing
ToObject () | |
ToObject Object | |
ToObject SimpleLogPayload | |
ToObject LogContexts |
class ToObject a => LogItem a where Source
Payload objects need instances of this class. LogItem makes it so
that you can have very verbose items getting logged with lots of
extra fields but under normal circumstances, if your scribe is
configured for a lower verbosity level, it will only log a
selection of those keys. Furthermore, each Scribe
can be
configured with a different Verbosity
level. You could even use
registerScribe
, unregisterScribe
, and clearScribes
to at
runtime swap out your existing scribes for more verbose debugging
scribes if you wanted to.
When defining payloadKeys
, don't redundantly declare the same
keys for higher levels of verbosity. Each level of verbosity
automatically and recursively contains all keys from the level
before it.
payloadKeys :: Verbosity -> a -> PayloadSelection Source
List of keys in the JSON object that should be included in message.
This has everything each log message will contain.
Item | |
|
itemEnv :: forall a. Lens' (Item a) Environment Source
itemSeverity :: forall a. Lens' (Item a) Severity Source
itemThread :: forall a. Lens' (Item a) ThreadIdText Source
itemProcess :: forall a. Lens' (Item a) ProcessID Source
itemPayload :: forall a a. Lens (Item a) (Item a) a a Source
itemMessage :: forall a. Lens' (Item a) LogStr Source
itemNamespace :: forall a. Lens' (Item a) Namespace Source
newtype ThreadIdText Source
ThreadIdText | |
|
Eq ThreadIdText | |
Ord ThreadIdText | |
Show ThreadIdText | |
ToJSON ThreadIdText | |
FromJSON ThreadIdText |
data PayloadSelection Source
Field selector by verbosity within JSON payload.
Scribes are handlers of incoming items. Each registered scribe knows how to push a log item somewhere.
Guidelines for writing your own Scribe
Scribes should always take a Severity
and Verbosity
.
Severity is used to *exclude log messages* that are < the provided
Severity. For instance, if the user passes InfoS, DebugS items
should be ignored. Katip provides the permitItem
utility for this.
Verbosity is used to select keys from the log item's payload. Each
LogItem
instance describes what keys should be retained for each
Verbosity level. Use the payloadObject
utility for extracting the keys
that should be permitted.
There is no built-in mechanism in katip for telling a scribe that
its time to shut down. unregisterScribe
merely drops it from the
LogEnv
. This means there are 2 ways to handle resources as a scribe:
- Pass in the resource when the scribe is created. Handle allocation and release of the resource elsewhere. This is what the Handle scribe does.
- Return a finalizing function that tells the scribe to shut
down.
katip-elasticsearch
'smkEsScribe
returns aIO (Scribe, IO ())
. The finalizer will flush any queued log messages and shut down gracefully before returning. This can be hooked into your application's shutdown routine to ensure you never miss any log messages on shutdown.
LogEnv | |
|
logEnvHost :: Lens' LogEnv HostName Source
logEnvEnv :: Lens' LogEnv Environment Source
logEnvTimer :: Lens' LogEnv (IO UTCTime) Source
logEnvScribes :: Lens' LogEnv (Map Text Scribe) Source
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.
(KatipContext m, Katip (MaybeT m)) => KatipContext (MaybeT m) | |
(KatipContext m, Katip (ListT m)) => KatipContext (ListT m) | |
(KatipContext m, Katip (IdentityT m)) => KatipContext (IdentityT m) | |
(KatipContext m, Katip (ResourceT m)) => KatipContext (ResourceT m) | |
(Monad m, KatipContext m) => KatipContext (KatipT m) | |
MonadIO m => KatipContext (KatipContextT m) | |
(Monoid w, KatipContext m, Katip (WriterT w m)) => KatipContext (WriterT w m) | |
(Monoid w, KatipContext m, Katip (WriterT w m)) => KatipContext (WriterT w m) | |
(KatipContext m, Katip (StateT s m)) => KatipContext (StateT s m) | |
(KatipContext m, Katip (StateT s m)) => KatipContext (StateT s m) | |
(KatipContext m, Katip (ReaderT r m)) => KatipContext (ReaderT r m) | |
(KatipContext m, Katip (ExceptT s m)) => KatipContext (ExceptT s m) | |
(KatipContext m, Katip (EitherT e m)) => KatipContext (EitherT e m) | |
(Monoid w, KatipContext m, Katip (RWST r w s m)) => KatipContext (RWST r w s m) | |
(Monoid w, KatipContext m, Katip (RWST r w s m)) => KatipContext (RWST r w s m) |
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.
liftPayload :: LogItem a => a -> LogContexts Source
Lift a log context into the generic wrapper so that it can combine with the existing log context.
data SimpleLogPayload Source
Monoid SimpleLogPayload | |
ToJSON SimpleLogPayload | A built-in convenience log payload that won't log anything on Construct using |
LogItem SimpleLogPayload | |
ToObject SimpleLogPayload |
sl :: ToJSON a => Text -> a -> SimpleLogPayload Source
Construct a simple log from any JSON item.
A Built-in Monad For Logging
A concrete monad you can use to run logging actions.
MonadTrans KatipT | |
MonadTransControl KatipT | |
MonadBase b m => MonadBase b (KatipT m) | |
MonadBaseControl b m => MonadBaseControl b (KatipT m) | |
Monad m => Monad (KatipT m) | |
Functor m => Functor (KatipT m) | |
Applicative m => Applicative (KatipT m) | |
MonadThrow m => MonadThrow (KatipT m) | |
MonadMask m => MonadMask (KatipT m) | |
MonadCatch m => MonadCatch (KatipT m) | |
MonadIO m => MonadIO (KatipT m) | |
MonadIO m => Katip (KatipT m) | |
(Monad m, KatipContext m) => KatipContext (KatipT m) | |
type StT KatipT a = a | |
type StM (KatipT m) a = ComposeSt KatipT m a |
Initializing Loggers
:: Namespace | A base namespace for this application |
-> Environment | Current run environment (e.g. |
-> IO LogEnv |
Create a reasonable default InitLogEnv. Uses an AutoUdate
with
the default settings as the timer. If you are concerned about
timestamp precision or event ordering in log outputs like
ElasticSearch, you should replace the timer with getCurrentTime
Add a scribe to the list. All future log calls will go to this scribe in addition to the others.
Remove a scribe from the list. All future log calls will no longer use this scribe. If the given scribe doesn't exist, its a no-op.
clearScribes :: LogEnv -> LogEnv Source
Unregister *all* scribes. Logs will go off into space from this point onward until new scribes are added.
Logging Functions
Log message with Builder unerneath; use <>
to concat in O(1).
:: (Applicative m, LogItem a, Katip m) | |
=> a | Contextual payload for the log |
-> Namespace | Specific namespace of the message. |
-> Severity | Severity of the message |
-> LogStr | The log message |
-> m () |
Log with full context, but without any code location.
logMsg :: (Applicative m, Katip m) => Namespace -> Severity -> LogStr -> m () Source
Log a message without any payload/context or code location.
Loc
-tagged logging when using template-haskell.
$(logT) obj mempty InfoS "Hello world"
logItem :: (Applicative m, LogItem a, Katip m) => a -> Namespace -> Maybe Loc -> Severity -> LogStr -> m () Source
Log with everything, including a source code location. This is
very low level and you typically can use logT
in its place.
:: (Katip m, LogItem a, MonadCatch m, Applicative m) | |
=> a | Log context |
-> Namespace | Namespace |
-> Severity | Severity |
-> m b | Main action being run |
-> m b |
Perform an action while logging any exceptions that may occur.
Inspired by onException
.
>>>
> logException () mempty ErrorS (error "foo")
:: (Applicative m, KatipContext m, Katip 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.
Loc
-tagged logging when using template-haskell. Automatically
supplies payload and namespace.
$(logt) InfoS "Hello world"
logItemM :: (Applicative m, KatipContext m, Katip m) => 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. Automaticallysupplies payload and namespace.
:: (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
Included Scribes
mkHandleScribe :: ColorStrategy -> Handle -> Severity -> Verbosity -> IO Scribe Source
Logs to a file handle such as stdout, stderr, or a file.
data ColorStrategy Source
ColorLog Bool | Whether to use color control chars in log output |
ColorIfTerminal | Color if output is a terminal |
Tools for implementing Scribes
permitItem :: Severity -> Item a -> Bool Source
Should this item be logged given the user's maximum severity?
payloadObject :: LogItem a => Verbosity -> a -> Object Source
Constrain payload based on verbosity. Backends should use this to automatically bubble higher verbosity levels to lower ones.
itemJson :: LogItem a => Verbosity -> Item a -> Value Source
Convert log item to its JSON representation while trimming its payload based on the desired verbosity. Backends that push JSON messages should use this to obtain their payload.
KatipContextT - Utility transformer that provides Katip and KatipContext instances
data KatipContextT m a Source
Provides a simple transformer that defines a KatipContext
instance for a fixed namespace and context. You will typically only
use this if you are forced to run in IO but still want to have your
log context. 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
MonadTrans KatipContextT | |
MonadTransControl KatipContextT | |
MonadBase b m => MonadBase b (KatipContextT m) | |
MonadBaseControl b m => MonadBaseControl b (KatipContextT m) | |
MonadWriter w m => MonadWriter w (KatipContextT m) | |
MonadState s m => MonadState s (KatipContextT m) | |
MonadReader r m => MonadReader r (KatipContextT m) | |
MonadError e m => MonadError e (KatipContextT m) | |
Alternative m => Alternative (KatipContextT m) | |
Monad m => Monad (KatipContextT m) | |
Functor m => Functor (KatipContextT m) | |
MonadFix m => MonadFix (KatipContextT m) | |
MonadPlus m => MonadPlus (KatipContextT m) | |
Applicative m => Applicative (KatipContextT m) | |
MonadThrow m => MonadThrow (KatipContextT m) | |
MonadMask m => MonadMask (KatipContextT m) | |
MonadCatch m => MonadCatch (KatipContextT m) | |
MonadIO m => MonadIO (KatipContextT m) | |
MonadIO m => Katip (KatipContextT m) | |
MonadIO m => KatipContext (KatipContextT m) | |
type StT KatipContextT a = StT (ReaderT KatipContextTState) a | |
type StM (KatipContextT m) a = ComposeSt KatipContextT m a |
runKatipContextT :: LogItem c => LogEnv -> c -> Namespace -> KatipContextT m a -> m a Source