《OGRE 3D 渲染引擎原理与架构》14.1 日志管理器

OGRE 的日志以 Log 类为核心:LogMessageLevel 四级(TRIVIAL/NORMAL/WARNING/CRITICAL),logMessage 按 lml >= mLogLevel 过滤,警告级走 cerr、其余走 cout,并落盘加 flush。LogListener 可在落盘前用 skipThisMessage 拦截。lab 用 C++ 复现级别过滤与输出分流。

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();
                }
            }
        }
    }

拆开看:

  1. 过滤:if (lml >= mLogLevel)——低于 mLogLevel(构造函数默认 LML_NORMAL,可用 setMinLogLevel 调整)的消息直接丢弃。
  2. 监听优先:遍历 mListeners,把 skipThisMessage 引用传进去;任一听监听器设为 true,整条消息不再输出(也不落盘)。
  3. 分流:int(lml) >= int(LML_WARNING) ? std::cerr : std::cout——警告及以上走 cerr,其余走 cout;终端支持颜色时警告标黄、致命标红。
  4. 落盘:写时间戳前缀(%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 去重后增删。

源码定位

上游引用固定到 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 异常体系 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图