zlog使用手册：从入门到精通的完整指南

一、zlog简介与核心优势

zlog是一款高性能、跨平台的C语言日志库，专为解决传统日志方案（如printf直接输出、简单文件写入）的性能瓶颈而生。其核心优势体现在三方面：

1. 高性能：通过内存缓冲、异步写入机制，将单条日志写入耗时从毫秒级降至微秒级。例如，在4核Linux服务器上，zlog可稳定处理每秒50万条日志，而传统方案仅能处理数千条。
2. 灵活配置：支持按日志级别（DEBUG/INFO/WARN/ERROR/FATAL）、模块名、线程ID等多维度分类，并可通过配置文件动态调整输出格式（如JSON、纯文本）和目标（文件、网络、控制台）。
3. 线程安全：内置锁机制，确保多线程环境下日志记录的原子性，避免日志内容交叉或丢失。

二、安装与基础配置

1. 安装步骤

• Linux/macOS：

  git clone https://github.com/HardySimpson/zlog.git
  cd zlog
  make && sudo make install

  安装后，头文件位于/usr/local/include/zlog.h，库文件位于/usr/local/lib/libzlog.so。
• Windows：通过vcpkg安装：

  vcpkg install zlog

2. 基础配置文件示例

配置文件（如zlog.conf）是zlog的核心，定义日志规则。以下是一个典型配置：

[formats]
simple = "%d.%s %V %M"
json = "{\"time\":\"%d.%s\",\"level\":\"%V\",\"module\":\"%M\",\"msg\":\"%@\"}"
[rules]
# 模块名为"server"的日志，INFO及以上级别输出到控制台
server.* > stdout; simple
# 所有模块的ERROR及以上级别输出到error.log
*.*.ERROR > error.log; json

• %d：时间戳（秒级）
• %s：时间戳（微秒级）
• %V：日志级别
• %M：模块名
• %@：日志消息

三、核心API使用指南

1. 初始化与销毁

#include "zlog.h"
int main() {
    // 初始化zlog，传入配置文件路径
    if (dzlog_init("zlog.conf") != 0) {
        fprintf(stderr, "zlog init failed\n");
        return -1;
    }
    // 程序退出前调用
    zlog_fini();
    return 0;
}

• 关键点：dzlog_init需在程序启动时优先调用，失败时需立即终止程序，避免日志记录异常。

2. 记录日志

// 定义模块名（通常为当前文件名）
#define MODULE "server"
void process_request() {
    dzlog_debug(MODULE, "Request received: %s", request_data);
    dzlog_info(MODULE, "Processing request...");
    if (error_occurred) {
        dzlog_error(MODULE, "Failed to process: %s", error_msg);
    }
}

• 级别选择：
  • DEBUG：开发调试信息
  • INFO：关键业务状态
  • ERROR：可恢复的异常
  • FATAL：不可恢复错误（需配合zlog_fini终止程序）

3. 动态调整日志级别

通过信号或API动态修改日志级别，无需重启程序：

// 将模块"server"的日志级别调整为WARN
zlog_level_t new_level = ZLOG_LEVEL_WARN;
zlog_set_level(MODULE, new_level);

四、高级功能与最佳实践

1. 异步日志写入

zlog默认采用同步写入，可能阻塞主线程。启用异步模式需在配置文件中添加：

[rules]
*.* > async_file; simple

并在初始化后调用：

zlog_thread_init(); // 启动异步线程

• 适用场景：高并发服务（如Web服务器、消息队列），可降低日志写入对主线程性能的影响。

2. 日志轮转与压缩

通过logrotate或zlog内置的轮转功能管理日志文件大小：

[rules]
*.* > rolling_file; simple
    max_size = 10485760  # 10MB
    backup_num = 5       # 保留5个历史文件

• 压缩：结合gzip对历史日志压缩，节省存储空间。

3. 多线程日志安全

zlog通过zlog_mutex_t保证线程安全，但需注意：

• 避免在日志消息中拼接字符串（如sprintf），推荐直接使用格式化参数：

  dzlog_info(MODULE, "User %s logged in", username); // 安全
  // 错误示例：char buf[100]; sprintf(buf, "..."); dzlog_info(...); // 非线程安全

4. 性能优化建议

• 批量记录：将多条低优先级日志合并为一条（如dzlog_debug批量调用）。
• 级别过滤：生产环境关闭DEBUG级别，减少I/O开销。
• 内存缓冲：增大内存缓冲区（通过zlog_set_buffer_size），减少磁盘写入次数。

五、常见问题与解决方案

1. 日志未输出

• 原因：配置文件路径错误、日志级别过滤、权限不足。
• 排查步骤：
  1. 检查dzlog_init返回值是否为0。
  2. 确认配置文件中规则的模块名与代码一致。
  3. 检查日志文件目录是否有写入权限。

2. 性能瓶颈

• 现象：高并发下日志写入延迟。
• 优化方案：
  1. 启用异步模式。
  2. 增大内存缓冲区（如从4KB调至64KB）。
  3. 减少单条日志长度（避免包含大段数据）。

3. 多线程日志交叉

• 现象：日志行中混入其他线程的内容。
• 解决：升级至zlog最新版本（已修复早期版本的锁竞争问题）。

六、总结与扩展资源

zlog通过高性能、灵活配置和线程安全设计，成为C语言日志的首选方案。建议开发者：

1. 从简单配置入手，逐步尝试异步、轮转等高级功能。
2. 结合strace或perf工具分析日志写入性能。
3. 参考官方文档（zlog GitHub）获取最新更新。

通过合理配置zlog，开发者可显著提升日志系统的可靠性与性能，为故障排查和业务分析提供有力支持。