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"].

Application environment, like prod, devel, testing.

Verbosity controls the amount of information (columns) a Scribe emits during logging.

The convention is: - V0 implies no additional payload information is included in message. - V3 implies the maximum amount of payload information. - Anything in between is left to the discretion of the developer.

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

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.

This has everything each log message will contain.

Field selector by verbosity within JSON payload.

Construct a simple log from any JSON item.

Reasonable defaults for a scribe. Buffer size of 4096.

A Effect you can use to run logging actions. there is only one effect as we can't have duplicated instances.

Run a KatipE Effect without a Namespace or a LogContexts. This also calls closeScribes

Run a KatipE Effect with a Namespace and a LogContexts. this also calls closeScribes

Run a KatipE Effect without a Namespace or a LogContexts and creating a LogEnv

Run a KatipE Effect with a Namespace and a LogContexts and creating a LogEnv

Add a scribe to the list. All future log calls will go to this scribe in addition to the others. Writes will be buffered per the ScribeSettings to prevent slow scribes from slowing down logging. Writes will be dropped if the buffer fills.

Remove a scribe from the environment. This does not finalize the scribe. This mainly only makes sense to use with something like MonadReader's local function to temporarily disavow a single logger for a block of code.

Unregister all scribes. Note that this is not for closing or finalizing scribes, use closeScribes for that. This mainly only makes sense to use with something like MonadReader's local function to temporarily disavow any loggers for a block of code.

Finalize a scribe early. Note that it isn't necessary to call this as both runKatipE and runKatipContextE call closeScribes

Log message with Builder underneath; use <> to concat in O(1).

Pack any string-like thing into a LogStr. This will automatically work on String, ByteString, Text and any of the lazy variants.

Shorthand for logStr

Convert any showable type into a LogStr.

get the KatipE LogEnv

temporarily modify the LogEnv

Log with full context, but without any code location.

Log a message without any payload/context or code location.

Loc-tagged logging using Stack when available. This function does not require template-haskell as it automatically uses implicit-callstacks when the code is compiled using GHC > 7.8. Using an older version of the compiler will result in the emission of a log line without any location information, so be aware of it. logLoc obj mempty InfoS "Hello world"

Log with everything, including a source code location. This is very low level and you typically can use logT in its place.

Log an already constructed Item. This is the lowest level function that other log* functions use. It can be useful when implementing centralised logging services.

Perform an action while logging any exceptions that may occur. >>> > logException () mempty ErrorS (error "foo")

get the KatipE LogContexts

temporarily modify the LogContexts

get the KatipE Namespace

temporarily modify the Namespace

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

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. logLocM InfoS "Hello world"

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.

Perform an action while logging any exceptions that may occur. >>> > error "foo" logExceptionM ErrorS

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

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.

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

Append a namespace segment to the current namespace for the given monadic action, then restore the previous state afterwards.

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.

Disable all scribes for the given monadic action, then restore them afterwards.

Logs to a file handle such as stdout, stderr, or a file. Contexts and other information will be flattened out into bracketed fields. For example:] [2016-05-11 21:01:15][MyApp][Info][myhost.example.com][PID 1724][ThreadId 1154][main:Helpers.Logging Helpers/Logging.hs:32:7] Started [2016-05-11 21:01:15][MyApp.confrabulation][Debug][myhost.example.com][PID 1724][ThreadId 1154][confrab_factor:42.0][main:Helpers.Logging Helpers/Logging.hs:41:9] Confrabulating widgets, with extra namespace and context [2016-05-11 21:01:15][MyApp][Info][myhost.example.com][PID 1724][ThreadId 1154][main:Helpers.Logging Helpers/Logging.hs:43:7] Namespace and context are back to normal Returns the newly-created Scribe. The finalizer flushes the handle. Handle mode is set to LineBuffering automatically.

Logs to a file handle such as stdout, stderr, or a file. Takes a custom ItemFormatter that can be used to format Item as needed. Returns the newly-created Scribe. The finalizer flushes the handle. Handle mode is set to LineBuffering automatically.

A specialization of mkHandleScribe that takes a FilePath instead of a Handle. It is responsible for opening the file in AppendMode and will close the file handle on closeScribe/closeScribes. Does not do log coloring. Sets handle to LineBuffering mode.

A custom ItemFormatter for logging Items. Takes a Value indicating whether to colorize the output, Verbosity of output, and an Item to format.

See bracketFormat and jsonFormat for examples.

A traditional bracketed log format. Contexts and other information will be flattened out into bracketed fields. For example:

[2016-05-11 21:01:15][MyApp][Info][myhost.example.com][PID 1724][ThreadId 1154][main:Helpers.Logging Helpers/Logging.hs:32:7] Started
[2016-05-11 21:01:15][MyApp.confrabulation][Debug][myhost.example.com][PID 1724][ThreadId 1154][confrab_factor:42.0][main:Helpers.Logging Helpers/Logging.hs:41:9] Confrabulating widgets, with extra namespace and context
[2016-05-11 21:01:15][MyApp][Info][myhost.example.com][PID 1724][ThreadId 1154][main:Helpers.Logging Helpers/Logging.hs:43:7] Namespace and context are back to normal

Logs items as JSON. This can be useful in circumstances where you already have infrastructure that is expecting JSON to be logged to a standard stream or file. For example:

{"at":"2018-10-02T21:50:30.4523848Z","env":"production","ns":["MyApp"],"data":{},"app":["MyApp"],"msg":"Started","pid":"10456","loc":{"loc_col":9,"loc_pkg":"main","loc_mod":"Helpers.Logging","loc_fn":"Helpers\\Logging.hs","loc_ln":44},"host":"myhost.example.com","sev":"Info","thread":"ThreadId 139"}
{"at":"2018-10-02T21:50:30.4523848Z","env":"production","ns":["MyApp","confrabulation"],"data":{"confrab_factor":42},"app":["MyApp"],"msg":"Confrabulating widgets, with extra namespace and context","pid":"10456","loc":{"loc_col":11,"loc_pkg":"main","loc_mod":"Helpers.Logging","loc_fn":"Helpers\\Logging.hs","loc_ln":53},"host":"myhost.example.com","sev":"Debug","thread":"ThreadId 139"}
{"at":"2018-10-02T21:50:30.4523848Z","env":"production","ns":["MyApp"],"data":{},"app":["MyApp"],"msg":"Namespace and context are back to normal","pid":"10456","loc":{"loc_col":9,"loc_pkg":"main","loc_mod":"Helpers.Logging","loc_fn":"Helpers\\Logging.hs","loc_ln":55},"host":"myhost.example.com","sev":"Info","thread":"ThreadId 139"}

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 lower than the provided Severity. For instance, if the user passes InfoS, DebugS items should be ignored. Katip provides the permitItem utility for this. The user or the scribe may use permitAND and permitOR to further customize this filtering, even dynamically if they wish to.

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 written.

Scribes provide a finalizer IO action (scribeFinalizer) that is meant to synchronously flush any remaining writes and clean up any resources acquired when the scribe was created. Internally, katip keeps a buffer for each scribe's writes. When closeScribe or closeScribes is called, that buffer stops accepting new log messages and after the last item in its buffer is sent to liPush, calls the finalizer. Thus, when the finalizer returns, katip can assume that all resources are cleaned up and all log messages are durably written.

While katip internally buffers messages per ScribeSettings, it sends them one at a time to the scribe. Depending on the scribe itself, it may make sense for that scribe to keep its own internal buffer to batch-send logs if writing items one at a time is not efficient. The scribe implementer must be sure that on finalization, all writes are committed synchronously.

Signature of a function passed to Scribe constructor and mkScribe* functions that decides which messages to be logged. Typically filters based on Severity, but can be combined with other, custom logic with permitAND and permitOR

AND together 2 permit functions

OR together 2 permit functions

Should this item be logged given the user's maximum severity? Most new scribes will use this as a base for their PermitFunc

Constrain payload based on verbosity. Backends should use this to automatically bubble higher verbosity levels to lower ones.

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.