Z-IO-0.6.1.0: Simple and high performance IO toolkit for Haskell
Copyright(c) Dong Han 2017-2018
LicenseBSD
Maintainerwinterland1989@gmail.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Z.IO.Logger

Description

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

A simple Logger type

data Logger Source #

Extensible logger type.

Constructors

Logger 

Fields

data LoggerConfig Source #

Logger config type used in this module.

Constructors

LoggerConfig 

Fields

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, see defaultFmt.

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.

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

Make a new structured JSON logger, see defaultJSONFmt

logging functions

otherLevel Source #

Arguments

:: HasCallStack 
=> Level

log level

-> Bool

flush immediately?

-> Builder ()

log content

-> IO () 

logging functions with specific logger

otherLevelTo Source #

Arguments

:: 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 #

Arguments

 = Builder ()

data/time string

-> Level

log level

-> Builder ()

log content

-> CallStack

call stack trace

-> ThreadId

logging thread id

-> Builder () 

defaultFmt :: LogFormatter Source #

A default log formatter

[FATAL][2021-02-01T15:03:30+0800][interactive:31:1][thread#669]...

defaultColoredFmt :: LogFormatter Source #

A default colored log formatter

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

defaultJSONFmt :: LogFormatter Source #

A default JSON log formatter.

{"level":FATAL,"time":"2021-02-01T15:02:19+0800","loc":"interactive:27:1","theadId":606,"content":"..."}\n

pushLogIORef Source #

Arguments

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

Constants

Level

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
CRITICAL50
FATAL40
WARNING30
INFO20
DEBUG10
NOTSET0

pattern DEBUG :: Level Source #

pattern INFO :: Level Source #

pattern WARNING :: Level Source #

pattern FATAL :: Level Source #

pattern CRITICAL :: Level Source #

pattern NOTSET :: Level Source #