Z-IO- Simple and high performance IO toolkit for Haskell
Copyright(c) Dong Han 2017-2018
Safe HaskellNone



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, warning to boost performance, but a fatal and critical 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 Source #

Extensible logger type.




data LoggerConfig Source #

Logger config type used in this module.




defaultLoggerConfig :: LoggerConfig Source #

A default logger config with

  • 0.1s minimal flush interval
  • line buffer size 240 bytes
  • show everything by default

setDefaultLogger :: Logger -> IO () Source #

Change the global logger.

getDefaultLogger :: IO Logger Source #

Get the global logger.

flushDefaultLogger :: IO () Source #

Manually flush global logger.

withDefaultLogger :: IO () -> IO () Source #

Flush global logger when program exits.

newLogger :: LoggerConfig -> MVar BufferedOutput -> IO Logger Source #

Make a new simple logger.

newColoredLogger :: LoggerConfig -> IO Logger Source #

Make a new colored logger(connected to stderr).

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

logging functions

otherLevel Source #


:: HasCallStack 
=> Level

log level

-> Bool

flush immediately?

-> Builder ()

log content

-> IO () 

logging functions with specific logger

otherLevelTo Source #


:: HasCallStack 
=> Logger 
-> Level

log level

-> Bool

flush immediately?

-> Builder ()

log content

-> IO () 

Helpers to write new logger

defaultTSCache :: IO (Builder ()) Source #

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

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

defaultFmtCallStack :: CallStack -> Builder () Source #

Default stack formatter which fetch the logging source and location.

defaultLevelFmt :: Level -> Builder () Source #

Format DEBUG to DEBUG, etc.

Level other than built-in ones, are formatted in decimal numeric format, i.e. defaultLevelFmt 60 == LEVEL60

type LogFormatter Source #


 = Builder ()

data/time string

-> Level

log level

-> Builder ()

log content

-> CallStack

call stack trace

-> Builder () 

defaultFmt :: LogFormatter Source #

A default log formatter

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

coloredFmt :: LogFormatter Source #

A default colored log formatter

DEBUG level is Cyan, WARNING level is Yellow, FATAL and CRITICAL level are Red.

pushLogIORef Source #


:: IORef [Bytes]

logs stored in a list, new log will be CASed into it.

-> Int

buffer size to build each log

-> Builder ()

formatted log

-> IO () 

Use pushLogIORef and pushLogIORef to implement a simple IORef based concurrent logger.

logsRef <- newIORef []
let push = pushLogIORef logsRef lineBufSize
    flush = flushLogIORef stderrBuf logsRef
    throttledFlush <- throttleTrailing_ flushInterval flush
return $ Logger push flush throttledFlush ...



type Level = Int Source #

Logging Levels

We following the Python logging levels, for details, see: https://docs.python.org/3/howto/logging.html#logging-levels

LevelNumeric value

pattern DEBUG :: Level Source #

pattern INFO :: Level Source #

pattern WARNING :: Level Source #

pattern FATAL :: Level Source #

pattern CRITICAL :: Level Source #

pattern NOTSET :: Level Source #