1. 项目概述为什么C项目需要一个像spdlog这样的日志库如果你写过C尤其是写过稍微有点规模的C项目那你一定对日志记录这件事深有体会。最原始的做法是什么std::cout或者printf直接往控制台一打调试的时候确实方便但项目一上线或者需要长期运行问题就全来了日志和程序输出混在一起分不清想存到文件里还得自己写文件操作多线程环境下输出还会乱序、互相覆盖更别提想按日期、按级别分文件或者设置日志滚动比如单个文件超过10MB就自动新建一个这些稍微高级点的需求了。自己从头实现一套健壮、高效、功能齐全的日志系统其复杂度和工作量不亚于写一个小型框架。这就是spdlog出现的背景。它不是一个“可有可无”的库而是现代C项目中解决日志需求的“标准答案”之一。它是一个纯头文件的、速度极快的C日志库官方宣称“非常快”benchmark数据显示其性能远超许多同类库。对于开发者而言集成spdlog意味着你不再需要关心底层的线程安全、格式化和输出目标sink管理而是可以专注于使用一套简洁、直观的API来记录日志。无论是需要将日志输出到控制台、文件、系统日志syslog还是远程服务器spdlog都提供了开箱即用的支持。它的设计哲学是“只做一件事并做到极致”其接口设计深受Python的logging模块影响对于有相关经验的开发者来说非常容易上手。简单来说集成spdlog就是为了把你和你的团队从繁琐、易错的自研日志系统中解放出来用业界公认的最佳实践来管理你的程序运行时产生的所有“声音”。它能让你的调试过程更高效让线上问题的排查更清晰是提升C项目工程化水平和可维护性的一个关键步骤。2. 核心设计解析spdlog的架构与核心概念要用好spdlog不能只停留在调用几个函数的层面理解其核心设计思想至关重要。这能帮助你在遇到复杂需求时知道该如何组合和配置而不是去魔改代码。2.1 核心组件三层模型spdlog的架构可以清晰地分为三层Logger记录器、Sink输出槽和Formatter格式化器。这三者以松耦合的方式协同工作。Logger这是你直接打交道的对象。你通过调用spdlog::info(),logger-warn()这样的方法将日志消息提交给Logger。一个Logger可以关联多个Sink。Logger的主要职责是接收日志调用包含级别、时间、消息等。判断该条日志的级别是否达到Logger或全局设置的日志级别阈值例如如果设置级别为warn那么info级别的日志会被过滤掉。将符合条件的日志消息分发给所有关联的Sink。Sink这是实际决定日志去向的组件。每个Sink代表一个输出目标。spdlog内置了丰富的Sinkstdout_sink_mt/stderr_sink_mt 输出到标准输出/错误多线程安全版本。basic_file_sink_mt 输出到单个基本文件。rotating_file_sink_mt 循环文件Sink当文件大小达到指定值时会自动创建新文件并重命名旧文件如app.log-app.1.log。daily_file_sink_mt 每日文件Sink每天在指定时间如午夜创建新的日志文件。syslog_sink 输出到系统日志Unix/Linux 系统。dist_sink_mt 分布式Sink可以将日志同时分发给多个其他Sink。 你可以将一个Logger绑定到多个Sink上实现同时输出到控制台和文件甚至更多目标。Formatter 它附着在Sink上决定了日志消息最终呈现的文本格式。spdlog使用一个非常强大的格式化语法默认的格式类似于[2023-10-27 14:30:15.123] [info] [main] This is a log message.。你可以通过set_pattern方法完全自定义格式提取进程ID、线程ID、源代码文件名和行号等丰富的信息。这种分层设计的好处是灵活性极高。例如你可以创建一个Logger给它同时添加一个输出到控制台的Sink格式简单便于调试时观看和一个输出到文件的Sink格式详细包含线程ID和文件名用于事后分析而两者互不干扰。2.2 日志级别与性能考量spdlog定义了六个标准的日志级别从低到高依次为trace,debug,info,warn,error,critical。还有一个off级别用于关闭所有日志。性能关键点格式化开销。这是很多新手容易忽略的地方。看下面两行代码// 不推荐的写法 logger-debug(Received a message from {} with data: {}, client_id, some_complex_object); // 推荐的写法 SPDLOG_DEBUG(logger, “Received a message from {} with data: {}”, client_id, some_complex_object);看起来功能一样但在release模式下如果日志级别设置为info或更高第一行代码仍然会进行参数client_id和some_complex_object的求值以及字符串格式化的计算即使这条日志最终不会被输出这个计算开销在热点路径上可能是不可忽视的。而使用宏SPDLOG_DEBUG等在编译时如果预定义宏SPDLOG_ACTIVE_LEVEL高于当前日志调用级别这行代码会被编译器直接优化掉参数求值和格式化计算根本不会发生。因此在性能敏感的场景下务必使用宏SPDLOG_XXX来记录日志而不是直接调用logger-xxx()方法。注意spdlog的宏默认是开启的。你可以通过定义SPDLOG_NO_MACRO来禁用它但除非有特殊原因否则不建议这么做。3. 从零开始在项目中集成与配置spdlog理论说再多不如动手搭一个。我们以最常见的集成方式——通过包管理器如vcpkg或直接复制头文件——来演示。3.1 获取spdlog方法一使用vcpkg推荐便于依赖管理# 安装 spdlog vcpkg install spdlog然后在你的CMakeLists.txt中find_package(spdlog CONFIG REQUIRED) target_link_libraries(your_target PRIVATE spdlog::spdlog)这种方式会自动处理头文件路径和编译定义是最省心的。方法二单头文件模式最快捷spdlog提供了一个 amalgamated合并的单头文件版本。直接从其GitHub仓库的include目录下载spdlog.h和spdlog.cpp放入你的项目然后包含spdlog.h即可。这种方式适合小型或快速原型项目但缺少了按需编译的灵活性。方法三作为子模块Git Submodule如果你的项目使用Git可以将spdlog添加为子模块。git submodule add https://github.com/gabime/spdlog.git extern/spdlog然后在CMakeLists.txt中add_subdirectory(extern/spdlog) target_link_libraries(your_target PRIVATE spdlog::spdlog)这种方式能锁定特定版本适合对依赖版本有严格要求的项目。3.2 基础配置与第一个日志假设我们创建一个控制台程序需要同时将日志输出到控制台和一个按日期滚动的文件中。#include spdlog/spdlog.h #include spdlog/sinks/stdout_color_sinks.h #include spdlog/sinks/daily_file_sink.h #include memory int main() { try { // 1. 创建两个 sink auto console_sink std::make_sharedspdlog::sinks::stdout_color_sink_mt(); auto file_sink std::make_sharedspdlog::sinks::daily_file_sink_mt(logs/myapp.log, 23, 59); // 每天23:59创建新文件 // 2. 为不同的 sink 设置不同的格式 // 控制台格式彩色简洁带时间 console_sink-set_pattern([%Y-%m-%d %H:%M:%S.%e] [%^%l%$] %v); // 文件格式更详细包含线程ID和文件名需要启用SPDLOG_USE_STD_FORMAT或使用fmtlib file_sink-set_pattern([%Y-%m-%d %H:%M:%S.%e] [%l] [thread %t] [%s:%#] %v); // 3. 创建 logger 并添加 sinks std::vectorspdlog::sink_ptr sinks{console_sink, file_sink}; auto combined_logger std::make_sharedspdlog::logger(main_logger, sinks.begin(), sinks.end()); // 4. 设置全局日志级别和刷新级别 combined_logger-set_level(spdlog::level::debug); // 捕获 debug 及以上级别的日志 combined_logger-flush_on(spdlog::level::warn); // 当遇到 warn 及以上级别日志时立即刷新缓冲区到磁盘 // 5. 注册为全局默认 logger可选这样可以直接使用 spdlog::info() 等 spdlog::set_default_logger(combined_logger); spdlog::info(Spdlog initialized successfully!); // 6. 使用宏记录日志推荐有编译期优化 SPDLOG_DEBUG(This is a debug message, arg1{}, arg2{}, 42, test); SPDLOG_WARN(Something might be wrong here.); SPDLOG_ERROR(A serious error occurred: {}, File not found); // 也可以直接使用 logger 对象 combined_logger-info(Using logger object directly.); } catch (const spdlog::spdlog_ex ex) { // spdlog 初始化或写入可能抛出的异常 std::cerr Log initialization failed: ex.what() std::endl; return -1; } // 程序结束时所有 logger 会自动析构并 flush 剩余日志 spdlog::info(Application shutting down.); spdlog::shutdown(); // 显式关闭所有 logger确保所有日志被写出 return 0; }关键配置解析set_pattern 格式字符串中%Y等是时间占位符%l是级别%v是实际消息%t是线程ID%s和%#是源代码文件名和行号需要定义SPDLOG_USE_STD_FORMAT或使用fmt且日志调用需用宏。%^和%$在控制台sink中用于颜色范围。set_level 这是过滤器的核心。设置为debug意味着trace级别的日志不会被记录。通常开发环境设为debug生产环境设为info或warn。flush_on 这是一个重要的可靠性配置。日志通常先写入内存缓冲区然后批量写入磁盘文件sink或控制台以提高性能。flush_on指定在遇到哪个级别及以上的日志时立即强制刷新缓冲区。对于error和critical日志强烈建议立即刷新以防程序崩溃导致最后的错误信息丢失。3.3 高级配置异步日志与自定义格式化对于高性能服务器应用同步日志默认可能成为瓶颈因为每次写日志都会阻塞调用线程直到I/O完成。spdlog提供了强大的异步日志功能。#include spdlog/async.h #include spdlog/sinks/rotating_file_sink.h void setup_async_logging() { // 设置异步日志的全局线程池参数 // 队列大小为 8192 条日志使用1个后台线程 spdlog::init_thread_pool(8192, 1); // 创建一个异步的 rotating file sink auto async_sink std::make_sharedspdlog::sinks::rotating_file_sink_mt(logs/async_app.log, 1024 * 1024 * 10, 5); // 10MB一个文件保留5个 async_sink-set_pattern([%Y-%m-%d %H:%M:%S.%e] [%l] [%t] %v); // 使用线程池创建异步 logger auto async_logger std::make_sharedspdlog::async_logger(async_logger, async_sink, spdlog::thread_pool(), spdlog::async_overflow_policy::block); // 队列满时阻塞 async_logger-set_level(spdlog::level::info); spdlog::register_logger(async_logger); // 使用异步 logger SPDLOG_LOGGER_INFO(async_logger, This log is written asynchronously.); for(int i 0; i 10000; i) { // 这不会阻塞主线程日志被放入队列由后台线程处理 SPDLOG_LOGGER_DEBUG(async_logger, High-throughput logging message {}, i); } }异步策略选择async_overflow_policy有两种策略block阻塞和overrun_oldest丢弃最老的。在要求绝对不能丢失日志的场景如金融交易下应使用block但需注意队列满时可能引起的延迟。在日志量极大、可以容忍少量丢失的场景如 metrics 收集可使用overrun_oldest。自定义格式化除了使用格式字符串你还可以继承spdlog::custom_flag_formatter来创建完全自定义的格式字段。例如添加一个输出当前请求ID的字段。4. 实战技巧与避坑指南在实际项目中使用spdlog几年我积累了一些文档里不会明确写但能极大提升体验和稳定性的技巧。4.1 多线程环境下的Logger管理核心原则Logger对象本身是线程安全的但其创建和注册不是。不要在多个线程中同时创建同名的logger并调用spdlog::register_logger。正确的做法是在程序初始化阶段主线程或单线程环境下完成所有logger的创建和注册之后在各个线程中通过spdlog::get(“logger_name”)来获取并使用。// 初始化阶段 void init_logging_system() { auto logger spdlog::daily_file_sink_mt(“network”, “logs/network.log”, 0, 0); spdlog::register_logger(logger); } // 工作线程中 void worker_thread() { auto net_logger spdlog::get(“network”); // 安全获取 if(net_logger) { SPDLOG_LOGGER_INFO(net_logger, “Thread {} started”, std::this_thread::get_id()); } }注意spdlog::get可能返回nullptr如果logger不存在。在生产代码中务必检查返回值或者使用spdlog::get的另一个重载版本设置一个默认logger。4.2 性能调优与缓冲区设置文件Sink的缓冲区默认情况下文件sink有自己的缓冲区。你可以通过sink-set_buffer_size(size)来调整。更大的缓冲区能减少磁盘I/O次数提高吞吐量但在程序异常崩溃时缓冲区中未写入的数据会丢失。根据你对性能和可靠性的权衡来设置。异步日志的队列大小如前所述异步日志的队列大小 (init_thread_pool的第一个参数) 是关键。设置太小在高负载下容易阻塞或丢日志设置太大会消耗更多内存。一个经验值是预估你的应用峰值日志速率然后设置队列能容纳至少1-2秒的日志量。关闭不必要的特性如果你不需要源代码位置%s%#确保不要定义SPDLOG_USE_STD_FORMAT或类似宏也不要使用能捕获位置的宏如SPDLOG_LOGGER_INFO。这能减少编译后的代码大小和运行开销。4.3 日志文件管理与滚动策略rotating_file_sink和daily_file_sink是管理日志文件的利器但要注意文件名冲突rotating_file_sink在滚动时会将app.log重命名为app.1.log如果app.1.log已存在则会继续重命名之前的文件。确保你的最大文件数设置合理避免无限增长。时间点daily_file_sink的滚动发生在下一个日志写入时且时间大于或等于设定的滚动时间点。例如设置(23, 59)如果在23:58写了一条日志23:59没有日志那么直到第二天有日志写入时比如00:01才会创建新文件并重命名旧文件。这不是一个“定时任务”。日志清理spdlog不提供自动删除旧日志文件的功能。你需要借助外部工具如Linux的logrotate或自己在程序启动时编写简单的清理脚本根据文件修改时间删除过期的日志。4.4 异常处理与资源释放虽然spdlog在析构时会尝试刷新缓冲区但在某些极端情况如程序调用_exit或崩溃下日志仍可能丢失。对于关键的错误日志可以考虑使用flush()方法强制刷新。将关键的error/critical日志同时输出到一个更可靠的通道比如系统事件日志Windows Event Log或直接发送到监控系统。在捕获到未处理异常并即将退出前调用spdlog::shutdown()。另外确保在所有工作线程结束后再调用spdlog::shutdown()。如果后台异步日志线程还在工作而你提前销毁了sink依赖的资源比如文件句柄会导致未定义行为。5. 常见问题排查与解决方案实录即使按照指南操作在实际部署中还是会遇到一些“坑”。这里记录了几个最常见的问题及其解决方法。问题1日志没有输出到文件但控制台有输出。可能原因A目录权限不足。程序没有在指定路径创建文件或写入的权限。尤其是在Linux系统下尝试写入/var/log等系统目录时。解决检查目标目录是否存在以及进程用户是否有写权限。可以在代码中先尝试创建目录或输出到当前用户有权限的目录如./logs。可能原因B缓冲区未刷新。日志量较小还停留在内存缓冲区里程序就结束了。解决设置flush_on级别或在程序结束前显式调用logger-flush()/spdlog::shutdown()。可能原因CSink未被正确添加到Logger。在创建logger后又修改了sinks向量但logger持有的sink指针可能已经失效或未更新。解决确保在创建logger时一次性传递完整的sinks列表或者使用logger-sinks()返回的向量来修改需注意线程安全。问题2多线程日志输出顺序混乱非异步模式。现象不同线程的日志行在控制台或文件里交错在一起一句话被拆成了两半。原因虽然每个logger的log函数调用是线程安全的即不会崩溃但默认情况下stdout或文件的写入操作本身不是原子的。一条日志可能对应多次write系统调用线程A的第一次write和线程B的第一次write可能先于各自后续的write执行。解决这正是spdlog的价值所在spdlog的sink在其log方法内部进行了锁保护确保一条完整的日志消息的格式化到写入过程是原子的。如果你遇到了输出混乱请检查你是否在直接操作共享的std::cout或文件流而不是通过spdlog的接口。确保所有输出都通过spdlog完成。问题3异步日志模式下程序崩溃后最后几条日志丢失。原因异步日志将消息放入队列后函数就返回了。如果程序紧接着崩溃后台线程可能来不及处理队列中剩余的消息。解决对于非常重要的错误日志考虑使用同步logger或者调用async_logger-flush()。在捕获到导致崩溃的异常信号如SIGSEGV的处理函数中尽快调用spdlog::shutdown()。注意在信号处理函数中只能调用异步信号安全的函数而spdlog::shutdown可能不是。一个更安全的模式是设置一个全局标志在主程序循环中检查该标志并执行关闭。权衡接受极少量日志丢失的风险以换取更高的吞吐量。对于大多数应用丢失崩溃前瞬间的几条日志是可以接受的关键的错误信息应该在更早的时候记录下来。问题4日志格式中的“文件名和行号”不显示或显示为“?”。原因要记录文件名和行号需要满足两个条件使用能捕获这些信息的宏如SPDLOG_LOGGER_INFO(logger, …)或SPDLOG_INFO(…)。直接调用logger-info(…)无法捕获。在spdlog的编译配置中启用了相关支持。对于使用fmtlib的版本通常默认开启。对于使用std::format的版本C20需要定义SPDLOG_USE_STD_FORMAT并且你的编译器完全支持std::source_location。解决检查你的日志调用是否使用了正确的宏。查看spdlog的编译输出或文档确认SPDLOG_USE_STD_FORMAT或SPDLOG_FMT_EXTERNAL等宏的定义是否符合你的环境。最简单的验证方法是使用SPDLOG_LOGGER_INFO宏并确保格式字符串中包含%s和%#。问题5在动态链接库DLL/SO中使用spdlog时日志不见了。现象主程序和动态库都使用了spdlog但动态库中记录的日志没有出现在主程序设置的输出里。原因spdlog的默认logger注册表 (spdlog::details::registry::instance()) 在跨模块exe和dll边界时可能不是同一个实例这取决于编译选项如-fvisibility和运行时链接。动态库中spdlog::default_logger()获取的可能是一个不同于主程序的“副本”。解决最佳实践将日志logger对象通过指针或引用从主程序传递到动态库的初始化函数中动态库直接使用传入的logger而不是自己创建或获取全局默认logger。如果必须使用全局注册表确保主程序和动态库以相同的方式编译和链接spdlog例如都静态链接同一个spdlog库或者都动态链接同一个spdlog共享库。集成spdlog的过程本质上是在为你的C项目建立一套可靠的“黑匣子”系统。初期多花一点时间理解其架构和配置能避免后期无数次的调试和排查。记住好的日志不是事后才加的它应该与你的业务逻辑同步设计和实现。当你习惯了spdlog带来的清晰和便利后就很难再回到那个用cout和fstream手动拼凑日志的时代了。
C++项目日志系统实战：spdlog核心架构与高效配置指南
1. 项目概述为什么C项目需要一个像spdlog这样的日志库如果你写过C尤其是写过稍微有点规模的C项目那你一定对日志记录这件事深有体会。最原始的做法是什么std::cout或者printf直接往控制台一打调试的时候确实方便但项目一上线或者需要长期运行问题就全来了日志和程序输出混在一起分不清想存到文件里还得自己写文件操作多线程环境下输出还会乱序、互相覆盖更别提想按日期、按级别分文件或者设置日志滚动比如单个文件超过10MB就自动新建一个这些稍微高级点的需求了。自己从头实现一套健壮、高效、功能齐全的日志系统其复杂度和工作量不亚于写一个小型框架。这就是spdlog出现的背景。它不是一个“可有可无”的库而是现代C项目中解决日志需求的“标准答案”之一。它是一个纯头文件的、速度极快的C日志库官方宣称“非常快”benchmark数据显示其性能远超许多同类库。对于开发者而言集成spdlog意味着你不再需要关心底层的线程安全、格式化和输出目标sink管理而是可以专注于使用一套简洁、直观的API来记录日志。无论是需要将日志输出到控制台、文件、系统日志syslog还是远程服务器spdlog都提供了开箱即用的支持。它的设计哲学是“只做一件事并做到极致”其接口设计深受Python的logging模块影响对于有相关经验的开发者来说非常容易上手。简单来说集成spdlog就是为了把你和你的团队从繁琐、易错的自研日志系统中解放出来用业界公认的最佳实践来管理你的程序运行时产生的所有“声音”。它能让你的调试过程更高效让线上问题的排查更清晰是提升C项目工程化水平和可维护性的一个关键步骤。2. 核心设计解析spdlog的架构与核心概念要用好spdlog不能只停留在调用几个函数的层面理解其核心设计思想至关重要。这能帮助你在遇到复杂需求时知道该如何组合和配置而不是去魔改代码。2.1 核心组件三层模型spdlog的架构可以清晰地分为三层Logger记录器、Sink输出槽和Formatter格式化器。这三者以松耦合的方式协同工作。Logger这是你直接打交道的对象。你通过调用spdlog::info(),logger-warn()这样的方法将日志消息提交给Logger。一个Logger可以关联多个Sink。Logger的主要职责是接收日志调用包含级别、时间、消息等。判断该条日志的级别是否达到Logger或全局设置的日志级别阈值例如如果设置级别为warn那么info级别的日志会被过滤掉。将符合条件的日志消息分发给所有关联的Sink。Sink这是实际决定日志去向的组件。每个Sink代表一个输出目标。spdlog内置了丰富的Sinkstdout_sink_mt/stderr_sink_mt 输出到标准输出/错误多线程安全版本。basic_file_sink_mt 输出到单个基本文件。rotating_file_sink_mt 循环文件Sink当文件大小达到指定值时会自动创建新文件并重命名旧文件如app.log-app.1.log。daily_file_sink_mt 每日文件Sink每天在指定时间如午夜创建新的日志文件。syslog_sink 输出到系统日志Unix/Linux 系统。dist_sink_mt 分布式Sink可以将日志同时分发给多个其他Sink。 你可以将一个Logger绑定到多个Sink上实现同时输出到控制台和文件甚至更多目标。Formatter 它附着在Sink上决定了日志消息最终呈现的文本格式。spdlog使用一个非常强大的格式化语法默认的格式类似于[2023-10-27 14:30:15.123] [info] [main] This is a log message.。你可以通过set_pattern方法完全自定义格式提取进程ID、线程ID、源代码文件名和行号等丰富的信息。这种分层设计的好处是灵活性极高。例如你可以创建一个Logger给它同时添加一个输出到控制台的Sink格式简单便于调试时观看和一个输出到文件的Sink格式详细包含线程ID和文件名用于事后分析而两者互不干扰。2.2 日志级别与性能考量spdlog定义了六个标准的日志级别从低到高依次为trace,debug,info,warn,error,critical。还有一个off级别用于关闭所有日志。性能关键点格式化开销。这是很多新手容易忽略的地方。看下面两行代码// 不推荐的写法 logger-debug(Received a message from {} with data: {}, client_id, some_complex_object); // 推荐的写法 SPDLOG_DEBUG(logger, “Received a message from {} with data: {}”, client_id, some_complex_object);看起来功能一样但在release模式下如果日志级别设置为info或更高第一行代码仍然会进行参数client_id和some_complex_object的求值以及字符串格式化的计算即使这条日志最终不会被输出这个计算开销在热点路径上可能是不可忽视的。而使用宏SPDLOG_DEBUG等在编译时如果预定义宏SPDLOG_ACTIVE_LEVEL高于当前日志调用级别这行代码会被编译器直接优化掉参数求值和格式化计算根本不会发生。因此在性能敏感的场景下务必使用宏SPDLOG_XXX来记录日志而不是直接调用logger-xxx()方法。注意spdlog的宏默认是开启的。你可以通过定义SPDLOG_NO_MACRO来禁用它但除非有特殊原因否则不建议这么做。3. 从零开始在项目中集成与配置spdlog理论说再多不如动手搭一个。我们以最常见的集成方式——通过包管理器如vcpkg或直接复制头文件——来演示。3.1 获取spdlog方法一使用vcpkg推荐便于依赖管理# 安装 spdlog vcpkg install spdlog然后在你的CMakeLists.txt中find_package(spdlog CONFIG REQUIRED) target_link_libraries(your_target PRIVATE spdlog::spdlog)这种方式会自动处理头文件路径和编译定义是最省心的。方法二单头文件模式最快捷spdlog提供了一个 amalgamated合并的单头文件版本。直接从其GitHub仓库的include目录下载spdlog.h和spdlog.cpp放入你的项目然后包含spdlog.h即可。这种方式适合小型或快速原型项目但缺少了按需编译的灵活性。方法三作为子模块Git Submodule如果你的项目使用Git可以将spdlog添加为子模块。git submodule add https://github.com/gabime/spdlog.git extern/spdlog然后在CMakeLists.txt中add_subdirectory(extern/spdlog) target_link_libraries(your_target PRIVATE spdlog::spdlog)这种方式能锁定特定版本适合对依赖版本有严格要求的项目。3.2 基础配置与第一个日志假设我们创建一个控制台程序需要同时将日志输出到控制台和一个按日期滚动的文件中。#include spdlog/spdlog.h #include spdlog/sinks/stdout_color_sinks.h #include spdlog/sinks/daily_file_sink.h #include memory int main() { try { // 1. 创建两个 sink auto console_sink std::make_sharedspdlog::sinks::stdout_color_sink_mt(); auto file_sink std::make_sharedspdlog::sinks::daily_file_sink_mt(logs/myapp.log, 23, 59); // 每天23:59创建新文件 // 2. 为不同的 sink 设置不同的格式 // 控制台格式彩色简洁带时间 console_sink-set_pattern([%Y-%m-%d %H:%M:%S.%e] [%^%l%$] %v); // 文件格式更详细包含线程ID和文件名需要启用SPDLOG_USE_STD_FORMAT或使用fmtlib file_sink-set_pattern([%Y-%m-%d %H:%M:%S.%e] [%l] [thread %t] [%s:%#] %v); // 3. 创建 logger 并添加 sinks std::vectorspdlog::sink_ptr sinks{console_sink, file_sink}; auto combined_logger std::make_sharedspdlog::logger(main_logger, sinks.begin(), sinks.end()); // 4. 设置全局日志级别和刷新级别 combined_logger-set_level(spdlog::level::debug); // 捕获 debug 及以上级别的日志 combined_logger-flush_on(spdlog::level::warn); // 当遇到 warn 及以上级别日志时立即刷新缓冲区到磁盘 // 5. 注册为全局默认 logger可选这样可以直接使用 spdlog::info() 等 spdlog::set_default_logger(combined_logger); spdlog::info(Spdlog initialized successfully!); // 6. 使用宏记录日志推荐有编译期优化 SPDLOG_DEBUG(This is a debug message, arg1{}, arg2{}, 42, test); SPDLOG_WARN(Something might be wrong here.); SPDLOG_ERROR(A serious error occurred: {}, File not found); // 也可以直接使用 logger 对象 combined_logger-info(Using logger object directly.); } catch (const spdlog::spdlog_ex ex) { // spdlog 初始化或写入可能抛出的异常 std::cerr Log initialization failed: ex.what() std::endl; return -1; } // 程序结束时所有 logger 会自动析构并 flush 剩余日志 spdlog::info(Application shutting down.); spdlog::shutdown(); // 显式关闭所有 logger确保所有日志被写出 return 0; }关键配置解析set_pattern 格式字符串中%Y等是时间占位符%l是级别%v是实际消息%t是线程ID%s和%#是源代码文件名和行号需要定义SPDLOG_USE_STD_FORMAT或使用fmt且日志调用需用宏。%^和%$在控制台sink中用于颜色范围。set_level 这是过滤器的核心。设置为debug意味着trace级别的日志不会被记录。通常开发环境设为debug生产环境设为info或warn。flush_on 这是一个重要的可靠性配置。日志通常先写入内存缓冲区然后批量写入磁盘文件sink或控制台以提高性能。flush_on指定在遇到哪个级别及以上的日志时立即强制刷新缓冲区。对于error和critical日志强烈建议立即刷新以防程序崩溃导致最后的错误信息丢失。3.3 高级配置异步日志与自定义格式化对于高性能服务器应用同步日志默认可能成为瓶颈因为每次写日志都会阻塞调用线程直到I/O完成。spdlog提供了强大的异步日志功能。#include spdlog/async.h #include spdlog/sinks/rotating_file_sink.h void setup_async_logging() { // 设置异步日志的全局线程池参数 // 队列大小为 8192 条日志使用1个后台线程 spdlog::init_thread_pool(8192, 1); // 创建一个异步的 rotating file sink auto async_sink std::make_sharedspdlog::sinks::rotating_file_sink_mt(logs/async_app.log, 1024 * 1024 * 10, 5); // 10MB一个文件保留5个 async_sink-set_pattern([%Y-%m-%d %H:%M:%S.%e] [%l] [%t] %v); // 使用线程池创建异步 logger auto async_logger std::make_sharedspdlog::async_logger(async_logger, async_sink, spdlog::thread_pool(), spdlog::async_overflow_policy::block); // 队列满时阻塞 async_logger-set_level(spdlog::level::info); spdlog::register_logger(async_logger); // 使用异步 logger SPDLOG_LOGGER_INFO(async_logger, This log is written asynchronously.); for(int i 0; i 10000; i) { // 这不会阻塞主线程日志被放入队列由后台线程处理 SPDLOG_LOGGER_DEBUG(async_logger, High-throughput logging message {}, i); } }异步策略选择async_overflow_policy有两种策略block阻塞和overrun_oldest丢弃最老的。在要求绝对不能丢失日志的场景如金融交易下应使用block但需注意队列满时可能引起的延迟。在日志量极大、可以容忍少量丢失的场景如 metrics 收集可使用overrun_oldest。自定义格式化除了使用格式字符串你还可以继承spdlog::custom_flag_formatter来创建完全自定义的格式字段。例如添加一个输出当前请求ID的字段。4. 实战技巧与避坑指南在实际项目中使用spdlog几年我积累了一些文档里不会明确写但能极大提升体验和稳定性的技巧。4.1 多线程环境下的Logger管理核心原则Logger对象本身是线程安全的但其创建和注册不是。不要在多个线程中同时创建同名的logger并调用spdlog::register_logger。正确的做法是在程序初始化阶段主线程或单线程环境下完成所有logger的创建和注册之后在各个线程中通过spdlog::get(“logger_name”)来获取并使用。// 初始化阶段 void init_logging_system() { auto logger spdlog::daily_file_sink_mt(“network”, “logs/network.log”, 0, 0); spdlog::register_logger(logger); } // 工作线程中 void worker_thread() { auto net_logger spdlog::get(“network”); // 安全获取 if(net_logger) { SPDLOG_LOGGER_INFO(net_logger, “Thread {} started”, std::this_thread::get_id()); } }注意spdlog::get可能返回nullptr如果logger不存在。在生产代码中务必检查返回值或者使用spdlog::get的另一个重载版本设置一个默认logger。4.2 性能调优与缓冲区设置文件Sink的缓冲区默认情况下文件sink有自己的缓冲区。你可以通过sink-set_buffer_size(size)来调整。更大的缓冲区能减少磁盘I/O次数提高吞吐量但在程序异常崩溃时缓冲区中未写入的数据会丢失。根据你对性能和可靠性的权衡来设置。异步日志的队列大小如前所述异步日志的队列大小 (init_thread_pool的第一个参数) 是关键。设置太小在高负载下容易阻塞或丢日志设置太大会消耗更多内存。一个经验值是预估你的应用峰值日志速率然后设置队列能容纳至少1-2秒的日志量。关闭不必要的特性如果你不需要源代码位置%s%#确保不要定义SPDLOG_USE_STD_FORMAT或类似宏也不要使用能捕获位置的宏如SPDLOG_LOGGER_INFO。这能减少编译后的代码大小和运行开销。4.3 日志文件管理与滚动策略rotating_file_sink和daily_file_sink是管理日志文件的利器但要注意文件名冲突rotating_file_sink在滚动时会将app.log重命名为app.1.log如果app.1.log已存在则会继续重命名之前的文件。确保你的最大文件数设置合理避免无限增长。时间点daily_file_sink的滚动发生在下一个日志写入时且时间大于或等于设定的滚动时间点。例如设置(23, 59)如果在23:58写了一条日志23:59没有日志那么直到第二天有日志写入时比如00:01才会创建新文件并重命名旧文件。这不是一个“定时任务”。日志清理spdlog不提供自动删除旧日志文件的功能。你需要借助外部工具如Linux的logrotate或自己在程序启动时编写简单的清理脚本根据文件修改时间删除过期的日志。4.4 异常处理与资源释放虽然spdlog在析构时会尝试刷新缓冲区但在某些极端情况如程序调用_exit或崩溃下日志仍可能丢失。对于关键的错误日志可以考虑使用flush()方法强制刷新。将关键的error/critical日志同时输出到一个更可靠的通道比如系统事件日志Windows Event Log或直接发送到监控系统。在捕获到未处理异常并即将退出前调用spdlog::shutdown()。另外确保在所有工作线程结束后再调用spdlog::shutdown()。如果后台异步日志线程还在工作而你提前销毁了sink依赖的资源比如文件句柄会导致未定义行为。5. 常见问题排查与解决方案实录即使按照指南操作在实际部署中还是会遇到一些“坑”。这里记录了几个最常见的问题及其解决方法。问题1日志没有输出到文件但控制台有输出。可能原因A目录权限不足。程序没有在指定路径创建文件或写入的权限。尤其是在Linux系统下尝试写入/var/log等系统目录时。解决检查目标目录是否存在以及进程用户是否有写权限。可以在代码中先尝试创建目录或输出到当前用户有权限的目录如./logs。可能原因B缓冲区未刷新。日志量较小还停留在内存缓冲区里程序就结束了。解决设置flush_on级别或在程序结束前显式调用logger-flush()/spdlog::shutdown()。可能原因CSink未被正确添加到Logger。在创建logger后又修改了sinks向量但logger持有的sink指针可能已经失效或未更新。解决确保在创建logger时一次性传递完整的sinks列表或者使用logger-sinks()返回的向量来修改需注意线程安全。问题2多线程日志输出顺序混乱非异步模式。现象不同线程的日志行在控制台或文件里交错在一起一句话被拆成了两半。原因虽然每个logger的log函数调用是线程安全的即不会崩溃但默认情况下stdout或文件的写入操作本身不是原子的。一条日志可能对应多次write系统调用线程A的第一次write和线程B的第一次write可能先于各自后续的write执行。解决这正是spdlog的价值所在spdlog的sink在其log方法内部进行了锁保护确保一条完整的日志消息的格式化到写入过程是原子的。如果你遇到了输出混乱请检查你是否在直接操作共享的std::cout或文件流而不是通过spdlog的接口。确保所有输出都通过spdlog完成。问题3异步日志模式下程序崩溃后最后几条日志丢失。原因异步日志将消息放入队列后函数就返回了。如果程序紧接着崩溃后台线程可能来不及处理队列中剩余的消息。解决对于非常重要的错误日志考虑使用同步logger或者调用async_logger-flush()。在捕获到导致崩溃的异常信号如SIGSEGV的处理函数中尽快调用spdlog::shutdown()。注意在信号处理函数中只能调用异步信号安全的函数而spdlog::shutdown可能不是。一个更安全的模式是设置一个全局标志在主程序循环中检查该标志并执行关闭。权衡接受极少量日志丢失的风险以换取更高的吞吐量。对于大多数应用丢失崩溃前瞬间的几条日志是可以接受的关键的错误信息应该在更早的时候记录下来。问题4日志格式中的“文件名和行号”不显示或显示为“?”。原因要记录文件名和行号需要满足两个条件使用能捕获这些信息的宏如SPDLOG_LOGGER_INFO(logger, …)或SPDLOG_INFO(…)。直接调用logger-info(…)无法捕获。在spdlog的编译配置中启用了相关支持。对于使用fmtlib的版本通常默认开启。对于使用std::format的版本C20需要定义SPDLOG_USE_STD_FORMAT并且你的编译器完全支持std::source_location。解决检查你的日志调用是否使用了正确的宏。查看spdlog的编译输出或文档确认SPDLOG_USE_STD_FORMAT或SPDLOG_FMT_EXTERNAL等宏的定义是否符合你的环境。最简单的验证方法是使用SPDLOG_LOGGER_INFO宏并确保格式字符串中包含%s和%#。问题5在动态链接库DLL/SO中使用spdlog时日志不见了。现象主程序和动态库都使用了spdlog但动态库中记录的日志没有出现在主程序设置的输出里。原因spdlog的默认logger注册表 (spdlog::details::registry::instance()) 在跨模块exe和dll边界时可能不是同一个实例这取决于编译选项如-fvisibility和运行时链接。动态库中spdlog::default_logger()获取的可能是一个不同于主程序的“副本”。解决最佳实践将日志logger对象通过指针或引用从主程序传递到动态库的初始化函数中动态库直接使用传入的logger而不是自己创建或获取全局默认logger。如果必须使用全局注册表确保主程序和动态库以相同的方式编译和链接spdlog例如都静态链接同一个spdlog库或者都动态链接同一个spdlog共享库。集成spdlog的过程本质上是在为你的C项目建立一套可靠的“黑匣子”系统。初期多花一点时间理解其架构和配置能避免后期无数次的调试和排查。记住好的日志不是事后才加的它应该与你的业务逻辑同步设计和实现。当你习惯了spdlog带来的清晰和便利后就很难再回到那个用cout和fstream手动拼凑日志的时代了。
