Top-level module for structured logging support. Structured logging provides messages in a machine-readable format and passing an additional user data to the messages (context) to the log messages, and tooling that allows keep track of the current context and attach it to all the messages.

Short example:

logic :: LoggerEnv -> Int -> IO ()
logic ctx' entity_id = do                   -- (1)
   logInfo ctx "start processing entity"    -- (2)
   internal ctx entity_id                   -- (3)
   logInfo ctx "finish processing
  where
    ctx = addNamespace "logic"              -- (4)
        . addContext (sl "id" entity_id)    -- (5)
        $ ctx'

Here we:

• (1) pass initial context (ctx' :: LoggerEnv)
• (2) log message on InfoS severtity level with new context attached
• (3) start internal fuction with new context
• (4) extend initial context with a new namespace
• (5) extend initial context with a new user data

NOTE You may notice a bit of an extra boilerplate code here. It can be removed by using any effect handling approach, like ReaderT, MTL, various effects system or service pattern. However this library does not commit to any of those approaches and provides simple IO interface, so there can be a light wrapper with the system of your choice. E.g. The library author prefer to use ImplicitParams extension, as you can see in cheops-logger package.

For each message we attach additional information

• thread id — it can be useful to group messages by the thread when debugging, especially in a case if a thread can be associated with the request processing.
• namespace — . delimited text that describes the component that the log was emitted from. It allows simple logs filtering in an external system, or in the logger action.
• severity — information how urgent the message is.
• user_data - any user data in a key-value form, the key is a text value, and the value is a JSON-encoded value.

In order to keep track of that information we introduce LoggerEnv handle. It can be used to emit messages with additional information, see writing logs section, and modify current context, see adding context section.

Logs can we written using one of the following helpers. The general pattern is

logDebug logger "message"

Messages has type LogStr. This is an abstraction over a data-type for efficient log concatenation. Currently it uses Builder but it's an implementation detail and may change in the future.

LogStr can be created is several ways:

• From the string literal using IsString interface
• From the string like data that can be converted to text, using ls function
• From the type that has a Show instance using showLS

Library provides helper for each Severity level.

Messages in the library forms a stack, and you can attach 2 kinds of data to it:

1. namespace - a list of locations, that allows to tell that the component is it.
2. context - context is a list of key-value pairs, where key is a text and a value is any JSON value.

When you attach that information to the LoggerContext it will be added to each message that is written in that context. Allowing to analyze data in the external systems. User data is pushed as using PushContext wrapper, that can be created using sl.