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
Create a new logger
logging functions
logging functions with specific logger
Helpers to write new log formatter
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
data LoggerConfig = LoggerConfig {
- loggerMinFlushInterval :: !Int
- loggerLineBufSize :: !Int
- loggerConfigLevel :: !Level
- loggerFormatter :: LogFormatter
}
defaultLoggerConfig :: LoggerConfig
defaultJSONLoggerConfig :: LoggerConfig
setDefaultLogger :: Logger -> IO ()
getDefaultLogger :: IO Logger
flushDefaultLogger :: IO ()
withDefaultLogger :: IO () -> IO ()
newLogger :: LoggerConfig -> MVar BufferedOutput -> IO Logger
newStdLogger :: LoggerConfig -> IO Logger
newFileLogger :: LoggerConfig -> CBytes -> 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 ()
type LogFormatter = Builder () -> Level -> Builder () -> CallStack -> ThreadId -> Builder ()
defaultFmt :: LogFormatter
defaultColoredFmt :: LogFormatter
defaultJSONFmt :: LogFormatter
defaultFmtCallStack :: CallStack -> Builder ()
defaultLevelFmt :: Level -> Builder ()
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.

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 loggerFormatter :: LogFormatter Log formatter

defaultLoggerConfig :: LoggerConfig Source #

A default logger config with

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

defaultJSONLoggerConfig :: LoggerConfig Source #

A default logger config with

0.5s minimal flush interval
line buffer size 1000 bytes
show everything by default
defaultJSONFmt

setDefaultLogger :: Logger -> IO () Source #

Change the global logger.

getDefaultLogger :: IO Logger Source #

Get the global logger.

This is a logger connected to stderr, if stderr is connect to TTY, then use defaultColoredFmt, otherwise use defaultFmt.

flushDefaultLogger :: IO () Source #

Manually flush global logger.

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

Flush global logger when program exits.

Create a new logger

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

Make a new logger with given write device.

newStdLogger :: LoggerConfig -> IO Logger Source #

Make a new logger write to stderrBuf.

newFileLogger :: LoggerConfig -> CBytes -> IO Logger Source #

Make a new file based logger with defaultFmt.

The file will be opened in append mode.

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 log formatter

type LogFormatter Source #

Arguments

= Builder ()	data/time string(second precision)
-> 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

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

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 #