zlog使用手册

Contents
1 zlog是什么？ 5
1.1 兼容性说明. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 zlog 1.2 发布说明. . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 zlog不是什么？ 9
3 Hello World 11
3.1 编译和安装zlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 应用程序调用和链接zlog . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Hello World 代码. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.4 更简单的Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4 Syslog 模型15
4.1 分类(Category)、规则(Rule)和格式(Format) . . . . . . . . . . . . . . . . 15
4.2 syslog模型和log4j模型的区别. . . . . . . . . . . . . . . . . . . . . . 16
4.3 扩展syslog模型. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5 配置文件19
5.1 全局参数. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2 日志等级自定义. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.3 格式(Formats) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.4 转换格式串. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.4.1 转换字符. . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.4.2 宽度修饰符. . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4.3 时间字符. . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.5 规则(Rules) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5.1 级别匹配. . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5.2 分类匹配. . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.5.3 输出动作. . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.6 文件转档. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.7 配置文件工具. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3
4 CONTENTS
6 zlog接口(API) 35
6.1 初始化和清理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.2 分类(Category)操作. . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.3 写日志函数及宏. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.4 MDC操作. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.5 dzlog接口. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.6 用户自定义输出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.7 调试和诊断. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7 高阶使用43
7.1 MDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.2 诊断zlog本身. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.3 用户自定义等级. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.4 用户自定义输出. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
8 尾声53
Chapter 1
zlog是什么？
zlog是一个高可靠性、高性能、线程安全、灵活、概念清晰的纯C日志函数库。
事实上，在C的世界里面没有特别好的日志函数库（就像JAVA里面的的log4j，或者C++的
log4cxx）。C程序员都喜欢用自己的轮子。printf就是个挺好的轮子，但没办法通过配置改变
日志的格式或者输出文件。syslog是个系统级别的轮子，不过速度慢，而且功能比较单调。
所以我写了zlog。
zlog在效率、功能、安全性上大大超过了log4c，并且是用c写成的，具有比较好的通用性。
zlog有这些特性：
• syslog分类模型，比log4j模型更加直接了当
• 日志格式定制，类似于log4j的pattern layout
• 多种输出，包括动态文件、静态文件、stdout、stderr、syslog、用户自定义输出函数
• 运行时手动、自动刷新配置文件（同时保证安全）
• 高性能，在我的笔记本上达到25万条日志每秒, 大概是syslog(3)配合rsyslogd的1000倍速
度
• 用户自定义等级
• 多线程和多进程环境下保证安全转档
• 精确到微秒
• 简单调用包装dzlog（一个程序默认只用一个分类）
• MDC，线程键-值对的表，可以扩展用户自定义的字段
• 自诊断，可以在运行时输出zlog自己的日志和配置状态
• 不依赖其他库，只要是个POSIX系统就成(当然还要一个C99兼容的vsnprintf)
5
6 CHAPTER 1. ZLOG是什么？
相关链接：
软件下载： https://github.com/downloads/HardySimpson/zlog/zlog-latest-stable.tar.gz
源代码： git@github.com:HardySimpson/zlog.git
使用手册(pdf)： https://github.com/downloads/HardySimpson/zlog/UsersGuide-CN.pdf
问题讨论区： https://github.com/HardySimpson/zlog/issues
英文主页： http://hardysimpson.github.com/zlog/
中文主页： http://www.oschina.net/p/zlog
作者博客： http://my.oschina.net/HardySimpson/blog
邮箱： HardySimpson1984@gmail.com
1.1 兼容性说明
1. zlog是基于POSIX的。目前我手上有的环境只有AIX和linux。在其他的系统下（FreeBSD,
NetBSD, OpenBSD, OpenSolaris, Mac OS X...）估计也能行，有问题欢迎探讨。
2. zlog使用了一个C99兼容的vsnprintf。也就是说如果缓存大小不足，vsnprintf将会返回目
标字符串应有的长度（不包括'\0')。如果在你的系统上vsnprintf不是这么运作的，zlog
就不知道怎么扩大缓存。如果在目标缓存不够的时候vsnprintf返回-1，zlog就会认为这次
写入失败。幸运的是目前大多数c标准库符合C99标准。glibc 2.1,libc on AIX, libc on
freebsd...都是好的，不过glibc2.0不是。在这种情况下，用户需要自己来装一个C99兼
容的vsnprintf，来crack这个函数库。我推荐ctrio, 或者C99-snprintf。只要改buf.c就
行，祝好运！
3. zlog目前还没有计划支持windows，毕竟windows下已经有非常成熟的日志函数库。
1.2 zlog 1.2 发布说明
1. zlog 1.2 新增了这些功能
(a) 对管道的支持，从此zlog可以外接cronolog这样的日志过滤程序来输出
(b) 全面的日志转档支持，详见5.6
(c) 其他兼容性的代码改动
2. zlog 1.2 在库方面是和zlog 1.0/1.1二进制兼容的，区别在于：
(a) 所有的宏改为小写，ZLOG_INFO->zlog_info，方便开发者手工输入。这是一个巨大的
改变，如果zlog1.1/1.0的用户要用zlog 1.2的话，需要写一个脚本，把源代码中的
大写批量替换为小写，然后重新编译你的程序。我提供了一个脚本：
sed -i -e 's/\b\w*ZLOG\w*\b/\L&\E/g' aa.c
1.2. ZLOG 1.2 发布说明7
(b) 取消了auto tools的使用，也就是说，不论你在任何平台，都需要gcc和gnu make才能
编译安装zlog。主流的操作系统(Aix, OpenSolaris..)都能安装gcc和gnu make。当
然也可以自行修改makefile来完成编译，对于平台稍有经验的Geek都可以自行完成！
8 CHAPTER 1. ZLOG是什么？
Chapter 2
zlog不是什么？
zlog的目标是成为一个简而精的日志函数库，不会直接支持网络输出或者写入数据库，不
会直接支持日志内容的过滤和解析。
原因很明显，日志库是被应用程序调用的，所有花在日志库上的时间都是应用程序运行时
间的一部分，而上面说的这些操作都很费时间，会拖慢应用程序的速度。这些事儿应该在别的
进程或者别的机器上做。
如果你需要这些特性，我建议使用rsyslog、zLogFabric、Logstash，这些日志搜集、过
滤、存储软件，当然这是单独的进程，不是应用程序的一部分。
目前zlog已经支持7.4，可以自己实现一个输出函数，自由的把日志输出到其他进程或者其
他机器。而把日志的分类匹配、日志格式成型的工作交给zlog。
目前我的想法是实现一个zlog-redis客户端，用自定义输出功能，把日志存储到本机或者
远程的redis服务器内，然后用其他进程(也使用zlog库)来把日志写到文件里面，不知大家以为
这个想法如何？欢迎和我联系探讨。
9
10 CHAPTER 2. ZLOG不是什么？
Chapter 3
Hello World
3.1 编译和安装zlog
下载zlog-latest-stable.tar.gz
$ tar -zxvf zlog-latest-stable.tar.gz
$ cd zlog-1.2.*/
$ make
$ sudo make install
or
$ sudo make PREFIX=/usr/local/ install
PREFIX指明了安装的路径，安转完之后为了让你的程序能找到zlog动态库
$ sudo vi /etc/ld.so.conf
/usr/local/lib
$ sudo ldconfig
在你的程序运行之前，保证libzlog.so在系统的动态链接库加载器可以找到的目录下。上面的
命令适用于linux，别的系统自己想办法。
• 除了一般的make以外，还可以
$ make 32bit # 32bit version on 64bit machine, libc6-dev-i386 is needed
$ make noopt # without gcc optimization
$ make doc # lyx and hevea is needed
$ make test # test code, which is also good example for zlog
• makefile是用GNU make的格式写的，所以在你的平台上需要预装gnu make和gcc。或者，手
工修改一个自己平台的makefile也行。
11
12 CHAPTER 3. HELLO WORLD
3.2 应用程序调用和链接zlog
应用程序使用zlog很简单，只要在C文件里面加一行。
#include "zlog.h"
链接zlog需要pthread库，命令是：
$ cc -c -o app.o app.c -I/usr/local/include
# -I[where zlog.h is put]
$ cc -o app app.o -L/usr/local/lib -lzlog -lpthread
# -L[where libzlog.so is put]
3.3 Hello World 代码
这些代码在$(top_builddir)/test/test_hello.c, test_hello.conf
1. 写一个C文件：
$ vi test_hello.c
#include <stdio.h>
#include "zlog.h"
int main(int argc, char** argv)
{
int rc;
zlog_category_t *c;
rc = zlog_init("test_hello.conf");
if (rc) {
printf("init failed\n");
return -1;
}
c = zlog_get_category("my_cat");
if (!c) {
printf("get cat fail\n");
zlog_fini();
return -2;
}
zlog_info(c, "hello, zlog");
zlog_fini();
return 0;
3.4. 更简单的HELLO WORLD 13
}
2. 写一个配置文件，放在和test_hello.c同样的目录下:
$ vi test_hello.conf
[formats]
simple = "%m%n"
[rules]
my_cat.DEBUG >stdout; simple
3. 编译、然后运行!
$ cc -c -o test_hello.o test_hello.c -I/usr/local/include
$ cc -o test_hello test_hello.o -L/usr/local/lib -lzlog
$ ./test_hello
hello, zlog
3.4 更简单的Hello World
这个例子在$(top_builddir)/test/test_default.c, test_default.conf. 源代码是：
#include <stdio.h>
#include "zlog.h"
int main(int argc, char** argv)
{
int rc;
rc = dzlog_init("test_default.conf", "my_cat");
if (rc) {
printf("init failed\n");
return -1;
}
dzlog_info("hello, zlog");
zlog_fini();
return 0;
}
配置文件是test_default.conf，和test_hello.conf一模一样，最后执行程序的输出也一样。
区别在于这里用了dzlog API，内含一个默认的zlog_category_t。详见6.5。
14 CHAPTER 3. HELLO WORLD
Chapter 4
Syslog 模型
4.1 分类(Category)、规则(Rule)和格式(Format)
zlog有3个重要的概念：分类(Category)、规则(Rule)和格式(Format)。
分类(Category)用于区分不同的输入。代码中的分类变量的名字是一个字符串，在一个程序
里面可以通过获取不同的分类名的category用来后面输出不同分类的日志，用于不同的目的。
格式(Format)是用来描述输出日志的格式，比如是否有带有时间戳，是否包含文件位置信
息等，上面的例子里面的格式simple就是简单的用户输入的信息+换行符。
规则(Rule)则是把分类、级别、输出文件、格式组合起来，决定一条代码中的日志是否输
出，输出到哪里，以什么格式输出。
所以，当程序执行下面的语句的时候
zlog_category_t *c;
c = zlog_get_category("my_cat");
zlog_info(c, "hello, zlog");
zlog会找到c的名字是"my_cat"，对应的配置文件中的规则是
[rules]
my_cat.DEBUG >stdout; simple
然后库会检查，目前这条日志的级别是否符合规则中的级别来决定是否输出。因为INFO>=DEBUG，
所以这条日志会被输出。并且根据这条规则，会被输出到stdout（标准输出） ，输出的格式是
simple，在配置文件中定义是
[formats]
simple = "%m%n"
最后在屏幕上打印
hello, zlog