Copyright	(c) Dong Han 2017-2018
License	BSD
Maintainer	winterland1989@gmail.com
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Z.IO.Logger

Contents

A simple Logger type
logging functions
logging functions with specific logger
Helpers to write new logger
Constants
- Level

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

data Logger = Logger {
- loggerPushBuilder :: Builder () -> IO ()
- flushLogger :: IO ()
- flushLoggerThrottled :: IO ()
- loggerTSCache :: IO (Builder ())
- loggerFmt :: LogFormatter
- loggerLevel :: !Level
}
data LoggerConfig = LoggerConfig {
- loggerMinFlushInterval :: !Int
- loggerLineBufSize :: !Int
- loggerConfigLevel :: !Level
}
defaultLoggerConfig :: LoggerConfig
setDefaultLogger :: Logger -> IO ()
getDefaultLogger :: IO Logger
flushDefaultLogger :: IO ()
withDefaultLogger :: IO () -> IO ()
newLogger :: LoggerConfig -> MVar BufferedOutput -> IO Logger
newColoredLogger :: LoggerConfig -> IO Logger
newJSONLogger :: LoggerConfig -> MVar BufferedOutput -> IO Logger
debug :: HasCallStack => Builder () -> IO ()
info :: HasCallStack => Builder () -> IO ()
warning :: HasCallStack => Builder () -> IO ()
fatal :: HasCallStack => Builder () -> IO ()
critical :: HasCallStack => Builder () -> IO ()
otherLevel :: HasCallStack => Level -> Bool -> Builder () -> IO ()
debugTo :: HasCallStack => Logger -> Builder () -> IO ()
infoTo :: HasCallStack => Logger -> Builder () -> IO ()
warningTo :: HasCallStack => Logger -> Builder () -> IO ()
fatalTo :: HasCallStack => Logger -> Builder () -> IO ()
otherLevelTo :: HasCallStack => Logger -> Level -> Bool -> Builder () -> IO ()
defaultTSCache :: IO (Builder ())
defaultFmtCallStack :: CallStack -> Builder ()
defaultLevelFmt :: Level -> Builder ()
type LogFormatter = Builder () -> Level -> Builder () -> CallStack -> ThreadId -> Builder ()
defaultFmt :: LogFormatter
defaultColoredFmt :: LogFormatter
defaultJSONFmt :: LogFormatter
pushLogIORef :: IORef [Bytes] -> Int -> Builder () -> IO ()
flushLogIORef :: HasCallStack => MVar BufferedOutput -> IORef [Bytes] -> IO ()
type Level = Int
pattern DEBUG :: Level
pattern INFO :: Level
pattern WARNING :: Level
pattern FATAL :: Level
pattern CRITICAL :: Level
pattern NOTSET :: Level

A simple Logger type

data Logger Source #

Extensible logger type.

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 ())
An IO action return a formatted date/time string
loggerFmt :: LogFormatter
Log formatter
loggerLevel :: !Level
Output logs if level is equal or higher than this value.

data LoggerConfig Source #

Logger config type used in this module.

Constructors

LoggerConfig
Fields loggerMinFlushInterval :: !Int Minimal flush interval, see Notes on `debug` loggerLineBufSize :: !Int Buffer size to build each log line loggerConfigLevel :: !Level Config log's filter level

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

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

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

warning :: HasCallStack => Builder () -> IO () Source #

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

critical :: HasCallStack => Builder () -> IO () Source #

otherLevel Source #

Arguments

:: HasCallStack
=> Level	log level
-> Bool	flush immediately?
-> Builder ()	log content
-> IO ()

logging functions with specific logger

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

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

warningTo :: HasCallStack => Logger -> Builder () -> IO () Source #

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

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

flushLogIORef :: HasCallStack => MVar BufferedOutput -> IORef [Bytes] -> IO () Source #

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

Level	Numeric value
CRITICAL	50
FATAL	40
WARNING	30
INFO	20
DEBUG	10
NOTSET	0

pattern DEBUG :: Level Source #

pattern INFO :: Level Source #

pattern WARNING :: Level Source #

pattern FATAL :: Level Source #

pattern CRITICAL :: Level Source #

pattern NOTSET :: Level Source #