Contents
1 What is zlog? 3
1.1 zlog 1.0 Release Notes: . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 What is not zlog? 5
3 Hello World 6
3.1 Build and Installation zlog . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2 Call and Link zlog in User’s application . . . . . . . . . . . . . . . . 7
3.3 Hello World Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.4 Simpler Hello World Example . . . . . . . . . . . . . . . . . . . . . . 9
4 Syslog model 10
4.1 Category, Rule and Format . . . . . . . . . . . . . . . . . . . . . . . 10
4.2 The difference between syslog model and log4j model . . . . . . . . . 11
4.3 Expand syslog model . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5 Configure File 14
5.1 Global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.3 Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.4 Conversion pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.4.1 Conversion Characters . . . . . . . . . . . . . . . . . . . . . . 19
5.4.2 Format Modifier . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.4.3 Time Character . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.5 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.5.1 Level Matching . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.5.2 Category Matching . . . . . . . . . . . . . . . . . . . . . . . . 26
5.5.3 Output Action . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.6 Configure File Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
1
CONTENTS 2
6 zlog API 30
6.1 initialize and finish . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.2 category operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.3 log functions and macros . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.4 MDC operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.5 dzlog API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.6 User-defined Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.7 debug and profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
7 Advance Using 38
7.1 MDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.2 Profile zlog Itself . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.3 User-defined Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.4 User-defined Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Chapter 1
What is zlog?
zlog is a reliable, high efficent, thread safe, flexsible, clear model, pure c logging
library
Actually, in the c world there is NO good logging library for application like
logback in java or log4cxx in c++. printf can work, but can not be easily redirected
or reformat, syslog is slow and is designed for system use.
So I write zlog.
It is faster, safer and more powerful than log4c. So it can be widely used.
zlog has feartures below:
• syslog model, better than log4j model
• log format customization
• multiple output, include static file path, dynamic file path, stdout, stderr,
syslog, user-defined ouput
• runtime mannully or automaticlly refreash configure(safely)
• high efficieny, about 200 times faster than syslog(3) with rsyslogd
• user-defined log level
• safely rotate log file on multiple-process or multiple-threads condition
• accurate to microseconds
• dzlog, a default category log API for easy use
• MDC, a log4j style key-value map
3
CHAPTER 1. WHAT IS ZLOG? 4
• self debugable, can output zlog’s self debug&error log at runtime
• Not depend on any other 3rd party library, just base on POSIX system(and a
C99 compliant vsnprintf).
Links:
Download: https://github.com/downloads/HardySimpson/zlog/zlog-latest-stable.tar.gz
GettingStart: doc/GettingStart-CN.txt GettingStart-EN.txt
UsersGuide: doc/UsersGuide-CN.pdf UsersGuide-EN.pdf
SourceCode: git@github.com:HardySimpson/zlog.git
Mail List: https://github.com/HardySimpson/zlog/issues
Homepage(in English): http://hardysimpson.github.com/zlog
Homepage(in Chinese): http://www.oschina.net/p/zlog
Author’s Blog(in Chinese): http://my.oschina.net/HardySimpson/blog
Author’s Email: HardySimpson1984@gmail.com
1.1 zlog 1.0 Release Notes:
1. zlog is based on POSIX-compatible system. I just have GNU/linux and AIX
envrionment and test to compile and run zlog on them. Still I think zlog will
work well on FreeBSD, NetBSD, OpenBSD, OpenSolaris, Mac OS X etc. Test
run zlog on any system is welcome.
2. in zlog, I use a feature of C99 compliant vsnprintf. That is, if the buffer
size of destination is not long enough, vsnprintf will return the the number of
characters (not includ- ing the trailing ’\0’) which would have been written to
the final string if enough space had been available. If the vsnprintf on your
sysem is not work like that, zlog can not know the right buffer size when a single
log is longer than buffer. Fortunately, glibc 2.1,libc on AIX, libc on freebsd...
work in the right way, while glibc 2.0 is not. In this case, user should crack
zlog himself with a C99 compliant vsnprintf. I suggest ctrio, or C99-snprintf.
The file buf.c should be cracked, good luck!
3. zlog 1.0 is not compatible with zlog 0.9. I change zlog() in zlog.h for more
arguments, as func which points the function where the log takes place. I
change zlog.conf also, which is divided into some sections for more clarity. If
The user of zlog 0.9 want to update to zlog 1.0, he should re-compile his source
code(but need not to change it), as all macros of zlog 1.0 are the same as zlog
0.9.
