配置文件

zlog是一个通用日志库，基本功能跟专用日志库并没有本质区别。通用日志库，通过配置文件，来简化一些列日志使用和配置，以适应各种不同项目需求。而配置文件承载了这角色，为不同项目需求定制不同的功能，主要包括：把日志打印到哪儿去，用什么格式，如何转档等。

例如，一个完整的配置文件内容如下：

# comments
[global]
strict init = true
buffer min = 1024
buffer max = 2MB
rotate lock file = /tmp/zlog.lock
default format = "%d.%us %-6V (%c:%F:%L) - %m%n"
file perms = 600

[levels]
TRACE = 10
CRIT = 130, LOG_CRIT

[formats]
simple = "%m%n"
normal = "%d %m%n"

[rules]
default.*               >stdout; simple
*.*                    "%12.2E(HOME)/log/%c.log", 1MB*12; simple
my_.INFO              >stderr;
my_cat.!ERROR         "/var/log/aa.log"
my_dog.=DEBUG         >syslog, LOG_LOCAL0; simple
my_mice.*             $user_define;

单位说明：
当设置内存、文件大小，或较大数字时，可设置1k 5GB 4M这样的单位

# 1k => 1000 bytes
# 1kb => 1024 bytes
# 1m => 1000000 bytes
# 1mb => 1024*1024 bytes
# 1g => 1000000000 bytes
# 1gb => 1024*1024*1024 byte

注：单位大小写不敏感，1GB <=> 1gb <=> 1Gb <=> 1gB。

全局参数

可选。
全局参数以[global]开头，"[]"代表一个字节开始，四个小节顺序不能变：global -> levels -> formats -> rules。

语法格式：

(key) = (value)

比如上面的"strict init = true"中，"strict init"是key，"true"是value。

• strict init

如果"strict init"值为true，那么zlog_init()将严格检查所有的格式和规则，任何错误都会导致zlog_init()失败并返回-1；如果为false，zlog_init()将忽略错误的格式和规则。该参数默认为true。

• reload conf period

该选项让zlog能在一段时间后，自动重载配置文件。重载的间隔以每进程写日志的次数来定义。当写日志次数到了一定值后，内会将会调用zlog_reload()进行重载。每次zlog_reload()或zlog_init()后重新计数累加。因为zlog_reload()是原子的，重载失败继续用当前的配置信息，所以自动重载是（线程）安全的。默认值0，标识自动重载关闭。

• buffer min和buffer max

zlog在堆上为每个线程申请缓存。"buffer min"是单个缓存最小值，zlog_init()申请这个长度的内存。写日志时，如果单条日志长度 > 缓存大小，缓存会自动扩充，直到"buffer max"。单条日志长度 > "buffer max"时，该日志就会被截断。如果"buffer max"值为0，表示不限制缓存，每次扩充为原来2倍，直到进程用完所有内存。
缓存大小默认使用byte作为单位，可以显式加上KB，MB或GB单位。"buffer min"默认值1K，"buffer max默认值2MB。

所谓截断，通常是指将末尾的几个数据替换为如"..."（zlog_buf_new()调用者决定），让用户知道内容发生阶段。

• ratate lock file

该选项指定一个锁文件，用来保证多进程情况下日志安全转档。zlog会在zlog_init()时，以读写权限打开该文件。

请确认你执行APP的用户有权限创建和读写该锁文件。

转档日志的伪代码：

write(log_file, a_log)
if (log_file > 1M) 
    if (pthread_mutex_lock succ && fcntl_lock(lock_file) succ)
        if (log_file > 1M) rotate(log_file);
        fcntl_unlock(lock_file);
        pthread_mutex_unlock;

mutex 锁（互斥锁）用于多线程，fcntl 锁（POSIX建议锁）用于多进程。进程意外死亡后，OS会释放此进程持有的锁。这是zlog选择用fcntl锁保证安全转档的重要原因。

rotate lock file默认值是/tmp/zlog.lock。

如果rotate lock file = self，此时，zlog不会创建任何锁文件，用配置文件作为锁文件。而fnctl是建议锁（并非强制锁），用户可自由修改、存储配置文件。一般地，单个日志文件不会被不同OS用户的进程转档，所以用配置文件作为锁文件是安全的。

如果用户设置其他路径作为锁文件，如/tmp/zlog.lock，zlog会在zlog_init()时创建该文件。如果有多个OS用户的进程需要转档同一个日志文件，确认该锁文件id多个用户都可读写。

• default format

缺省日志格式，默认值：

%d %V [%p:%F:%L] %m%n"

该格式输出形如：

2022-09-11 12:14:52 INFO [14210:test_hello.c:33] info, zlog

• file perms

指定了创建日志文件的缺省访问权限。必须注意最后产生的日志文件权限为"file perms" & ~umask。umask是进程操作文件的权限的掩码。

默认值为0x600（"rw-------"），表示只允许当前用户读写。

• fsync period

每条规则写了一定次数的日志消息到文件后，zlog会调用fsync(3)让OS马上把数据写到硬盘。次数是每条规则单独统计的，并且在zlog_reload()后会清0。需要指出的是，在日志文件名是动态生成或者被转档的情况下，zlog不能保证把所有文件都搞定，zlog只fsync()那个时候刚刚write()的文件描述符。这提供了写日志速度和数据安全性之间的平衡。

例如：

$ time ./test_press_zlog 1 10 100000
real 0m1.806s
user 0m3.060s
sys 0m0.270s

$ wc -l press.log
1000000 press.log

$ time ./test_press_zlog 1 10 100000 # fsync period = 1K
real 0m41.995s
user 0m7.920s
sys  0m0.990s

$ time ./test_press_zlog 1 10 100000 # fsync period = 10K
real 0m6.856s
user 0m4.360s
sys 0m0.550s

如果你非常在乎安全而不是速度，建议用同步IO文件，参见【输出动作】部分。

默认值0，由OS决定何时冲刷缓存到文件。

日志等级

可选。除了支持系统默认的几个日志等级：DEBUG，INFO，NOTICE，WARN，ERROR，FATAL。zlog还支持用户自定义日志等级。语法：

(level string) = (level int), (syslog level, optional)

(level int)必须在[1, 253]之间，值越大表示越重要。

用户自定义等级

如果用户需要自定义一个等级，如TRACE（没有在默认等级中），可以按下面步骤进行配置。

步骤：
1）在配置文件中定义新的等级

$ cat $(top_builddir)/test/test_level.conf
[global]
default format  =               "%V %v %m%n"
[levels]
TRACE = 30, LOG_DEBUG
[rules]
my_cat.TRACE            >stdout;

内置默认等级（不需要写在配置文件里面）：

DEBUG = 20, LOG_DEBUG
INFO = 40, LOG_INFO
NOTICEC = 60, LOG_NOTICE
WARN = 80, LOG_WARNING
ERROR = 100, LOG_ERR
FATAL = 120, LOG_ALERT
UNKNOWN = 254, LOG_ERR

自定义的等级数，必须在[1, 253]之间，其他数字非法。数字越大，代表越重要。现在， TRACE等级为30，比DEBUG（等级20）高，比INFO等级低（等级40）。这样，TRACE就能在下面的配置文件中用了。例如：

my_cat.TRACE >stdout;

意味着等级 >= TRACE的，包括INFO，NOTICE，WARN，ERROR，FATAL都会被写到标准输出中。

格式里面的转换字符%V会产生等级字符串的大写输出，%v会产生小写的等级字符串输出。

另外，在等级的定义里面，LOG_DEBUG是指当需要输出到syslog时，自定义的TRACE等级会以LOG_DEBUG输出到syslog。

2）在源代码里面直接用新的等级
注意：这个.c文件和下面的.h文件，相当于是用户程序自定义的，并非库运行时的程序。

zlog(cat, __FILE__, sizeof(__FILE__)-1, \
    __func__, sizeof(__func__)-1, __LINE__, \
    30, "test %d", 1); // 30 是刚刚自定义的TRACE

为了简单使用，创建一个.h头文件。

$ cat $(top_builder)/test/test_level.h
#ifndef __test_level_h
#define __test_level_h

#include "zlog.h"

enum {
    ZLOG_LEVEL_TRACE = 30,
    /* must equals conf file setting */
};

#define zlog_trace(cat, format, ...) \
        zlog(cat, __FILE__, sizeof(__FILE__)-1, \
        __func__, sizeof(__func__)-1, __LINE__, \
        ZLOG_LEVEL_TRACE, format, ## __VA_ARGS__)

#endif

3）这样zlog_trace就能在.c文件里面调用了

$ cat $(top_builddir)/test/test_level.c
#include <stdio.h>
#include "test_level.h"

int main(int argc, char *argv[])
{
    int rc;
    zlog_category_t *zc;

    rc = zlog_init("test_level.conf"); /* 以配置文件test_level.conf初始化zlog库 */
    if (rc) {
        printf("init failed\n");
        return -1;
    }

    zc = zlog_get_category("my_cat");
    if (!zc) {
        printf("get cat fail\n");
        zlog_fini(); /* 反初始化zlog库 */
        return -2;
    }

    zlog_trace(zc, "hello, zlog - trace");
    zlog_debug(zc, "hello, zlog - debug");
    zlog_info(zc, "hello, zlog - debug");
    zlog_fini();

    return 0;
}

4）最后，可以观察到输出

$ ./test_level
TRACE trace hello, zlog - trace
INFO info hello, zlog - info

这正是我们所期待的，配置文件只允许 >= TRACE等级的日志输出到屏幕上。配置文件test_level.conf中的%V %v，也显示了正确的结果。

格式（Formats）

以[formats]开始，用来定义日志的格式。语法：

(name) = "(actual formats)"

后面的规则（rules）需要引用时，就通过(name)。(name)必须由数字、字母、下划线（"_"）组成。(actual format)需要用双引号包裹，可以由转换字符串组成，见【转换格式串】部分。

e.g. 截取formats及rules中引用示例

[formats]
simple = "%m%n"
normal = "%d %m%n"

[rules]
default.*               >stdout; simple

这里，"simple"就是格式name，"%m%b"就是转换格式串。

转换格式串

转换格式串的设计是从C标准的printf抄过来的。一个转换格式串由文本字符和转换说明组成。

转换格式串用于规则（rules）的日志文件路径，输出格式（format）中。

你可以把任意的文本字符放到转换格式串里面。

每个转换说明都是以百分号（%）打头，后面跟可选的宽度修饰符，最后以转换字符结尾。转换字符决定了输出什么数据，例如分类名、级别、时间日期、进程号等。宽度修饰符控制了这个字段的最大最小宽度、左右对齐。

例如，如果转换格式串是

"%d(%m-%d %T) %-8V [%p:%F:%L] %m%n"

说明："%"开头+若干字母，能被zlog识别的，称为转换字符。
像"-" ":" "[" "]" " "()等，称为文本字符。
这里%-8V，表示日志级别要大写，并且左对齐，占用8个字符宽度。

源代码中，写log语句是：

zlog_info(c, "hello, zlog");

将会输出：

09-11 15:37:21 INFO     [27608:test_hello.c:33] info, zlog

转换字符

zlog可以识别的转换字符有：

宽度修饰符

通常，数据按原样输出。不过，因为不同消息的各字段长度不一样，如果要控制不同消息对齐，该怎么办？
可以使用宽度修饰符，控制最小字段宽度、最大字段宽度和左右对齐方式。需要付出一定性能代价。

宽度修饰符，可选，位于%和转换字符之间。

• 左对齐标识

左对齐标识，用减号（-）表示。

• 最小字段宽度

十进制数常量，表示最少有几个字符会被输出。如果数据本来没有那么多字符，将会填充空格（左对齐/右对齐）直到最小宽度为止。默认填充在字段的左边，也就说右对齐。如果使用了左对齐标识，那么就填充在右边。填充字符为空格（）。如果数据宽度 > 最小宽度，则按数据宽度输出，不会截断数据。

例如，前面的

[formats]
simple = "%d(%m-%d %T) %-8V [%p:%F:%L] %m%n"
%-8V：表示日志级别字段左对齐，最小宽度8.

输出log：

09-11 15:37:21 INFO     [27608:test_hello.c:33] info, zlog

即这里日志级别"INFO"后会跟5个空格（8 - 3 = 5），还有1个空格是simple原有固定的空格。

而最大字段宽度，可以截断数据。最大字段宽度是放在一个句点号(.)后面的十进制数常量。如果数据宽度超过最大字段宽度，则尾部多余的字符（超过最大字段宽度的部分）将会被截去。如果最大宽度字段8，数据宽度10，那么最后2个字符会被丢弃。该行为和C的printf一样，把后面的部分截断。

下面是各种宽度修饰符和分类转换字符（%c）配合一起使用的例子。

时间字符

转换字符d 支持的时间字符，即%d()括号中的内容。
所有字符都由strftime(2)生成。在Linux OS上支持的是：

规则（Rules）

描述了日志怎么被过滤、格式化以及被输出。语法：

(category).(level)    (output), (options, optional); (format name, optional)

当zlog_init()被调用时，所有规则都会被读到内存中。当zlog_get_category()被调用时，规则就会被分配给分类。在实际写日志的时候，例如zlog_info()被调用的时候，就会比较这个INFO和各条规则的等级，来决定这条日志会不会通这条规则输出。当zlog_reload()被调用时，配置文件会被重新读入，包括所有的规则，并且重新计算分类对应的规则。

级别匹配

规则中，level字段决定级别。
zlog有6个默认的级别：DEBUG, INFO, NOTICE, WARN, ERROR, FATAL。像其他的日志函数库，aa.DEBUG意味着任何 >= DEBUG级别的日志会被输出。

分类匹配

分类必须由数字和字母组成，下划线"_"也算字母。

输出动作

目前zlog支持若干种输出，语法：

[输出],[附加选项, 可选]; [format(格式)名, 可选]

• stdout, stderr, syslog

如表格描述，其中只有syslog的附加选项是有意义并且必须写到。
值得注意的是，zlog在写日志的时候，会用这样的语句：

write(STDOUT_FILENO, zlog_buf_str(a_thread->msg_buf), zlog_buf_len(a_thread->msg_buf));

如果你的程序是一个守护进程，那么在启动时候就会把STDOUT_FILENO，也就说值为1的文件描述符关闭，会发生什么？
日志会被写到新的值为1的文件描述符所代表的文件里。有用户就反馈过，zlog把日志写到自己的配置文件里面去了。

因此，不要在守护进程的规则里加上>stdout或>stderr。这会产生未定义行为。如果一定要输出到终端（STDOUT_FILENO），那么用"/dev/tty"代替。

• 管道输出

*.*    | /usr/bin/cronolog /www/logs/example_%Y%m%d.log ; normal

这是一个将zlog的输出到管道后接cronolog的例子。实现原理很简单，在zlog_init时，调用popen("/usr/bin/cronolog /www/logs/example_%Y%m%d.log", "w")，后面往这个文件描述符写指定格式的日志。使用cronolog来生成按天分割的日志效率，比zlog自己的动态路径的效率要高，因为通过管道，无需每次都打开、关闭动态路径的文件描述符。

[rules]
*.*              "press%d(%Y%m%d).log"
$ time ./test_press_zlog 1 10 100000
real 0m4.240s
user 0m2.500s
sys 0m5.460s

[rules]
*.*                  / /usr/bin/cronolog press%Y%m%d.log
$ time ./test_press_zlog 1 10 100000
real 0m1.911s
user 0m1.980s
sys 0m1.470s

使用管道也有限制：
1）POSIX.1-2001 保证读写不大于PIPE_BUF大小的内容是原子的。Linux上，PIPE_BUF为4096。
2）单条日志的长度超过PIPE_BUF时，并且有多个有父子关系的进程通zlog写同一个管道，也就说zlog_init之后fork多个子进程，此时只有一个cronolog的进程监听一个管道描述符，日志内容可能会交错。
3）多个进程分别调用zlog_init，启动多个cronolog进程，写拥有同一个文件路径的日志文件，即单条日志长度不超过PIPE_BUF，也有可能导致日志交错，因为cronolog读到的文件流是连续的，它不知道单条日志的边界在哪。

总结下，使用管道来输出到单个日志文件的情况：
1）单进程写，单条日志长度不限制。单进程内的多线程写日志的原子性已经由zlog保证。
2）有父子关系的多进程，单条日志长度不能超过PIPE_BUF（4096）。
3）无父子关系的多进程使用管道同时写一个日志，无论单条日志长度是多少，都有可能导致日志交错。

zlog本身的直接文件输出能保证即使多进程，同时调用zlog写一个日志文件也不会产生交错。

• 文件

1）文件路径
可以说相对路径或绝对路径，被双引号（""）包含。转换格式串可以用在文件路径上。例如，文件路径是"%E(HOME)/log/out.log"，环境变量$HOME是/home/harry，最后的输出文件是/home/harry/log/output.log。详见【转换格式串】部分。

zlog文件功能强大，例如：
（1）输出到命名管道（FIFO），必须在调用前由mkfifo(1)创建

*.*    "/tmp/pipefile"

（2）输出到NULL，也就是不输出

*.*    "/dev/null"

（3）在任何情况下输出到终端

*.*    "/dev/tty"

（4）每个线程一个日志，在程序运行的目录下

*.*     "%T.log"

（5）输出到有进程号区分的日志，每天，在$HOME/log目录，每1GB转档一次，保持5个日志文件。

*.*     "%E(HOME)/log/aa.%p.%d(%F).log",1GB * 5

（6）aa_及下级分类，每个分类一个日志

aa_.*      "/var/log/%c.log"

• 文件转档

控制文件的大小和个数。zlog根据这个字段来转档，当日志文件太大时，例如

"%E(HOME)/log/out.log", 1M * 3 ~ "%E(HOME)/log/out.log.#r"

这三个参数都不是必填项，zlog转档功能详见【文件转档】。

• 同步IO文件

在文件路径前加一个"-"，就打开了同步IO选项 。在打开文件（open）时，会以O_SYNC选项打开，此时，每次写日志操作都会等OS把数据写到硬盘后才返回。该选项极为耗时：

$ time ./test_press_zlog 100 1000
real 0m0.732s
user 0m1.030s
sys 0m1.080s
$ time ./test_press_zlog 100 1000 # synchronous I/O open
real 0m20.646s
user 0m2.570s
sys 0m6.950s

• 格式名

可选。如果不写，用全局配置里面的默认格式

[global]
default format = "%d(%F %T) %V [%p:%F:%L] %m%n"

• 用户自定义输出

详见【用户自定义输出】部分。

文件转档

为什么需要日志文件转档？
因为日志文件过大，可能导致系统硬盘被撑爆；或者，单个日志文件过大，导致grep需要花费很多时间来查找需要匹配的日志。

日志转档，有以下范式：

1）按固定时间段来切分日志

如每天生成一个日志文件

aa.2022-08-02.log
aa.2022-08-03.log
aa.2022-08-04.log

适用场景：管理员大概知道每天生成日志量，然后希望在n个月后，能精确找到某天所有日志。这种日志切分最好由日志库来完成，其次由cronosplit软件分析日志内容的时间字符串后进行切分，最后是用crontab+logrotate或mv来定期移动（但不精确，会造成若干条当前日志被放到上一天的文件里面去）。

zlog完成这种需求，很简单，只需要在（输出）日志文件名里设置时间日期字符串就行了

*.* "aa.%d(%F).log"

如果用cronolog，速度会更快点

*.* | cronolog aa.%F.log

2）按照日志大小切分

多用于开发环境，适用场景：程序在短时间生成大量日志，而vi、ue等编辑器打开速度过慢。同样地，这种日志切分可用在事后用split等工具来完成，但对于开发而言会增加步骤，所以最好由日志库来完成。

存档有两种模式：nlog里称为Sequence和Rolling。

Sequence的例子：

aa.log (new)
aa.log.2 (less new)
aa.log.1
aa.log.0 (old)

Rolling的例子：

aa.log (new)
aa.log.0 (less new)
aa.log.1
aa.log.2 (old)

其中，aa.log永远是当前最新的log。Sequence和Rolling的区别，就是后缀0，1，2，谁是次新的，谁是最旧的。

如果只有若干个最新的文件才有意义，需要日志库做主动的删除旧log的工作。由外部程序判断哪些是旧的很难。

最简单的zlog转档配置

[rules]
*.*     "aa.log", 10MB

该配置是Rolling的情况，每次aa.log超过10MB的时候，会这样做重命名：

aa.log.2 -> aa.log.3
aa.log.1 -> aa.log.2
aa.log.0 -> aa.log.1
aa.log   -> aa.log.0

上面配置可用写更啰嗦一点：

[rules]
*.*     "aa.log", 10MB * 0 ~ "aa.log.#r"

逗号后，第一个参数表示文件达到多大后，开始进行转档；
第二个参数表示保留多少个存档文件（0表示不删除任何存档文件）；
第三个参数表示转档的文件名，其中#r表示存档文件的序号，r是rolling的缩写。还可以放#s，s是sequence缩写。转档文件名必须包含#r或#s。

3）按照日志大小切分，但同时加上时间标签

aa.log
aa.log-20070305.00.log
aa.log-20070501.00.log
aa.log-20070501.01.log
aa.log-20071008.00.log

这种情况适合于程序本身的日志不是很受关注，但又在某天想要找出来看看。当然，这种情况下，万一在20070501这天日志的量超过指定值，如100MB，就要退回到第二种状态，在文件名种加后缀。

注：第二种状态，纯粹看日志大小进行切分，有可能多天的日志都混在一起。

zlog对应配置：

*.*     "aa.log", 100MB ~ "aa-%d(%Y%m%d).#2s.log"

每到100MB时转档，转档文件名支持转换字符，可用把转档当时的时间串作为转档文件名的一部分。#2s的意思是序号长度最少2位，从00开始编号，Sequence转档。

4）压缩、移动、删除旧的日志

压缩不应该由日志库来完成，因为压缩消耗大量CPU时间。日志库的任务是配合压缩。

对于第一种和第三种，管理较为简单，只要符合某些文件名规则或修改日期的，用shell脚本+crontab轻易压缩、移动和删除。

如果一定要转档的同时进行压缩，只有logrotate能干这活，毕竟是独立的程序，能转档同时搞压缩，不会混淆。

5）zlog对外部转档工具，如logrotate的支持

zlog的转档功能极为强大，有几种是zlog无法处理的，如按时间条件进行转档，转档前后调用一些自制的shell脚本... 这会把zlog配置和表达弄得过于复杂而缺乏美感。

此时，你也许喜欢用一些外部转档工具，如logrotate来完成工作。问题是，Linux OS下，转档工具重命名日志文件名后，APP还是往原来的文件描述符写日志，没办法重新打开日志文件写新的日志。标准做法是给APP一个信号，让其重新打开日志文件，对syslog是

$ kill -SIGHUP 'cat /var/run/syslogd.pid'

对于zlog，因为是个函数库，不适合接受信号。zlog提供函数接口zlog_reload()，该函数会重载配置文件，重新打开所有的日志文件。APP在收到信号logrotate的信号，或者相关命令后，可用调用该函数，重新打开所有日志文件。

配置文件工具

zlog源码src路径下，有个zlog-chk-conf.c源码文件，执行"$ make"命令编译后，会生成zlog-chk-conf目标程序。该程序尝试读取配置文件，检查语法，然后往屏幕上输出这些配置文件是否正确。建议每次创建或改动一个配置文件后，都用这个工具检查一下。

$ ./zlog-chk-conf -h
usage: zlog-chk-conf [conf files]...
        -q,     suppress non-error message
        -h,     show help message
zlog version: 1.2.12

用zlog-chk-conf检查配置文件zlog.conf（error）：

$ ./zlog-chk-conf zlog.conf
03-08 15:35:44 ERROR (10595:rule.c:391) sscanf [aaa] fail, category or level is null
03-08 15:35:44 ERROR (10595:conf.c:155) zlog_rule_new fail [aaa]
03-08 15:35:44 ERROR (10595:conf.c:258) parse configure file[zlog.conf] line[126] fail
03-08 15:35:44 ERROR (10595:conf.c:306) zlog_conf_read_config fail
03-08 15:35:44 ERROR (10595:conf.c:366) zlog_conf_build fail
03-08 15:35:44 ERROR (10595:zlog.c:66) conf_file[zlog.conf], init conf fail
03-08 15:35:44 ERROR (10595:zlog.c:131) zlog_init_inner[zlog.conf] fail

---[zlog.conf] syntax error, see error message above

可以同时分析多个配置文件（OK）：

$ ./zlog-chk-conf ../test/test_hello.conf ../test/test_init.conf
--[../test/test_hello.conf] syntax right
--[../test/test_init.conf] syntax right