现代 C++ 工程日志系统设计：从 spdlog 到异步落盘实践

林夕07

759人浏览 · 2026-05-25 08:30:00

林夕07 · 2026-05-25 08:30:00 发布

现代 C++ 工程日志系统设计：从 spdlog 到异步落盘实践

很多 C++ 项目早期都不太重视日志：std::cout 能看就行，调试时输出几行文本也够用。但项目只要进入多人协作、长期维护、线上运行阶段，你很快就会发现——没有一套像样的日志体系，定位问题几乎靠运气。

尤其是在桌面客户端、仿真系统、设备控制平台、后台服务这类项目中，日志不是“锦上添花”，而是最基本的排障基础设施。

本文就围绕现代 C++ 项目的日志系统设计展开：

为什么日志系统要单独设计
日志分级、格式、文件切分怎么定
为什么推荐 spdlog
异步落盘什么时候值得上
多线程环境下怎么避免日志拖慢主流程

一、日志系统不是 printf 的升级版

先说结论：

日志系统的核心目标不是“打印文本”，而是让你在出问题时，有足够的信息还原现场。

所以一个可用的日志体系，至少要解决下面这些问题：

日志按严重程度分级
格式统一，便于搜索和过滤
文件可滚动切分，避免无限增长
多线程下输出有序、不打架
关键路径不能被同步 IO 拖慢
最好能兼顾控制台与文件输出

如果这些都没有，那么日志越多，后期越痛苦。

二、先把日志级别定义清楚

一个很常见的反模式是：

什么都打 info
真出错了也只是输出一句“失败了”
同一个模块里日志风格完全不一致

推荐最少定义下面几级：

级别	用途
trace	最细粒度调试信息，默认关闭
debug	开发期调试信息
info	正常业务流程关键信息
warn	异常但未中断流程的情况
error	需要关注的失败事件
critical	可能导致系统不可用的严重错误

关键不是“级别多高级”，而是团队要统一：

什么场景算 warn
什么场景必须打 error
线上默认打开哪些级别

三、日志内容怎么设计才有用？

一条好日志应该回答这些问题：

什么时候发生的？
发生在哪个线程 / 模块？
执行到了哪一步？
携带了哪些关键参数？
结果成功还是失败？

例如下面两条日志：

logger->error("load failed");

logger->error("Load config failed, path={}, reason={}", path, errorMessage);

第二条才是能真正帮助定位问题的日志。

四、为什么很多 C++ 项目会选 spdlog

原因很简单：

API 现代、好用
基于 fmt，格式化体验好
性能不错
同时支持同步 / 异步日志
控制台、文件、滚动文件都支持
集成成本低

一个最小示例

#include <spdlog/spdlog.h>
#include <spdlog/sinks/rotating_file_sink.h>

int main()
{
    auto logger = spdlog::rotating_logger_mt(
        "app",
        "logs/app.log",
        5 * 1024 * 1024,
        3);

    logger->set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%l] [thread %t] %v");
    logger->info("Application started");
    logger->warn("Config file not found, using defaults");
    logger->error("Connect server failed, code={}", 500);
}

这段代码已经具备：

文件输出
滚动切分
统一格式
多线程安全 logger

对于绝大多数桌面与服务端项目，已经是很好的起点。

五、什么时候需要异步日志？

很多人一上来就想“性能最大化”，于是直接全项目异步日志。其实没必要。

同步日志适合：

小中型桌面应用
普通工具类程序
日志量不大
更看重简单稳定

异步日志适合：

高频日志输出
多线程后台任务很多
主链路对延迟敏感
批量数据处理 / 服务端场景

异步日志的核心价值是：

把磁盘写入和格式化成本，从业务线程中移走。

spdlog 异步示例

#include <spdlog/async.h>
#include <spdlog/sinks/rotating_file_sink.h>

spdlog::init_thread_pool(8192, 1);

auto sink = std::make_shared<spdlog::sinks::rotating_file_sink_mt>(
    "logs/app.log", 10 * 1024 * 1024, 5);

auto logger = std::make_shared<spdlog::async_logger>(
    "async_app",
    sink,
    spdlog::thread_pool(),
    spdlog::async_overflow_policy::block);

spdlog::register_logger(logger);

这里有两个关键点：

队列大小要合理
队列满了是阻塞还是丢日志，要按业务场景选

六、多线程项目里，日志系统常见的坑

6.1 在热点循环里无脑打日志

例如每处理一条数据就打一条 info，这会迅速制造 IO 压力。

更合理的做法是：

高频路径默认只开 debug/trace
线上降级日志级别
用统计日志替代逐条日志

6.2 日志字符串自己拼接

logger->info(std::string("user=") + user + ", id=" + std::to_string(id));

这种写法会产生额外临时对象，既丑又没必要。

更推荐：

logger->info("user={}, id={}", user, id);

6.3 错误日志没有上下文

只写 open failed 基本等于没写。错误日志要带：

文件路径
错误码
关键参数
当前阶段

6.4 程序退出时没 flush

尤其异步日志，如果退出前不 flush，最后一批日志可能丢失。

建议在应用退出阶段主动：

spdlog::shutdown();

七、一个更实用的日志封装思路

真实项目里，通常不会到处直接裸调 spdlog::get("app")。更好的方式是封装一层自己的日志入口。

class Log
{
public:
    static void init();
    static std::shared_ptr<spdlog::logger> core();
};

这样有几个好处：

后面换日志库成本低
可以统一初始化策略
可以按模块创建子 logger
方便挂接文件路径、等级、格式等配置

如果项目模块多，还可以进一步区分：

Core Logger
Network Logger
Ui Logger
Db Logger

这样排查时会清晰很多。

八、日志系统上线前的检查清单

基础能力

是否有统一日志初始化入口？
是否定义了明确日志级别？
是否统一了输出格式？

文件策略

是否有滚动切分？
是否有限制单文件大小？
是否有限制历史文件数量？

性能与线程

高频路径是否避免大量 info 日志？
是否评估过同步/异步策略？
程序退出时是否 flush？

可维护性

错误日志是否带足上下文？
是否按模块区分 logger？
是否方便线上定位问题？

九、结语

现代 C++ 项目里的日志系统，真正重要的不是“库选得多高级”，而是是否满足这三个目标：

出了问题能快速定位
不会明显拖慢主流程
团队长期维护时依然一致可控

spdlog 之所以流行，不只是因为它快，更因为它让一套像样的日志体系变得很容易落地。

如果你现在的项目里还在大量使用 std::cout 和零散输出，建议尽快补上日志系统建设。很多线上问题不是“解决不了”，而是压根没有足够信息去还原它。

优秀的日志系统，不会让你在平时觉得它存在感很强；但一旦系统出事，它往往就是你最可靠的第一现场。

亚马逊云科技技术品牌专区

更多推荐

Zipkin vs Jaeger：Java程序员的链路追踪选型血泪史，我替你们把坑踩完了！

亚马逊云科技技术品牌专区

DolphinDB：高性能时序数据库与数据分析平台

DolphinDB 是一款集高性能时序数据库、流数据处理和复杂分析于一体的国产一体化平台。它专为金融、物联网、工业互联网等海量时序数据场景设计，提供从数据存储、实时计算到深度分析的全栈能力。DolphinDB 凭借其高性能、一体化的设计，在时序数据处理领域展现出显著优势。对于需要处理海量时序数据并进行实时分析的应用，它是一个值得深入研究和采用的技术选型。