前一阵处理一个用 C 写的 Windows 服务故障现场日志文件已经涨到几个 GB编辑器打开直接卡死里面堆满了没有时间戳、没有级别、没有线程信息的 printf 输出。定位问题只能靠“大概什么时候崩的”和日志文件大小来猜。那次之后我把项目里的日志全部切到了 spdlog顺手帮团队把日志规范、轮转策略和异步刷盘一起定了下来。很多 C 开发者第一次认识 spdlog是因为它的宣传语header-only、极快、支持异步。但真正用下来你会发现spdlog 解决的不是“能打日志”这件事而是把 C 里原本很随意的日志输出改造为了一套可配置、可组合、可管理、能真正支撑线上排查的工程化基础设施。这篇文章不打算写成 API 手册而是从“为什么值得用”和“怎么用才不出问题”两个角度把它的核心抽象、落地流程、常见坑点和工程化建议一次讲透。1. 先搞清楚 spdlog 解决的是哪一类问题1.1 C 日志的常见混乱状态C 项目里最常见的日志做法是什么要么是 printf 加文件重定向要么是自己封装一个全局函数往里传字符串内部用 std::ofstream 追加写一行。小项目这样写没问题项目一旦大起来问题会集中爆发日志没有分级debug 信息和线上错误混在一起刷屏严重。没有统一格式时间戳、线程号、文件行号全靠手工拼不同模块风格还不一样。文件越写越大没有人管切割出了问题想下载日志文件都难。多线程下直接写文件互相穿插日志内容错乱。服务崩溃时最后几行日志往往还在缓冲区里没落盘线索直接丢失。这些问题不是“多写几行代码”能解决的。它本质上是一个工程问题日志系统需要在性能、可靠性、可读性和可维护性之间做平衡。而 spdlog 的价值就是把这套平衡方案做成了现成的、成熟的、可以快速集成的库。1.2 spdlog 的三个核心抽象想用好 spdlog先理解它的三个核心抽象就够了logger、sink、formatter。logger 是开发者直接使用的对象它负责接收日志消息、判断级别、调用格式化逻辑、把最终文本交给配置好的 sink。一个项目里可以创建多个 logger比如按模块拆分网络模块、业务模块、存储模块各一个。sink 是输出目标。它决定日志最终写到哪以及怎么写。常见的内置 sink 包括basic_file_sink单文件输出。rotating_file_sink按文件大小轮转。daily_file_sink按时间轮转。stdout_sink / stderr_sink控制台输出。msvc_sink输出到 Visual Studio 调试输出窗口。syslog_sink输出到系统 syslog。null_sink丢弃日志常用于性能测试或静默模式。一个 logger 可以绑定多个 sink。比如生产环境同时输出到文件和控制台或者同时输出到文件和一个监控接口。这就是后续多路日志的基础。formatter 决定日志文本的格式。spdlog 使用 pattern 字符串来定义格式例如[%Y-%m-%d %H:%M:%S.%e] [%l] [%t] %v分别代表时间、级别、线程号和消息内容。这个能力看起来简单但实际工程价值非常高因为它把“格式”和“内容”解耦了。调试时想看线程号加一个%t就行不需要改代码。这三个抽象一旦理解后面看 spdlog 的所有用法都会变得很顺logger 是入口sink 是外部世界的接口formatter 是中间的表达层。1.3 它不只是一个“攒日志的库”如果只是“写文件 轮转”很多库都能做到。spdlog 真正拉开差异的地方在于几件事性能优化到极致。通过编译期格式化、批量写入、可选异步模式让日志在低延迟要求下也几乎不阻塞业务逻辑。线程安全。内置的_mtmulti-thread版本 logger 和 sink 自带锁多线程环境直接使用也不会互相穿插。丰富的模板格式化。基于 fmt 库可以像 Python 一样写logger-info(value {}, val)不用手动拼接字符串。异常处理可配置。默认日志抛异常也可以关闭避免日志系统自身拖垮业务。这套设计让 spdlog 不只是“写日志”而是把日志从被动记录工具升级成了主动的可观测性基础设施。理解这一点再看后面的实践才会明白每一步设计都是有理由的。2. 上手路径从最小可用到多 sink 组合2.1 引入方式与环境准备spdlog 的使用很简单推荐先看官方仓库当前的 README再决定用哪种方式引入。常见引入方式有四种直接把 include 目录加进工程使用 header-only 模式这是最快的接入方式。使用 CMake FetchContent 拉取源码并构建成库适合团队统一管理依赖。使用 vcpkg 或 Conan 安装适合已经用包管理的项目。把源码完整拷贝进项目作为第三方模块编译。如果项目对构建速度敏感建议编译成静态库而不是使用 header-only。虽然 spdlog 宣传支持 header-only但对大型项目来说每个编译单元都编译一遍模板代码会明显拖慢构建。这是个很容易踩的细节先用 header-only 做验证没问题正式纳入项目时改成预编译库形式更稳妥。注意不同版本的 spdlog 在 API 细节上会有差异比如默认使用 fmt 库还是标准库 format接口参数也可能调整。落地前先查看当前版本的头文件与示例代码不要照抄旧博客上的写法。2.2 最小可运行示例先跑通一个最简单的例子#include spdlog/spdlog.h int main() { spdlog::info(Hello, {}!, spdlog); spdlog::warn(This is a warning, value: {}, 42); spdlog::error(Error code: {}, -1); return 0; }这段代码什么都不用配置默认输出到控制台格式已经自动带上了时间戳和颜色。对刚接触 spdlog 的人来说这个“零配置”体验很重要你不需要理解 logger、sink、formatter 这些概念就能先看到结果。然后进阶一步输出到文件#include spdlog/spdlog.h #include spdlog/sinks/basic_file_sink.h int main() { auto logger spdlog::basic_logger_mt(file_logger, logs/app.log); logger-set_level(spdlog::level::debug); logger-info(File logger is ready); logger-flush(); return 0; }这里的_mt后缀代表 multi-thread内部线程安全。对应地还有_st单线程版本性能更高但不允许跨线程使用。默认情况下建议都用_mt除非你非常确定某个 logger 只在单线程里访问。flush()是重点操作。它把缓冲区里的日志真正写进磁盘。如果不调用程序正常退出时会自动刷新但崩溃时缓冲区里的内容可能丢失。后面会专门展开 flush 策略。2.3 常用配置组合跑通文件输出后可以配置 pattern 和级别#include spdlog/spdlog.h #include spdlog/sinks/basic_file_sink.h int main() { auto logger spdlog::basic_logger_mt(app, logs/app.log); spdlog::set_pattern([%Y-%m-%d %H:%M:%S.%e] [%^%l%$] [thread %t] %s:%# %! : %v); logger-set_level(spdlog::level::debug); logger-debug(A debug message, number: {}, 123); logger-info(An info message); logger-warn(A warning message); logger-error(An error message); return 0; }pattern 里的几个关键占位符建议记住%Y-%m-%d %H:%M:%S.%e日期、时间、毫秒。%l日志级别如 debug、info、warn、error。%t线程 ID。%s、%#、%!文件名、行号、函数名。%v消息本体。%^与%$级别上色标记。默认文件日志是纯文本不加颜色。控制台日志可以带上颜色方便开发时直观分辨级别。2.4 MFC 场景怎么接入搜索热词里出现“mfc 使用 spdlog 例子代码”说明这是个高频需求。MFC 程序调试时开发者习惯在 Visual Studio 的“输出”窗口看调试信息传统做法是 OutputDebugString 或 TRACE 宏。如果想把 spdlog 的日志同时输出到 VS 输出窗口和文件可以用 multi-sink 组合。一个典型做法是创建一个 vector 装 sink然后构造 logger#include spdlog/spdlog.h #include spdlog/sinks/msvc_sink.h #include spdlog/sinks/rotating_file_sink.h void InitMfcLogger() { std::vectorspdlog::sink_ptr sinks; sinks.push_back(std::make_sharedspdlog::sinks::msvc_sink_mt()); sinks.push_back(std::make_sharedspdlog::sinks::rotating_file_sink_mt( logs/mfc_app.log, 1024 * 1024 * 5, 3, true)); auto logger std::make_sharedspdlog::logger(mfc_logger, sinks.begin(), sinks.end()); logger-set_level(spdlog::level::debug); logger-flush_on(spdlog::level::warn); spdlog::set_default_logger(logger); } void OnAppExit() { spdlog::shutdown(); }这样在开发时VS 调试窗口里能实时看到日志同时文件里也在持续记录正式日志。上线后可以去掉 msvc_sink只保留文件或多路输出。这个例子很典型地体现了 spdlog 的“组合”优势不需要为不同场景写不同的日志实现只需要调换或增删 sink。3. 性能、异步与线程安全它不是魔法但很有章法3.1 为什么 spdlog 快spdlog 宣传自己性能极高很多测试里都能到每秒百万条级别。这个快不是靠玄学主要有几个贡献因素编译期格式化。使用 fmt 库在编译期解析格式字符串运行时不需要反复解析%d %s这类占位符。最小化锁粒度。多线程版本里使用细粒度锁降低了线程竞争。批量写入和异步队列。异步模式下业务线程只负责把日志消息放进队列写盘工作交给后台线程。避免不必要的内存分配。通过复用缓冲区减少了每次日志都 new 内存的开销。但性能数字总是有条件的。网上看到的测速结果通常是不开文件、不做轮转、使用 null sink 或者内存缓冲区时的“极限成绩”。真实工程里落到文件上的速度会被磁盘 I/O 明显拖慢尤其日志量大时。所以看待 spdlog 的性能要分两层格式化快不快是一回事落盘快不快是另一回事。3.2 异步模式的价值与代价异步日志的核心思路是业务线程把日志消息 push 到内存队列里立刻返回后台线程从队列取出消息执行格式化、写文件。这样业务逻辑几乎不被日志拖住。开启异步的基本写法#include spdlog/spdlog.h #include spdlog/async.h #include spdlog/sinks/rotating_file_sink.h void InitAsyncLogger() { spdlog::init_thread_pool(8192, 1); auto file_sink std::make_sharedspdlog::sinks::rotating_file_sink_mt( logs/async.log, 1024 * 1024 * 5, 3); std::vectorspdlog::sink_ptr sinks { file_sink }; auto logger std::make_sharedspdlog::async_logger( async_logger, sinks.begin(), sinks.end(), spdlog::thread_pool(), spdlog::async_overflow_policy::block); spdlog::set_default_logger(logger); }这里有两个关键参数要理解队列大小。上面写的 8192 表示队列最多装 8192 条日志。溢出策略。block表示队列满了就阻塞业务线程等待队列腾出空间overrun_oldest表示丢弃最旧的日志保证新日志总能进入。在设计评估时要注意异步不是免费午餐。如果日志量特别大队列会被写满。选block会反过来阻塞业务选overrun_oldest会丢日志。对需要可靠审计的场景丢日志不可接受这时要么同步写要么提高队列并配合合理的日志量控制对性能优先的场景丢一点 debug 日志可接受用overrun_oldest更合理。另一个代价是崩溃时丢失最后一段日志。异步模式下数据先在队列里后台线程还没写完。如果进程直接崩掉或者 kill -9这部分日志确实会丢。解决思路包括设置 flush 策略、定期 flush、应用层补 watchdog或者接受“审计不追求最后一刻”的取舍。3.3 线程安全怎么看待spdlog 的_mt系列自带线程安全的锁多个线程对同一个 logger 调用 info、error 不会互相穿插。但这不等于你的日志内容一定是“有意义的整体”。如果业务逻辑分多行日志描述一件事多线程并发下A 线程的第一行后面可能插入 B 线程的日志。为了避免这种情况可以把一个场景的日志拼成一条消息输出保持日志的原子性。单线程版本_st性能更高但没有线程安全保障。如果某个 logger 只在固定线程里使用可以选用_st否则不要冒险。我见过有人为了性能把所有 logger 都改成_st结果偶发崩溃排查了半天最后发现是日志对象跨线程访问的问题完全没必要。经验先默认_mt用性能分析证明日志确实是瓶颈再优化。多数项目的瓶颈在数据库、网络或业务算法不在日志。4. 轮转策略与文件管理4.1 rotating_file_sink按大小切割日志文件不能无限增长。轮转rotation就是限制单个文件大小达到阈值时自动切换到新文件。auto logger spdlog::rotating_logger_mt(rotate_logger, logs/app.log, 1024 * 1024 * 10, 5);参数含义第三个参数是单文件最大字节数上面是 10MB。第四个参数是保留的文件数量。假设保留 5 个文件实际文件会是app.log、app.1.log、app.2.log…app.4.log。app.log永远是当前正在写的文件。达到 10MB 时它会变成app.1.log旧文件依次顺延最旧的那个被删除。这个策略适合日志量比较稳定的服务搭配定期归档落冷存储。如果日志量波动很大比如某天线上异常导致爆量单文件切得飞快历史文件很快被冲掉这时需要更慎重的保留策略。4.2 daily_file_sink按时间切割按大小切适合控制单个文件大小按时间切更适合按天归档的习惯auto logger spdlog::daily_logger_mt(daily_logger, logs/daily.log, 0, 0);第三个参数是小时第四个是分钟。0, 0表示每天凌晨 0 点切换。每天生成一个新文件文件命名会自动带上日期。时间轮转的优点是查询日志时“按天找”很方便缺点是一个文件可能很大如果某天日志特别多文件会非常臃肿。实践中常把两者结合daily 负责自然日归档rotating 负责限制单文件大小。如果只用 daily最好额外加一个定期清理脚本避免磁盘被历史文件占满。4.3 日志文件的打开模式与多进程问题spdlog 写文件时默认策略需要考虑。如果程序重启是把日志追加到旧文件里还是直接覆盖这个行为取决于打开模式。默认通常是 append。如果需要覆盖写要在 sink 构造时传参数auto logger spdlog::rotating_logger_mt(rotate_logger, logs/app.log, 1024 * 1024 * 10, 5, true);最后一个参数是truncate。传true会截断已存在的文件。这个选项要谨慎生产环境一般不要截断否则会丢失历史日志。多进程写同一个日志文件是另一个坑。spdlog 的_mt只能保证一个进程内的多线程安全不保证多进程写同一个文件的安全。两个进程同时以追加模式写同一个文件日志可能交错。规范做法是每个进程使用独立文件名或者日志服务单独承担汇总职责。5. 常见坑点与排查链路5.1 日志没输出先按优先级排查遇到日志没写出来先别改代码按下面的顺序排查级别过滤。logger 默认级别是 info如果设成了 warndebug 和 info 都不会输出。确认调用set_level的位置以及是否被别处的配置覆盖了。pattern 是否影响了终端显示。控制台日志和文件日志用同一个 logger 时pattern 里如果有终端控制字符文件里会出现乱码。检查 pattern 中的%^和%$。sink 配置是否正确。路径不存在、目录没有权限文件 sink 会创建失败。先检查目录是否存在程序是否以正确的权限运行。flush 策略。日志可能已经写进缓冲区但还没有落盘。程序没有正常退出时最后几行可能看不到。异步队列卡住或溢出。异步模式下队列满、后台线程挂掉日志都可能丢失。可以先改成同步模式验证。这五步是典型的排查链路。很多人一上来就改日志参数结果最后发现是路径写错了。5.2 flush 策略别等崩溃时才后悔spdlog 默认 flush 行为根据 sink 不同而不同。文件 sink 通常是缓冲区满了才写不够实时。如果你的项目追求强一致性希望 error 日志立刻落盘设置 flush 策略非常关键。两种常见方式logger-flush_on(spdlog::level::warn);上面表示 warn 及以上级别触发立即 flush。另一种是按时间定期 flushspdlog::flush_every(std::chrono::seconds(3));表示每 3 秒把已写内容 flush 一次。两者可以结合定时 flush 保证整体不滞后严重级别日志立刻 flush 保证关键信息不丢。这里要做一个权衡每次 flush 都会触发一次系统调用太高频会影响性能。太低频会增加崩溃丢日志的风险。我一般建议把阈值设在 warn 或 error这样信息级别的日志可以攒批错误日志确保可靠。5.3 符号、宽字符与中文路径C 在 Windows 上处理中文路径容易出幺蛾子。spdlog 的默认日志消息可以接收 UTF-8 字符串但程序本身如果使用 GBK 编码中文会乱码。Windows 上推荐的做法是项目内统一使用 UTF-8源文件保存为 UTF-8编译选项增加/utf-8。如果对接 MFC 的 CString 等宽字符类型需要先转成 UTF-8 再传给 spdlog。很多 MFC 项目中文日志乱码根源不是 spdlog而是工程编码不统一。日志文件路径也不要写死中文名除非确认运行环境的代码页一致。否则同样的代码在中文 Windows 正常在英文系统上路径可能异常。5.4 编译慢、模板过多与二进制包体积使用 fmt 格式化会有模板实例化开销。项目里大量调用logger-info(...{}, x)会生成很多模板实例。解决思路是使用预编译的 spdlog 库而不是 header-only。官方支持SPDLOG_COMPILED_LIB编译模式。引入这个模式后编译期压力会明显下降。代价是需要多维护一个库依赖但对大型项目来说值得。另一个办法是不要在头文件里大范围 include spdlog只在 .cpp 文件里 include这样能减少不必要的重编译。如果很多模块要用同一个 logger可以用一个封装函数只在实现文件里操作 spdlog上层只传入字符串和级别。5.5 多模块共享 logger 的管理方式一个大型项目往往有多个模块如果每个模块都创建自己的 logger容易造成混乱。更推荐的方法是统一初始化然后通过一个接口取 logger。基本做法可以是这样// log_manager.h #pragma once #include memory namespace app { class LogManager { public: static void Init(); static void Shutdown(); static std::shared_ptrspdlog::logger GetLogger(const std::string name); }; }初始化函数里创建好各个 sink 和 logger把不常用的 logger 通过spdlog::drop(name)释放。注意创建太多 logger 而且不 drop 的情况下spdlog 内部会持有它们的注册信息程序退出时可能崩。全局退出时调用spdlog::shutdown()。这里的关键是设计一个统一的“获取 logger”的入口让不同模块拿到的 logger 级别和输出格式一致而不是各写各的。6. 从会用走向用好一个可复用的落地框架6.1 日志配置的五个决策点综合前面所有内容我把 spdlog 在真实项目里的落地流程收敛成五个决策点任何一个项目都可以按这个顺序梳理输出目标只写控制台还是控制台加文件还是文件加远程日志对应 sink 的选择。格式内容需要时间戳吗需要线程号吗需要文件名和行号吗对应 pattern 的设计。切分策略按大小还是按时间保留多少个文件磁盘空间怎么约束对应 rotating 与 daily 的选择。性能模式日志量多大业务是否能容忍阻塞崩溃丢日志的风险怎么权衡对应同步与异步的选择。可靠性策略什么级别的日志必须立刻落盘定期 flush 的间隔是多少程序退出时如何优雅关闭对应 flush_on、flush_every、shutdown。这套框架最大的价值是让日志系统从一个“写文件的工具”变成有明确决策依据的设计环节。问清楚这五个问题整个日志方案基本就定了。6.2 适合用 spdlog 的场景中小型 C 项目需要快速接入日志不想自己封装太多。服务端程序需要控制台输出和文件输出并存。桌面客户端需要输出到调试窗口同时保留文件日志。多线程环境对线程安全有硬性要求。需要格式化输出使用 fmt 语法明显比sprintf方便。spdlog 在这些场景下几乎是无脑选择接入成本低、稳定性好、资料多、生态成熟。6.3 不适合或要谨慎的场景日志量极大、对审计一致性要求极高的金融交易系统。如果需要强一致性和完整审计链可能需要借助专门的日志中间件甚至依赖数据库事务记录而不是文件日志。多进程会话spdlog 只解决单进程多线程安全。多个进程写同一个文件需要额外的锁或统一文件名。需要可视化查询、日志检索、链路追踪能力的场景。spdlog 没有查询和聚合能力适合“记录日志”不适合“日志治理”。跨平台 UI 框架项目如果使用不同模块需要各自封装日志路径不同平台上的 sink 配置需要分别处理。spdlog 不适合的场景核心原因是它的位置很清晰它是一个高质量的文件日志库不是完整的日志平台。没有巡检、没有告警、没有查询、没有指标统计。这些能力需要搭配其他组件或自己实现。6.4 最后的动作先定规则再动手给团队引入 spdlog 时最怕的不是 API 不熟而是没有规则。没有 level 使用规范所有日志都打 info没有 pattern 约定每个模块一种格式没有轮转参数测试环境跑一天磁盘就满了。我建议第一步不是“先写代码”而是先花半小时确定下面几条底线级别使用规范什么情况用 debug什么情况用 info什么情况必须 error。统一 pattern团队内所有模块保持一致。flush 策略error 必须立即 flush。日志保留周期测试环境保留几天生产环境保留几天。同步还是异步默认同步性能验证后再切异步。规则定明白spdlog 才能真正成为项目的“日志基础设施”而不是一个比别人更快的 printf。spdlog 是个很成熟的库但它不负责替你做架构决策。真正决定日志系统好不好用的是你在那几个决策点上的判断以及团队能否长期遵守同一套规则。从这个角度看日志库的核心价值不是省几十行代码而是逼你把“日志”这件事当成一个正经的工程问题来看待。
spdlog实战：C++日志从printf到工程化基础设施
前一阵处理一个用 C 写的 Windows 服务故障现场日志文件已经涨到几个 GB编辑器打开直接卡死里面堆满了没有时间戳、没有级别、没有线程信息的 printf 输出。定位问题只能靠“大概什么时候崩的”和日志文件大小来猜。那次之后我把项目里的日志全部切到了 spdlog顺手帮团队把日志规范、轮转策略和异步刷盘一起定了下来。很多 C 开发者第一次认识 spdlog是因为它的宣传语header-only、极快、支持异步。但真正用下来你会发现spdlog 解决的不是“能打日志”这件事而是把 C 里原本很随意的日志输出改造为了一套可配置、可组合、可管理、能真正支撑线上排查的工程化基础设施。这篇文章不打算写成 API 手册而是从“为什么值得用”和“怎么用才不出问题”两个角度把它的核心抽象、落地流程、常见坑点和工程化建议一次讲透。1. 先搞清楚 spdlog 解决的是哪一类问题1.1 C 日志的常见混乱状态C 项目里最常见的日志做法是什么要么是 printf 加文件重定向要么是自己封装一个全局函数往里传字符串内部用 std::ofstream 追加写一行。小项目这样写没问题项目一旦大起来问题会集中爆发日志没有分级debug 信息和线上错误混在一起刷屏严重。没有统一格式时间戳、线程号、文件行号全靠手工拼不同模块风格还不一样。文件越写越大没有人管切割出了问题想下载日志文件都难。多线程下直接写文件互相穿插日志内容错乱。服务崩溃时最后几行日志往往还在缓冲区里没落盘线索直接丢失。这些问题不是“多写几行代码”能解决的。它本质上是一个工程问题日志系统需要在性能、可靠性、可读性和可维护性之间做平衡。而 spdlog 的价值就是把这套平衡方案做成了现成的、成熟的、可以快速集成的库。1.2 spdlog 的三个核心抽象想用好 spdlog先理解它的三个核心抽象就够了logger、sink、formatter。logger 是开发者直接使用的对象它负责接收日志消息、判断级别、调用格式化逻辑、把最终文本交给配置好的 sink。一个项目里可以创建多个 logger比如按模块拆分网络模块、业务模块、存储模块各一个。sink 是输出目标。它决定日志最终写到哪以及怎么写。常见的内置 sink 包括basic_file_sink单文件输出。rotating_file_sink按文件大小轮转。daily_file_sink按时间轮转。stdout_sink / stderr_sink控制台输出。msvc_sink输出到 Visual Studio 调试输出窗口。syslog_sink输出到系统 syslog。null_sink丢弃日志常用于性能测试或静默模式。一个 logger 可以绑定多个 sink。比如生产环境同时输出到文件和控制台或者同时输出到文件和一个监控接口。这就是后续多路日志的基础。formatter 决定日志文本的格式。spdlog 使用 pattern 字符串来定义格式例如[%Y-%m-%d %H:%M:%S.%e] [%l] [%t] %v分别代表时间、级别、线程号和消息内容。这个能力看起来简单但实际工程价值非常高因为它把“格式”和“内容”解耦了。调试时想看线程号加一个%t就行不需要改代码。这三个抽象一旦理解后面看 spdlog 的所有用法都会变得很顺logger 是入口sink 是外部世界的接口formatter 是中间的表达层。1.3 它不只是一个“攒日志的库”如果只是“写文件 轮转”很多库都能做到。spdlog 真正拉开差异的地方在于几件事性能优化到极致。通过编译期格式化、批量写入、可选异步模式让日志在低延迟要求下也几乎不阻塞业务逻辑。线程安全。内置的_mtmulti-thread版本 logger 和 sink 自带锁多线程环境直接使用也不会互相穿插。丰富的模板格式化。基于 fmt 库可以像 Python 一样写logger-info(value {}, val)不用手动拼接字符串。异常处理可配置。默认日志抛异常也可以关闭避免日志系统自身拖垮业务。这套设计让 spdlog 不只是“写日志”而是把日志从被动记录工具升级成了主动的可观测性基础设施。理解这一点再看后面的实践才会明白每一步设计都是有理由的。2. 上手路径从最小可用到多 sink 组合2.1 引入方式与环境准备spdlog 的使用很简单推荐先看官方仓库当前的 README再决定用哪种方式引入。常见引入方式有四种直接把 include 目录加进工程使用 header-only 模式这是最快的接入方式。使用 CMake FetchContent 拉取源码并构建成库适合团队统一管理依赖。使用 vcpkg 或 Conan 安装适合已经用包管理的项目。把源码完整拷贝进项目作为第三方模块编译。如果项目对构建速度敏感建议编译成静态库而不是使用 header-only。虽然 spdlog 宣传支持 header-only但对大型项目来说每个编译单元都编译一遍模板代码会明显拖慢构建。这是个很容易踩的细节先用 header-only 做验证没问题正式纳入项目时改成预编译库形式更稳妥。注意不同版本的 spdlog 在 API 细节上会有差异比如默认使用 fmt 库还是标准库 format接口参数也可能调整。落地前先查看当前版本的头文件与示例代码不要照抄旧博客上的写法。2.2 最小可运行示例先跑通一个最简单的例子#include spdlog/spdlog.h int main() { spdlog::info(Hello, {}!, spdlog); spdlog::warn(This is a warning, value: {}, 42); spdlog::error(Error code: {}, -1); return 0; }这段代码什么都不用配置默认输出到控制台格式已经自动带上了时间戳和颜色。对刚接触 spdlog 的人来说这个“零配置”体验很重要你不需要理解 logger、sink、formatter 这些概念就能先看到结果。然后进阶一步输出到文件#include spdlog/spdlog.h #include spdlog/sinks/basic_file_sink.h int main() { auto logger spdlog::basic_logger_mt(file_logger, logs/app.log); logger-set_level(spdlog::level::debug); logger-info(File logger is ready); logger-flush(); return 0; }这里的_mt后缀代表 multi-thread内部线程安全。对应地还有_st单线程版本性能更高但不允许跨线程使用。默认情况下建议都用_mt除非你非常确定某个 logger 只在单线程里访问。flush()是重点操作。它把缓冲区里的日志真正写进磁盘。如果不调用程序正常退出时会自动刷新但崩溃时缓冲区里的内容可能丢失。后面会专门展开 flush 策略。2.3 常用配置组合跑通文件输出后可以配置 pattern 和级别#include spdlog/spdlog.h #include spdlog/sinks/basic_file_sink.h int main() { auto logger spdlog::basic_logger_mt(app, logs/app.log); spdlog::set_pattern([%Y-%m-%d %H:%M:%S.%e] [%^%l%$] [thread %t] %s:%# %! : %v); logger-set_level(spdlog::level::debug); logger-debug(A debug message, number: {}, 123); logger-info(An info message); logger-warn(A warning message); logger-error(An error message); return 0; }pattern 里的几个关键占位符建议记住%Y-%m-%d %H:%M:%S.%e日期、时间、毫秒。%l日志级别如 debug、info、warn、error。%t线程 ID。%s、%#、%!文件名、行号、函数名。%v消息本体。%^与%$级别上色标记。默认文件日志是纯文本不加颜色。控制台日志可以带上颜色方便开发时直观分辨级别。2.4 MFC 场景怎么接入搜索热词里出现“mfc 使用 spdlog 例子代码”说明这是个高频需求。MFC 程序调试时开发者习惯在 Visual Studio 的“输出”窗口看调试信息传统做法是 OutputDebugString 或 TRACE 宏。如果想把 spdlog 的日志同时输出到 VS 输出窗口和文件可以用 multi-sink 组合。一个典型做法是创建一个 vector 装 sink然后构造 logger#include spdlog/spdlog.h #include spdlog/sinks/msvc_sink.h #include spdlog/sinks/rotating_file_sink.h void InitMfcLogger() { std::vectorspdlog::sink_ptr sinks; sinks.push_back(std::make_sharedspdlog::sinks::msvc_sink_mt()); sinks.push_back(std::make_sharedspdlog::sinks::rotating_file_sink_mt( logs/mfc_app.log, 1024 * 1024 * 5, 3, true)); auto logger std::make_sharedspdlog::logger(mfc_logger, sinks.begin(), sinks.end()); logger-set_level(spdlog::level::debug); logger-flush_on(spdlog::level::warn); spdlog::set_default_logger(logger); } void OnAppExit() { spdlog::shutdown(); }这样在开发时VS 调试窗口里能实时看到日志同时文件里也在持续记录正式日志。上线后可以去掉 msvc_sink只保留文件或多路输出。这个例子很典型地体现了 spdlog 的“组合”优势不需要为不同场景写不同的日志实现只需要调换或增删 sink。3. 性能、异步与线程安全它不是魔法但很有章法3.1 为什么 spdlog 快spdlog 宣传自己性能极高很多测试里都能到每秒百万条级别。这个快不是靠玄学主要有几个贡献因素编译期格式化。使用 fmt 库在编译期解析格式字符串运行时不需要反复解析%d %s这类占位符。最小化锁粒度。多线程版本里使用细粒度锁降低了线程竞争。批量写入和异步队列。异步模式下业务线程只负责把日志消息放进队列写盘工作交给后台线程。避免不必要的内存分配。通过复用缓冲区减少了每次日志都 new 内存的开销。但性能数字总是有条件的。网上看到的测速结果通常是不开文件、不做轮转、使用 null sink 或者内存缓冲区时的“极限成绩”。真实工程里落到文件上的速度会被磁盘 I/O 明显拖慢尤其日志量大时。所以看待 spdlog 的性能要分两层格式化快不快是一回事落盘快不快是另一回事。3.2 异步模式的价值与代价异步日志的核心思路是业务线程把日志消息 push 到内存队列里立刻返回后台线程从队列取出消息执行格式化、写文件。这样业务逻辑几乎不被日志拖住。开启异步的基本写法#include spdlog/spdlog.h #include spdlog/async.h #include spdlog/sinks/rotating_file_sink.h void InitAsyncLogger() { spdlog::init_thread_pool(8192, 1); auto file_sink std::make_sharedspdlog::sinks::rotating_file_sink_mt( logs/async.log, 1024 * 1024 * 5, 3); std::vectorspdlog::sink_ptr sinks { file_sink }; auto logger std::make_sharedspdlog::async_logger( async_logger, sinks.begin(), sinks.end(), spdlog::thread_pool(), spdlog::async_overflow_policy::block); spdlog::set_default_logger(logger); }这里有两个关键参数要理解队列大小。上面写的 8192 表示队列最多装 8192 条日志。溢出策略。block表示队列满了就阻塞业务线程等待队列腾出空间overrun_oldest表示丢弃最旧的日志保证新日志总能进入。在设计评估时要注意异步不是免费午餐。如果日志量特别大队列会被写满。选block会反过来阻塞业务选overrun_oldest会丢日志。对需要可靠审计的场景丢日志不可接受这时要么同步写要么提高队列并配合合理的日志量控制对性能优先的场景丢一点 debug 日志可接受用overrun_oldest更合理。另一个代价是崩溃时丢失最后一段日志。异步模式下数据先在队列里后台线程还没写完。如果进程直接崩掉或者 kill -9这部分日志确实会丢。解决思路包括设置 flush 策略、定期 flush、应用层补 watchdog或者接受“审计不追求最后一刻”的取舍。3.3 线程安全怎么看待spdlog 的_mt系列自带线程安全的锁多个线程对同一个 logger 调用 info、error 不会互相穿插。但这不等于你的日志内容一定是“有意义的整体”。如果业务逻辑分多行日志描述一件事多线程并发下A 线程的第一行后面可能插入 B 线程的日志。为了避免这种情况可以把一个场景的日志拼成一条消息输出保持日志的原子性。单线程版本_st性能更高但没有线程安全保障。如果某个 logger 只在固定线程里使用可以选用_st否则不要冒险。我见过有人为了性能把所有 logger 都改成_st结果偶发崩溃排查了半天最后发现是日志对象跨线程访问的问题完全没必要。经验先默认_mt用性能分析证明日志确实是瓶颈再优化。多数项目的瓶颈在数据库、网络或业务算法不在日志。4. 轮转策略与文件管理4.1 rotating_file_sink按大小切割日志文件不能无限增长。轮转rotation就是限制单个文件大小达到阈值时自动切换到新文件。auto logger spdlog::rotating_logger_mt(rotate_logger, logs/app.log, 1024 * 1024 * 10, 5);参数含义第三个参数是单文件最大字节数上面是 10MB。第四个参数是保留的文件数量。假设保留 5 个文件实际文件会是app.log、app.1.log、app.2.log…app.4.log。app.log永远是当前正在写的文件。达到 10MB 时它会变成app.1.log旧文件依次顺延最旧的那个被删除。这个策略适合日志量比较稳定的服务搭配定期归档落冷存储。如果日志量波动很大比如某天线上异常导致爆量单文件切得飞快历史文件很快被冲掉这时需要更慎重的保留策略。4.2 daily_file_sink按时间切割按大小切适合控制单个文件大小按时间切更适合按天归档的习惯auto logger spdlog::daily_logger_mt(daily_logger, logs/daily.log, 0, 0);第三个参数是小时第四个是分钟。0, 0表示每天凌晨 0 点切换。每天生成一个新文件文件命名会自动带上日期。时间轮转的优点是查询日志时“按天找”很方便缺点是一个文件可能很大如果某天日志特别多文件会非常臃肿。实践中常把两者结合daily 负责自然日归档rotating 负责限制单文件大小。如果只用 daily最好额外加一个定期清理脚本避免磁盘被历史文件占满。4.3 日志文件的打开模式与多进程问题spdlog 写文件时默认策略需要考虑。如果程序重启是把日志追加到旧文件里还是直接覆盖这个行为取决于打开模式。默认通常是 append。如果需要覆盖写要在 sink 构造时传参数auto logger spdlog::rotating_logger_mt(rotate_logger, logs/app.log, 1024 * 1024 * 10, 5, true);最后一个参数是truncate。传true会截断已存在的文件。这个选项要谨慎生产环境一般不要截断否则会丢失历史日志。多进程写同一个日志文件是另一个坑。spdlog 的_mt只能保证一个进程内的多线程安全不保证多进程写同一个文件的安全。两个进程同时以追加模式写同一个文件日志可能交错。规范做法是每个进程使用独立文件名或者日志服务单独承担汇总职责。5. 常见坑点与排查链路5.1 日志没输出先按优先级排查遇到日志没写出来先别改代码按下面的顺序排查级别过滤。logger 默认级别是 info如果设成了 warndebug 和 info 都不会输出。确认调用set_level的位置以及是否被别处的配置覆盖了。pattern 是否影响了终端显示。控制台日志和文件日志用同一个 logger 时pattern 里如果有终端控制字符文件里会出现乱码。检查 pattern 中的%^和%$。sink 配置是否正确。路径不存在、目录没有权限文件 sink 会创建失败。先检查目录是否存在程序是否以正确的权限运行。flush 策略。日志可能已经写进缓冲区但还没有落盘。程序没有正常退出时最后几行可能看不到。异步队列卡住或溢出。异步模式下队列满、后台线程挂掉日志都可能丢失。可以先改成同步模式验证。这五步是典型的排查链路。很多人一上来就改日志参数结果最后发现是路径写错了。5.2 flush 策略别等崩溃时才后悔spdlog 默认 flush 行为根据 sink 不同而不同。文件 sink 通常是缓冲区满了才写不够实时。如果你的项目追求强一致性希望 error 日志立刻落盘设置 flush 策略非常关键。两种常见方式logger-flush_on(spdlog::level::warn);上面表示 warn 及以上级别触发立即 flush。另一种是按时间定期 flushspdlog::flush_every(std::chrono::seconds(3));表示每 3 秒把已写内容 flush 一次。两者可以结合定时 flush 保证整体不滞后严重级别日志立刻 flush 保证关键信息不丢。这里要做一个权衡每次 flush 都会触发一次系统调用太高频会影响性能。太低频会增加崩溃丢日志的风险。我一般建议把阈值设在 warn 或 error这样信息级别的日志可以攒批错误日志确保可靠。5.3 符号、宽字符与中文路径C 在 Windows 上处理中文路径容易出幺蛾子。spdlog 的默认日志消息可以接收 UTF-8 字符串但程序本身如果使用 GBK 编码中文会乱码。Windows 上推荐的做法是项目内统一使用 UTF-8源文件保存为 UTF-8编译选项增加/utf-8。如果对接 MFC 的 CString 等宽字符类型需要先转成 UTF-8 再传给 spdlog。很多 MFC 项目中文日志乱码根源不是 spdlog而是工程编码不统一。日志文件路径也不要写死中文名除非确认运行环境的代码页一致。否则同样的代码在中文 Windows 正常在英文系统上路径可能异常。5.4 编译慢、模板过多与二进制包体积使用 fmt 格式化会有模板实例化开销。项目里大量调用logger-info(...{}, x)会生成很多模板实例。解决思路是使用预编译的 spdlog 库而不是 header-only。官方支持SPDLOG_COMPILED_LIB编译模式。引入这个模式后编译期压力会明显下降。代价是需要多维护一个库依赖但对大型项目来说值得。另一个办法是不要在头文件里大范围 include spdlog只在 .cpp 文件里 include这样能减少不必要的重编译。如果很多模块要用同一个 logger可以用一个封装函数只在实现文件里操作 spdlog上层只传入字符串和级别。5.5 多模块共享 logger 的管理方式一个大型项目往往有多个模块如果每个模块都创建自己的 logger容易造成混乱。更推荐的方法是统一初始化然后通过一个接口取 logger。基本做法可以是这样// log_manager.h #pragma once #include memory namespace app { class LogManager { public: static void Init(); static void Shutdown(); static std::shared_ptrspdlog::logger GetLogger(const std::string name); }; }初始化函数里创建好各个 sink 和 logger把不常用的 logger 通过spdlog::drop(name)释放。注意创建太多 logger 而且不 drop 的情况下spdlog 内部会持有它们的注册信息程序退出时可能崩。全局退出时调用spdlog::shutdown()。这里的关键是设计一个统一的“获取 logger”的入口让不同模块拿到的 logger 级别和输出格式一致而不是各写各的。6. 从会用走向用好一个可复用的落地框架6.1 日志配置的五个决策点综合前面所有内容我把 spdlog 在真实项目里的落地流程收敛成五个决策点任何一个项目都可以按这个顺序梳理输出目标只写控制台还是控制台加文件还是文件加远程日志对应 sink 的选择。格式内容需要时间戳吗需要线程号吗需要文件名和行号吗对应 pattern 的设计。切分策略按大小还是按时间保留多少个文件磁盘空间怎么约束对应 rotating 与 daily 的选择。性能模式日志量多大业务是否能容忍阻塞崩溃丢日志的风险怎么权衡对应同步与异步的选择。可靠性策略什么级别的日志必须立刻落盘定期 flush 的间隔是多少程序退出时如何优雅关闭对应 flush_on、flush_every、shutdown。这套框架最大的价值是让日志系统从一个“写文件的工具”变成有明确决策依据的设计环节。问清楚这五个问题整个日志方案基本就定了。6.2 适合用 spdlog 的场景中小型 C 项目需要快速接入日志不想自己封装太多。服务端程序需要控制台输出和文件输出并存。桌面客户端需要输出到调试窗口同时保留文件日志。多线程环境对线程安全有硬性要求。需要格式化输出使用 fmt 语法明显比sprintf方便。spdlog 在这些场景下几乎是无脑选择接入成本低、稳定性好、资料多、生态成熟。6.3 不适合或要谨慎的场景日志量极大、对审计一致性要求极高的金融交易系统。如果需要强一致性和完整审计链可能需要借助专门的日志中间件甚至依赖数据库事务记录而不是文件日志。多进程会话spdlog 只解决单进程多线程安全。多个进程写同一个文件需要额外的锁或统一文件名。需要可视化查询、日志检索、链路追踪能力的场景。spdlog 没有查询和聚合能力适合“记录日志”不适合“日志治理”。跨平台 UI 框架项目如果使用不同模块需要各自封装日志路径不同平台上的 sink 配置需要分别处理。spdlog 不适合的场景核心原因是它的位置很清晰它是一个高质量的文件日志库不是完整的日志平台。没有巡检、没有告警、没有查询、没有指标统计。这些能力需要搭配其他组件或自己实现。6.4 最后的动作先定规则再动手给团队引入 spdlog 时最怕的不是 API 不熟而是没有规则。没有 level 使用规范所有日志都打 info没有 pattern 约定每个模块一种格式没有轮转参数测试环境跑一天磁盘就满了。我建议第一步不是“先写代码”而是先花半小时确定下面几条底线级别使用规范什么情况用 debug什么情况用 info什么情况必须 error。统一 pattern团队内所有模块保持一致。flush 策略error 必须立即 flush。日志保留周期测试环境保留几天生产环境保留几天。同步还是异步默认同步性能验证后再切异步。规则定明白spdlog 才能真正成为项目的“日志基础设施”而不是一个比别人更快的 printf。spdlog 是个很成熟的库但它不负责替你做架构决策。真正决定日志系统好不好用的是你在那几个决策点上的判断以及团队能否长期遵守同一套规则。从这个角度看日志库的核心价值不是省几十行代码而是逼你把“日志”这件事当成一个正经的工程问题来看待。
