14.1 日志管理器
跑起来一个引擎,第一件事往往是「看它说了什么」。OGRE 的日志系统以 Log 类为核心:消息有级别,日志有最小级别门槛,高于门槛的消息才被记录;记录时既写文件、又按严重程度分流到 stdout/stderr。这一节拆 Log::logMessage 的完整处理链。
本章与站内既有内容的分工
13 章讲内存与容器;这里讲运行期观测。站内 go-runtime/java-conc 系列也讲日志,但对象是语言运行时;OGRE 的日志是纯 C++ 引擎里「监听器 + 过滤 + 文件流」的经典组合。
LogMessageLevel:四级消息
OgreLog.h 定义消息级别枚举,同时保留一个 deprecated 的 LoggingLevel:
// OgreMain/include/OgreLog.h:LogMessageLevel(v14.6.3 源码摘录,已删减)
/// @deprecated use LogMessageLevel instead
enum LoggingLevel
{
LL_LOW = 1,
LL_NORMAL = 2,
LL_BOREME = 3
};
/** The importance of a logged message.
*/
enum LogMessageLevel
{
LML_TRIVIAL = 1,
LML_NORMAL = 2,
LML_WARNING = 3,
LML_CRITICAL = 4
};
四级从 1 到 4:TRIVIAL(琐碎)→ NORMAL(普通)→ WARNING(警告)→ CRITICAL(致命)。数值越大越严重。LoggingLevel 是旧名,LL_BOREME(「无聊」)的命名也透出历史味道——新代码统一用 LogMessageLevel。
Log::logMessage:过滤 → 监听 → 分流 → 落盘
OgreLog.cpp 的 Log::logMessage 是整条链的实现,四级步骤:
// OgreMain/src/OgreLog.cpp:Log::logMessage(v14.6.3 源码摘录,已删减)
void Log::logMessage( const String& message, LogMessageLevel lml, bool maskDebug )
{
OGRE_LOCK_AUTO_MUTEX;
if (lml >= mLogLevel)
{
bool skipThisMessage = false;
for(auto & l : mListeners)
l->messageLogged( message, lml, maskDebug, mLogName, skipThisMessage);
if (!skipThisMessage)
{
if (mDebugOut && !maskDebug)
{
std::ostream& os = int(lml) >= int(LML_WARNING) ? std::cerr : std::cout;
if(mTermHasColours) {
if(lml == LML_WARNING)
os << YELLOW;
if(lml == LML_CRITICAL)
os << RED;
}
os << message;
if(mTermHasColours) {
os << RESET;
}
os << std::endl;
}
// Write time into log
if (!mSuppressFile)
{
if (mTimeStamp)
{
auto t = std::time(nullptr);
auto pTime = std::localtime(&t);
mLog << std::put_time(pTime, "%H:%M:%S: ");
}
mLog << message << std::endl;
// Flush stcmdream to ensure it is written (incase of a crash, we need log to be up to date)
mLog.flush();
}
}
}
}
拆开看:
- 过滤:
if (lml >= mLogLevel)——低于mLogLevel(构造函数默认LML_NORMAL,可用setMinLogLevel调整)的消息直接丢弃。 - 监听优先:遍历
mListeners,把skipThisMessage引用传进去;任一听监听器设为 true,整条消息不再输出(也不落盘)。 - 分流:
int(lml) >= int(LML_WARNING) ? std::cerr : std::cout——警告及以上走cerr,其余走cout;终端支持颜色时警告标黄、致命标红。 - 落盘:写时间戳前缀(
%H:%M:%S:)+ 消息 +std::endl,然后mLog.flush()——注释点明「万一崩溃,日志必须是最新的」。
关键语义:监听器先于一切输出,它甚至可以「吞掉」消息。这给了外部系统(比如把日志转发给 GUI/网络/调试工具)一个干净的钩子,而不必改动日志本体。
监听器接口:LogListener
OgreLog.h 里监听器是纯抽象类,注释里写明了 skipThisMessage 的用途:
// OgreMain/include/OgreLog.h:LogListener(v14.6.3 源码摘录,已删减)
/** @remarks Pure Abstract class, derive this class and register to the Log to listen to log messages */
class LogListener
{
public:
virtual ~LogListener() {}
virtual void messageLogged( const String& message, LogMessageLevel lml, bool maskDebug, const String &logName, bool& skipThisMessage ) = 0;
};
回调参数携带:消息文本、级别、是否屏蔽调试输出、日志名(多个日志可共用一个监听器来区分)、以及可写的 skipThisMessage。Log::addListener/removeListener 用 std::find 去重后增删。
源码定位
OgreMain/include/OgreLog.h:enum LogMessageLevel、class LogListener、class Log(mLogLevel/mListeners/addListener/setMinLogLevel)OgreMain/src/OgreLog.cpp:Log::logMessage(过滤 → 监听 → cerr/cout 分流 → 时间戳落盘 + flush)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现 Log 的级别过滤、输出分流与监听器拦截。它与 src/14-1-log-message.cpp 逐字节一致:
// file: src/14-1-log-message.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/14-1-log-message.cpp -o bin/14-1-log-message && ./bin/14-1-log-message
//
// 复现 Log 的消息级别过滤与输出:
// LogMessageLevel 枚举(LML_TRIVIAL/NORMAL/WARNING/CRITICAL,对应 OgreLog.h);
// logMessage 按 lml >= mLogLevel 过滤(对应 OgreLog.cpp);
// >= WARNING 走错误流(cerr),否则走标准输出(cout);
// LogListener 可在落盘前拦截(skipThisMessage)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <string>
#include <vector>
namespace ogre_repro {
// 对应 Ogre::LogMessageLevel
enum LogMessageLevel {
LML_TRIVIAL = 1,
LML_NORMAL = 2,
LML_WARNING = 3,
LML_CRITICAL = 4,
};
// 对应 Ogre::LogListener:可拦截消息
class LogListener {
public:
virtual void messageLogged(const std::string& message, LogMessageLevel lml, bool& skipThisMessage) = 0;
virtual ~LogListener() {}
};
// 对应 Ogre::Log 的最小版:级别过滤 + 监听 + 输出分流
class Log {
public:
Log(LogMessageLevel logLevel) : mLogLevel(logLevel) {}
// 对应 Log::logMessage:lml >= mLogLevel 才处理
void logMessage(const std::string& message, LogMessageLevel lml) {
if (lml < mLogLevel) return;
bool skipThisMessage = false;
for (auto* l : mListeners)
l->messageLogged(message, lml, skipThisMessage);
if (skipThisMessage) return;
// >= WARNING 走错误流(对应 std::cerr),否则标准输出
if (lml >= LML_WARNING)
errorOutput += message + "\n";
else
standardOutput += message + "\n";
fileOutput += message + "\n"; // 落盘
}
std::vector<LogListener*> mListeners;
LogMessageLevel mLogLevel;
std::string standardOutput; // stdout 方向
std::string errorOutput; // stderr 方向
std::string fileOutput; // 文件方向
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
Log log(LML_NORMAL); // mLogLevel = LML_NORMAL
// TRIVIAL 低于 mLogLevel → 被过滤
log.logMessage("tick", LML_TRIVIAL);
CHECK(log.fileOutput.empty());
// NORMAL 通过:标准输出 + 落盘
log.logMessage("frame 1", LML_NORMAL);
CHECK(log.fileOutput == "frame 1\n");
CHECK(log.standardOutput == "frame 1\n");
CHECK(log.errorOutput.empty());
// WARNING/CRITICAL 走错误流
log.logMessage("warn", LML_WARNING);
log.logMessage("fatal", LML_CRITICAL);
CHECK(log.errorOutput == "warn\nfatal\n");
CHECK(log.standardOutput == "frame 1\n");
// 监听器可拦截:设置 skipThisMessage
struct DropWarn : public LogListener {
void messageLogged(const std::string&, LogMessageLevel lml, bool& skipThisMessage) override {
if (lml == LML_WARNING) skipThisMessage = true;
}
} dropWarn;
log.mListeners.push_back(&dropWarn);
log.logMessage("ignored warn", LML_WARNING);
CHECK(log.errorOutput == "warn\nfatal\n"); // 未新增
return lab::report("14-1 日志与异常:日志管理器");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 7/7 通过。
小结
- 消息分四级
LML_TRIVIAL/NORMAL/WARNING/CRITICAL,mLogLevel是最小门槛。 Log::logMessage链:lml >= mLogLevel过滤 → 监听器优先(可skipThisMessage吞掉)→ WARNING 及以上走cerr其余走cout→ 时间戳 + 落盘 +flush()。LogListener是纯抽象类,回调可拿到日志名、级别并可写跳过标志。- flush 注释的潜台词:日志写进 OGRE 的崩溃现场依赖,必须逐条即时落盘。
阅读导航:上一节:13.3 分类分配与容器策略 · 下一节:14.2 异常体系 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。