简介这是一个面向 C 开发者的轻量级日志类资源解决中小型项目或工具中日志记录引入过重依赖的问题。核心实现仅有一个 ylog.h 头文件约 60 多行代码不依赖第三方库不定义宏和全局变量使用标准库即可在 Windows 与 Linux 下编译运行同时支持多线程安全输出每条日志可携带级别、时间、所在文件名、行号及自定义信息。压缩包内含 5 个文件包括头文件、示例 main.cc、makefile、README.md 以及 .gitignore整体仅 4KB结构简洁方便直接整合进现有工程。资源已吸引 410 人浏览学习适合希望快速理解日志封装原理、或在轻量场景中直接使用的 C 初学者及进阶开发者。通过阅读源码与示例可掌握日志级别控制、文件写入方式以及线程安全设计思路。1. 从需求出发为什么还要写一个“新”日志类先说点实际的。C 生态里日志库一抓一大把log4cpp、spdlog、glog、easylogging哪个不是久经考验刚接触这个项目的人第一反应基本都是又造轮子我一开始也这么想但真正深入之后才明白很多嵌入式、客户端、教学演示场景对日志的需求其实非常朴素——能按级别输出、能带时间戳、能控制开关、编译别太重。这些需求用 spdlog 当然能实现但转头一看光是头文件展开就多出好几百 KB交叉编译还要带着一堆依赖就比较难受了。ylog 这个项目要解决的正是这个问题一个头文件加一个源文件不依赖任何第三方库只用 C11 标准库就能提供日常开发里 90% 的日志场景能力。这种需求在单片机上位机、Windows 桌面小工具、Linux 服务端辅助模块、甚至刷题验证算法时都很常见。适合的场景不是大型分布式系统而是中小型项目里“我要看得见程序在干什么”这个基本诉求。另外一个很现实的原因是可定制性。大型日志框架封装层次多改动内部行为往往要翻很久源码。ylog 这种小类核心代码就几百行任何行为不满意直接动手改就是改完立刻生效。这种“代码量小到可以整体读一遍”的优势在实际工程维护里其实非常值钱。我当初用 ylog 的场景是一个串口数据采集工具跑在 Windows 上需要同时记录数据帧、错误信息、调试输出。原来 console 输出一多就乱关键信息被刷掉排查问题全靠猜。接手代码后第一件事就是把日志系统理顺ylog 也是在这个背景下一点点打磨成型的。2. 整体设计与核心实现2.1 日志级别与模块划分日志库的第一个核心问题就是级别。ylog 采用六级划分TRACE、DEBUG、INFO、WARN、ERROR、FATAL。这个划分基本沿袭主流日志库惯例好处是大家一看就懂不需要额外培训。设计上最关键的一点是日志级别过滤在编译期和运行期双重生效。编译期通过宏控制最低输出级别运行期通过设置当前输出级别动态过滤。这样做的好处很实在发布版本直接编译到 INFO 级别所有 DEBUG 和 TRACE 的输出代码虽然还在但编译后不产生任何开销。实话说这个设计是从 Android 的 Log 系统借鉴过来的很成熟也很符合 C 的“零成本抽象”哲学。模块划分上ylog 支持一个程序内创建多个日志实例每个实例有独立的名称、输出目标和级别设置。这个设计在小工具里看起来有点过度设计但只要你的程序有“业务模块”和“底层通信模块”之分日志分开管理的好处立刻就能体现出来——排查串口数据问题时你只需要盯 communication 这个日志文件不用在业务日志里翻来翻去。2.2 流式接口与宏定义用过 C 日志库的人都知道流式接口是标配。:按位左移 这种方式写日志比 printf 格式串安全得多类型不对在编译期就能发现。ylog 的接口也遵循这个惯例LOG_INFO user login, uid uid , ip ip;这里实际调用的是LOG_INFO宏。宏的设计是这个项目的一个亮点直接决定使用体验。定义大致如下#define LOG_INFO ylog::LogMessage(__FILE__, __LINE__, ylog::LogLevel::INFO).stream()每一步拆开看LogMessage是一个临时对象构造时记录文件名、行号、级别和时间戳.stream()返回一个std::ostringstream引用析构时把流里的内容格式化后写入输出目标。临时对象在当前语句结束时自动析构所以一行LOG_INFO就是一条完整日志不需要手动 flush。这个 RAII 设计带来的好处是——即使你写日志的代码抛出异常临时对象析构时依然会尝试输出日志不会静默丢失当然如果ostringstream本身抛异常就另当别论了。FATAL 级别还有一点特殊处理输出日志后直接调用abort()终止程序模拟 assert 的行为。这在调试阶段特别有用遇到不可恢复的错误直接崩溃并留下现场日志比“程序继续跑然后各种诡异现象”要好排查得多。2.3 单例与生命周期管理日志库的全局访问方式主流做法无非两种单例模式或全局函数。ylog 用的是Meyers SingletonC11 之后这种写法是线程安全的标准保证局部静态变量的初始化是线程安全的。代码很简单Logger Logger::instance() { static Logger instance; return instance; }单例的生命周期问题在日志库上尤其需要小心。如果日志库内部还持有其他单例的引用或反过来被其他单例持有时析构顺序就会变得完全不可控。ylog 的应对策略是析构时不强制 flush而是依赖操作系统关闭文件句柄时刷新缓冲区。听起来有点偷懒但实际测试中只要不是_Exit()这类直接终止的手段标准库的std::fstream析构是会正常刷盘关闭的。这也是一个踩过坑之后才加上的注释说明。另外ylog 显式提供了shutdown()方法让使用者在 main 函数末尾按需调用。这是一个从实践出发的设计嵌入式上位机有时需要断开串口后把日志彻底落盘再退出程序有了这个方法就能精确控制日志的最终输出时机。3. 关键功能实现解析3.1 时间戳与格式化日志里的时间戳看着是个小功能真要做得顺手也不简单。ylog 内部使用chrono获取当前时间再通过ctime格式化为字符串。有一个细节值得拿出来说不要每次获取时间都调用localtime这种线程不安全的函数。ylog 里的做法是调localtime_r或使用std::put_time具体取决于平台。格式化输出方面常用的控制项包括是否显示完整毫秒时间戳是否显示文件名和行号是否显示线程 ID日志前缀的样式纯文本还是带颜色控制码。console 输出时默认带 ANSI 颜色文件输出时则去掉颜色码。这两个场景需求不同用一个设置项控制容易互相干扰。ylog 的处理是对不同输出目标分别设置console 和文件独立控制。实际用起来很舒服文件里干干净净终端上一目了然。有一点很多自研日志库没处理好而 ylog 处理了的日志写入时对换行符的处理。Windows 下std::endl会输出\r\nLinux 下只有\n。如果一份日志文件在 Windows 上生成后拿到 Linux 上看会被\r干扰。ylog 内部统一用\n并显式将std::fstream打开为二进制模式避免平台相关的转换。这是个小细节但能省掉不少跨平台查看日志时的烦躁。3.2 日志文件管理与输出目标文件输出是日志库的基本盘。ylog 支持以下输出目标组合输出目标说明典型场景Console标准输出/标准错误可带颜色开发调试File指定路径的单文件服务端记录FileWithRotate按大小轮转多个文件长时间运行的桌面工具轮转日志是长时间运行程序的好帮手。实现逻辑在RotatingFileSink里写入前检查当前文件大小超过阈值就关闭旧文件、把旧文件改名加序号如app.log.1然后新建app.log。同时保留最大文件数量超出后删除最老的。有个细节是这个轮转逻辑不是按行判断的而是按字节计数的。也就是说一条超过阈值的日志可能会自己占满一个文件。这在极端场景比如一条 10 MB 的 JSON 数据被打印出来会有点意外但这是所有按大小轮转日志框架的通病。解决方案也简单在业务代码里给大对象单独处理别直接用日志流输出。3.3 线程安全设计多线程环境下写日志核心就是两件事保证日志内容不交错、保证日志库内部状态不崩。ylog 的做法是全局一个std::mutex所有写入操作持锁完成。简单粗暴但在低并发场景每秒几十到几百条日志完全够用锁竞争导致的性能损耗可以忽略不计。更精细的设计是每日志实例一把锁这样不同模块的日志之间不互相阻塞。但我实测下来对 ylog 的定位来说全局锁就够了还省掉一个“该锁哪个实例”的心智负担。有一条经验分享日志库的线程安全是为了“不出错”不是为了“高并发”。真的每秒写几万条日志你会用 spdlog 的异步队列而不是这种轻量级方案。线程 ID 的获取在 C11 标准里没有跨平台APIylog 的做法是条件编译Linux 用syscall(SYS_gettid)Windows 用GetCurrentThreadId()。没有用std::this_thread::get_id是因为它返回的是内部表示在排查问题时很难对应到系统线程 ID比如 gdb 里看到的 LWP 编号。4. 接入与使用实践4.1 工程集成方式ylog 的工程集成方式非常省心只有两个文件ylog.h和ylog.cpp。我实际用过的集成方式有三种直接拷贝源码到工程目录适合源码级依赖改动方便最推荐编译成静态库适合多个可执行文件共用同一份日志实现安装到系统路径适合做公共组件但不推荐因为小库的迭代速度快系统级安装反而限制更新。对大多数中小项目最简单的方式就是直接把两个文件丢进src/common目录在构建系统里扫进源码列表。CMake 里大概是这样add_library(common STATIC src/common/ylog.cpp ) target_include_directories(common PUBLIC src/common)4.2 日常使用的配置技巧实际项目中我推荐大家配日志时抓住下面几个点设置合理的运行级别。开发环境可以用 DEBUG看看流程细节发布时至少 INFO。这里的核心教训是——日志级别一定要支持运行期动态修改最好做一个信号处理器或配置热加载机制。我见过很多系统出问题时想开 DEBUG 日志结果被迫重启服务现场就丢了。按模块拆分文件。程序里如果有网络收发和业务处理两大块建议建两个 Log instance分别写不同文件。排查问题时非常爽一看文件名就知道该去哪找。开头的初始化代码要固定。ylog 的初始化我一般放在程序入口最前面全局配置集中在一起方便维护ylog::Logger logger ylog::Logger::instance(); logger.setLevel(ylog::LogLevel::DEBUG); logger.setFileOutput(logs/app.log, 5 * 1024 * 1024, 10); logger.setConsoleOutput(true);需要注意setFileOutput的第二个参数是单文件大小上限第三个是保留文件数。如果程序是系统服务用 systemd 托管文件路径记得用绝对路径别依赖工作目录。5. 踩坑记录与问题排查5.1 常见问题速查表现象可能原因解决办法日志文件为空程序异常终止析构未执行关键路径主动调用shutdown()日志时间戳少 8 小时localtime与gmtime混用统一使用本地时间避免混用终端输出是乱码Windows 下中文编码问题源文件保存为 UTF-8 with BOM或使用/utf-8编译选项多线程日志互相穿插使用了多个日志实例且未统一锁检查是否所有写入都走同一实例或为每个实例独立加锁轮转文件数量超过上限多进程共用同一日志文件日志文件名中加入 PID 或进程名FATAL 日志输出后程序未退出自定义了 SIGABRT 处理检查是否拦截了 abort 信号如需定制修改宏定义5.2 具体踩过的几个坑第一个坑析构时崩溃。有一次在程序退出时出现偶发崩溃排查了半天发现是某个全局对象析构时还在写日志而单例日志对象已经先一步析构了。根治办法有两个一是全局对象析构时避免写日志二是保证日志单例比其他全局对象更晚析构。后者不好控制所以 ylog 的析构函数里特意做了容错处理捕获一切异常保证析构不抛异常。这也是为什么我建议你不要写出“日志库析构时还会失败”的代码——日志库自身的健康必须保证。第二个坑被信号打断的日志。程序收到 SIGTERM 直接退出时最后几次日志经常丢失。后来看了下是因为默认的信号处理只做进程终止不做清理。解决方式是在信号处理函数里调用ylog::Logger::shutdown()注意信号处理函数里调用非异步安全函数本身有风险需要权衡或者更简单程序正常退出时统一调用 shutdown信号处理只负责设置标志位主循环检查后优雅退出。第三个坑频繁写日志导致的性能问题。早期版本在 console 输出时每次都刷新标准输出缓冲区跑一次数据采集循环要 30 多秒去掉刷新后压缩到 2 秒不到。所以 ylog 的 Console 输出默认是不刷新的只有显式调用flush()或者到达std::endl才会真正写入显示设备。这里有个权衡程序崩溃时 console 最后几行可能没打出来。我的建议是调试时打开自动 flush发布时关闭换取性能。5.3 调试日志与性能的平衡聊点实用的东西。写日志不是越多越好无脑 DEBUG 输出到最后没人看而且拖慢程序。我一直以来的习惯是函数入口出口不打日志只在关键决策点打循环体内尽量别打日志如果要打就加频控每 1000 次打一条数据量大时先截断再输出比如只打印前 64 字节错误日志一定要带上下文信息比如 errno、指针值、网络状态否则事后看日志等于看天书。这些最佳实践和日志库本身无关但却是让 ylog 这类工具发挥价值的核心。一个再轻量的日志类被塞进高频循环里照样会拖垮性能。日志代码本身要克制这是长期写日志系统的人最大的心得。6. 实用扩展从日志到多场景ylog 虽然定位轻量但做一点扩展后能适用的场景远不止“打日志”这么简单。我实际扩展过的方向有三个作为调试动态开关。通过环境变量控制日志级别比如export YLOG_LEVELDEBUG程序跑起来后临场查看逻辑细节。这个扩展只要在初始化时读一下环境变量就能实现改动成本极低收益却很直接。接入网络上报。在Sink层加一个网络输出目标把 WARN 以上级别的日志实时上报到集中日志服务实现轻量告警。这个方向适合小服务集群不用引入完整的日志采集链路。录制回放工具。程序跑的过程中把关键输入输出按特定格式打印之后写脚本解析日志、模拟输入回放。这种方式在算法调试时非常实用等于给程序加了一个“录像机”。ylog 里的TRACE级别正好作为回放数据的载体不干扰正常日志的阅读。这些扩展本身都很简单但能看出一个好的日志基础组件能带来的杠杆效应。核心代码稳定、接口清晰扩展的能力就有了抓手这也是轻量级组件的价值所在——不限制你而是让你在它之上做出自己的方案。最后再分享一个实际使用中的体会日志类这种东西代码量不重要稳定性和可读性才重要。ylog 的代码总共就几百行但它让我在最需要排查问题时能快速定位在跨平台部署时没有额外依赖在性能敏感场景下不至于拖后腿。对一个工具类组件来说这已经算交出了一份让我满意的答卷。如果你也是一个人维护中小型 C 项目找个时间把日志模块理顺真的是性价比很高的一件事。本文还有配套的精品资源点击获取