Z.IO.Logger

Simple, high performance logger. The design choice of this logger is biased towards simplicity instead of generlization:

• All log functions live in IO.
• By default this logger is connected to stderr, use setDefaultLogger to customize.

• When logging each thread will build log Builders into a small Bytes with line buffer instead of leaving all Builders to the flushing thread:

  • Logger won't keep heap data for too long simply because they're referenced by log's Builder.
  • Each logging thread only need perform a CAS to prepend log Bytes into a list, which reduces contention.
  • Each log call is atomic, Logging order is preserved under concurrent settings.

Flushing is automatic and throttled for debug, info, warn to boost performance, but a fatal log will always flush logger's buffer. This could lead to a problem that if main thread exits too early logs may missed, to add a flushing when program exits, use withDefaultLogger like:

import Z.IO.Logger

main :: IO ()
main = withDefaultLogger $ do
    ....
    debug "..."   -- So that this log won't be missed
    ...

A simple Logger type

data Logger

Constructors

Logger

Fields

• loggerPushBuilder :: Builder () -> IO ()

  push log into buffer

• flushLogger :: IO ()

  flush logger's buffer to output device

• flushLoggerThrottled :: IO ()

  throttled flush, e.g. use throttleTrailing_ from Z.IO.LowResTimer

• loggerTSCache :: IO (Builder ())

  A IO action return a formatted date/time string

• loggerFmt :: LogFormatter

data LoggerConfig

Constructors

LoggerConfig

Fields

• loggerMinFlushInterval :: !Int

  Minimal flush interval, see Notes on debug

• loggerLineBufSize :: !Int

  Buffer size to build each log line

• loggerShowDebug :: Bool

  Set to False to filter debug logs

defaultLoggerConfig :: LoggerConfig

A default logger config with

• 0.1s minimal flush interval
• line buffer size 240 bytes
• show debug True

setDefaultLogger :: Logger -> IO ()

Change the global logger.

getDefaultLogger :: IO Logger

Get the global logger.

flushDefaultLogger :: IO ()

Manually flush stderr logger.

withDefaultLogger :: IO () -> IO ()

Flush stderr logger when program exits.

newLogger :: Output o => LoggerConfig -> MVar (BufferedOutput o) -> IO Logger

Make a new simple logger.

newColoredLogger :: LoggerConfig -> IO Logger

Make a new colored logger connected to stderr.

This logger will output colorized log if stderr is connected to TTY.

logging functions

debug :: HasCallStack => Builder () -> IO ()

info :: HasCallStack => Builder () -> IO ()

warn :: HasCallStack => Builder () -> IO ()

fatal :: HasCallStack => Builder () -> IO ()

otherLevel

Arguments

:: HasCallStack

=> Level

log level

-> Bool

flush immediately?

-> Builder ()

log content

-> IO ()

type Level = CBytes

logging functions with specific logger

debugTo :: HasCallStack => Logger -> Builder () -> IO ()

infoTo :: HasCallStack => Logger -> Builder () -> IO ()

warnTo :: HasCallStack => Logger -> Builder () -> IO ()

fatalTo :: HasCallStack => Logger -> Builder () -> IO ()

otherLevelTo

Arguments

:: HasCallStack

=> Logger

-> Level

log level

-> Bool

flush immediately?

-> Builder ()

log content

-> IO ()

Helper to write new logger

defaultTSCache :: IO (Builder ())

A default timestamp cache with format %Y-%m-%dT%H:%M:%S%Z

The timestamp will updated in 0.1s granularity to ensure a seconds level precision.

defaultFmtCallStack :: CallStack -> Builder ()

Default stack formatter which fetch the logging source and location.

type LogFormatter

Arguments

 = Builder ()

data/time string

-> Level

log level

-> Builder ()

log content

-> CallStack

call stack trace

-> Builder ()

defaultFmt

Arguments

:: Bool

show DEGUG?

-> LogFormatter

A default log formatter

 [DEBUG][2020-10-09T07:44:14UTC][interactive:7:1]This a debug message\n

coloredFmt

Arguments

:: Bool

show DEBUG?

-> LogFormatter

A default colored log formatter

DEBUG level is Cyan, WARN level is Yellow, FATAL level is Red.

flushLog :: (HasCallStack, Output o) => MVar (BufferedOutput o) -> IORef [Bytes] -> IO ()

Use this function to implement a simple IORef based concurrent logger.

bList <- newIORef []
let flush = flushLog buffered bList
..
return $ Logger (pushLog bList) flush ...