C++高性能日志库spdlog使用指南

1. spdlog简介与核心优势

spdlog是一个专为C++设计的高性能日志库，在现代C++项目中广受欢迎。作为一名长期使用spdlog的开发者，我认为它的核心价值在于将简洁的API与卓越的性能完美结合。相比传统的log4cxx等方案，spdlog完全采用头文件方式实现，集成成本极低，同时通过精心的架构设计，在单线程模式下可达每秒数百万条日志记录的性能。

在实际项目中最让我欣赏的是它对fmt库的深度集成。这种设计使得日志输出既保持了类型安全，又能像printf一样灵活。例如当我们需要记录一个HTTP请求时：

cpp复制int status_code = 200;
std::string path = "/api/v1/user";
spdlog::info("Request completed: status={}, path={}", status_code, path);

这种格式化方式不仅比传统的流式输出更直观，而且在编译时就会进行类型检查，完全避免了格式字符串与参数类型不匹配导致的运行时错误。

2. 环境配置与基础使用

2.1 安装与集成

spdlog的安装异常简单，这也是它的一大优势。对于使用CMake的项目，只需在CMakeLists.txt中添加：

cmake复制find_package(spdlog REQUIRED)
target_link_libraries(your_target PRIVATE spdlog::spdlog)

如果使用vcpkg包管理器：

bash复制vcpkg install spdlog

对于需要快速测试的场景，甚至可以直接包含头文件：

cpp复制#include <spdlog/spdlog.h>

注意：虽然spdlog是header-only的，但为了获得最佳性能，建议通过包管理器安装并链接标准库版本。

2.2 基础日志输出

spdlog提供了6个标准日志级别，从低到高依次为：

• trace
• debug
• info
• warn
• error
• critical

基础使用示例：

cpp复制spdlog::info("Application started");  // 默认级别为info
spdlog::debug("Debug message");       // 默认不会显示
spdlog::warn("Low disk space: {}GB", 2.5);
spdlog::error("Failed to connect to database");

在实际项目中，我通常会先在main函数开头设置全局日志级别：

cpp复制spdlog::set_level(spdlog::level::debug);  // 显示debug及以上级别的日志

3. 日志器创建与管理

3.1 控制台日志器

控制台日志器是最常用的类型，spdlog提供了带颜色输出的版本：

cpp复制auto console = spdlog::stdout_color_mt("console");  // 多线程安全版本
console->info("Welcome to spdlog!");
console->error("Something went wrong!");

颜色标记说明：

• %^：开始颜色范围
• %$：结束颜色范围
• 在set_pattern中使用，例如：

cpp复制console->set_pattern("[%H:%M:%S] [%^%l%$] %v");

3.2 文件日志器

基础文件日志器：

cpp复制auto file_logger = spdlog::basic_logger_mt("file_logger", "logs/basic.log");
file_logger->info("This will be written to file");

轮转文件日志器是我在生产环境的首选，它可以防止单个日志文件过大：

cpp复制auto rotating_logger = spdlog::rotating_logger_mt(
    "rotating_logger",
    "logs/rotating.log",
    1024 * 1024 * 5,  // 5MB
    3                 // 保留3个备份
);

3.3 异步日志器

对于高性能场景，异步日志器是必选方案。它通过后台线程处理日志写入，避免阻塞主线程：

cpp复制spdlog::init_thread_pool(8192, 1);  // 队列大小8192，1个工作线程

auto async_logger = spdlog::basic_logger_mt<spdlog::async_factory>(
    "async_logger",
    "logs/async.log"
);

重要经验：异步日志器的队列大小需要根据实际负载调整。在高并发场景下，我通常设置为32768（32KB）以上。

4. 高级配置技巧

4.1 多目标输出

一个实用的技巧是将日志同时输出到控制台和文件：

cpp复制std::vector<spdlog::sink_ptr> sinks;
sinks.push_back(std::make_shared<spdlog::sinks::stdout_color_sink_mt>());
sinks.push_back(std::make_shared<spdlog::sinks::basic_file_sink_mt>("logs/multi.log"));

auto combined_logger = std::make_shared<spdlog::logger>("combined", begin(sinks), end(sinks));
combined_logger->set_level(spdlog::level::debug);

4.2 自定义格式

spdlog的格式字符串非常灵活，常用的占位符包括：

我的常用格式：

cpp复制logger->set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%^%8l%$] [%t] %v");

4.3 日志级别动态调整

在生产环境中，动态调整日志级别非常有用：

cpp复制// 通过环境变量控制日志级别
if (const char* env_level = std::getenv("LOG_LEVEL")) {
    logger->set_level(spdlog::level::from_str(env_level));
}

5. 性能优化实践

5.1 编译时优化

启用以下编译选项可以显著提升性能：

cmake复制target_compile_definitions(your_target PRIVATE SPDLOG_COMPILED_LIB)
target_compile_definitions(your_target PRIVATE SPDLOG_NO_EXCEPTIONS)

5.2 异步日志配置

合理的异步配置对性能影响巨大：

cpp复制// 高性能配置示例
spdlog::init_thread_pool(32768, 2);  // 大队列+多线程
auto async_logger = spdlog::basic_logger_mt<spdlog::async_factory>(
    "perf_logger",
    "logs/perf.log"
);
async_logger->set_level(spdlog::level::info);

5.3 避免常见性能陷阱

1. 避免频繁创建/销毁logger：logger创建成本较高，应该作为长期对象使用
2. 慎用flush()：除非必要，否则不要手动调用flush
3. 合理设置队列大小：异步日志器的队列太小会导致日志丢失

6. 生产环境最佳实践

6.1 日志文件管理

我推荐以下目录结构：

code复制logs/
├── app.log       # 当前日志
├── app.1.log     # 第一次轮转
├── app.2.log     # 第二次轮转
└── archive/      # 历史归档
    ├── app-2023-07-01.log
    └── app-2023-07-02.log

6.2 异常处理

良好的异常处理可以防止日志系统崩溃：

cpp复制try {
    spdlog::init_thread_pool(8192, 1);
    auto logger = spdlog::basic_logger_mt("main", "logs/main.log");
} catch (const spdlog::spdlog_ex& ex) {
    std::cerr << "Log init failed: " << ex.what() << std::endl;
}

6.3 多模块日志

对于大型项目，建议为每个模块创建独立的logger：

cpp复制auto network_logger = spdlog::basic_logger_mt("network", "logs/network.log");
auto db_logger = spdlog::basic_logger_mt("database", "logs/db.log");

7. 常见问题排查

7.1 日志不显示

可能原因：

1. 日志级别设置过高
2. 没有正确初始化logger
3. 异步日志器队列已满

7.2 性能问题

优化建议：

1. 检查是否使用了异步模式
2. 减少不必要的日志调用
3. 使用编译时优化

7.3 文件写入失败

常见解决方案：

1. 检查目录权限
2. 确保文件没有被其他进程锁定
3. 使用try-catch捕获异常

在实际项目中，我发现90%的日志问题都可以通过以下三步解决：

1. 检查日志级别
2. 确认logger是否成功创建
3. 查看是否有异常抛出

8. 扩展与高级特性

8.1 自定义sink

spdlog允许创建自定义输出目标。例如实现一个网络sink：

cpp复制class network_sink : public spdlog::sinks::base_sink<std::mutex> {
protected:
    void sink_it_(const spdlog::details::log_msg& msg) override {
        // 实现网络发送逻辑
    }
    
    void flush_() override {
        // 实现刷新逻辑
    }
};

8.2 日志过滤

可以实现自定义过滤逻辑：

cpp复制logger->set_filter([](const spdlog::details::log_msg& msg) {
    return msg.level >= spdlog::level::warn;  // 只记录warn及以上
});

8.3 性能统计

spdlog提供了性能统计接口：

cpp复制auto stats = spdlog::get_logger("perf")->stats();
std::cout << "Dropped messages: " << stats.dropped_messages << std::endl;

经过多年实践，我认为spdlog最强大的地方在于它的可扩展性。无论是添加新的输出目标，还是实现复杂的过滤逻辑，都能通过简洁的接口完成。对于大多数C++项目来说，spdlog提供了从简单到复杂的所有日志需求解决方案。