co-log-json-0.1.0.0: Structured messages support in co-log ecosystem.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Colog.Json.Action

Description

Action that allows to write structured log message.

Synopsis

Documentation

logToHandle :: Handle -> LogAction IO Message Source #

Dump logs to the output. On the contrary to the usual co-log functions this one embeds all the functionality inside. However all internals are exposed and in the case if you need any special functionality you can build your own function.

This function serializes a message to a temporary buffer and dumps buffer contents to the handle as soon as it's filled. See encodeMessage for encoding details.

Notes:

  1. In case of exception this function tries to dump information about exception in the handle once. But if another exception arrives while storing info, function rethorws the second exception.
  2. During log dumping this function captures all exceptions (SomeException) including asynchronous ones. So it should be run under a mask.
  3. Running a function under interruptible mask is safe as long no other thread is using a Handle.
  4. This function does not add timestamp to the message. This is done because we can always rely on external tools to add timestamp, whether it would be ts or journald or docker-logger. However if timestamp from the program is strictly needed it's possible to add it to the user data.
  5. If user data contains multiple values with the equal keys all the values will be stored. In case if it's unbearable you should remove duplicates when generating a Message
  6. While dumping the message to the Handle no lock is obtained, so the user is responsible for running this function in a race free context. It can be done either from a single thread, or using additional locking mechanisms.
  7. This function relies on the line bufferring in order to dump logs promptly. It's up to the user to decide how to setup it but in case of block buffering during low activity logs may be delayed a lot.

encodeMessage :: Message -> Encoding Source #

Efficiently convert a message into JSON encoding.

Message structure:

{ "namespace": "segment1.segment2"
, "severity": DEBUG
, "thread": 123121
, "data":  { ... }
, "message": "text message"
}

In case if there are no user attributes "data" key is omitted.