Qt5.14.2 揭秘Qt日志神器高效诊断程序潜在隐疾

对程序员而言，代码中的bug往往如同无影无踪的隐疾，影响着程序的健康运行。而及时有效的诊断手段则是治疗这些隐疾的良药。今天，我们将一窥Qt日志框架QLoggingCategory的神奇功效，探究它如何为你的Qt应用程序构筑坚实的诊断防火墙。

一、Qt日志框架简介

Qt内置了一个功能强大的日志框架，旨在帮助开发者高效诊断应用程序中潜在的问题。这套框架包含qDebug()、qInfo()、qWarning()和qCritical()等日志记录函数，以及QLoggingCategory等控制日志输出的工具类。

二、简单实践:qDebug输出

qDebug()无疑是最常用的日志输出函数，它会将日志信息输出到stderr标准错误流，从而统一输出到终端或者IDE集成工具的调试视图中。

qDebug() << "Hello Qt Log!";
qDebug() << "Value:" << 3.14;
QString str = "Debug Message";
qDebug() << str;

三、QLoggingCategory助力日志控制

借助QLoggingCategory，我们可以更细腻地控制不同日志信息的记录规则，甚至限制日志只输出在特定的平台或设备上。这对于分析复杂应用中的特定环节或组件情况极为有用。

// 1.定义日志类别
Q_LOGGINGCATEGORY(QT_EXAMPLE_MAIN， "qt.example.main")
Q_LOGGINGCATEGORY(QT_EXAMPLE_NETWORKING， "qt.example.networking"， QtInfoMsg)

// 2.根据类别名控制输出级别
QLoggingCategory::setFilterRules("qt.example.networking=true\nqt.example.main.debug=false");

// 3.在代码中使用
qCDebug(QT_EXAMPLE_MAIN) << "Main log"; 
qCInfo(QT_EXAMPLE_NETWORKING) << "Network log";

QLoggingCategory允许我们在运行时动态设置日志级别，从而控制哪些级别的日志可以被输出。设置日志级别的方式很简单，使用QLoggingCategory::setFilterRules函数即可。

QLoggingCategory定义了以下几个日志级别:

• QtDebugMsg - Debug级别
• QtInfoMsg - 信息级别
• QtWarningMsg - 警告级别
• QtCriticalMsg - 严重级别
• QtFatalMsg - 致命级别

我们可以为每个日志类别设置单独的日志级别，或者为所有类别设置统一的全局级别。

下面是一些示例:

1、设置单个类别的日志级别:

Q_LOGGINGCATEGORY(APP_MAIN， "app.main")

// 只输出APP_MAIN类别的WARNING及以上级别日志
QLoggingCategory::setFilterRules("app.main.warning=true");

qCDebug(APP_MAIN) << "Ignored debug"; 
qCWarning(APP_MAIN) << "Warning message"; //会输出

2、设置所有类别的全局日志级别:

// 所有类别只输出CRITICAL及以上级别日志
QLoggingCategory::setFilterRules("*.critical=true");

qCDebug(APP_MAIN) << "Ignored debug";
qCWarning(APP_MAIN) << "Ignored warning";
qCCritical(APP_MAIN) << "Critical error!"; //会输出

3、同时设置多个规则:

// APP_NETWORK类别只输出INFO及以上
// 其他类别只输出WARNING及以上
QLoggingCategory::setFilterRules("app.network.info=true\n*.warning=true");

可以看到，setFilterRules函数的参数是一个规则字符串，可以包含多条规则，以\n分隔。规则语法为:

<category>.debug|info|warning|critical|fatal=true|false

其中，category可以是具体的类别名或通配符*表示所有类别。等号后面指定是启用还是禁用该级别的日志输出。

我们也可以在程序启动时就设置好规则，比如通过命令行参数或配置文件传入。或者在运行过程中根据需求动态修改日志级别，实现灵活的日志控制。

此外，QtCreator还提供了一个非常方便的图形化界面来配置日志级别。在Analyzer->Logging->LoggingSettings中，我们可以可视化地启用禁用不同类别和级别的日志输出。

通过合理设置日志级别，我们可以在应用开发和调试的不同阶段，根据实际情况来控制输出精简的日志信息，提高诊断效率。

四、高级主题:详尽日志上下文

在实际开发中，我们往往需要获取更多辅助信息(如行号、函数名等)，以确定问题发生的上下文环境。Qt提供了qDebug捕获器(QDebugStateSaverX)来记录详细的语句执行位置信息。

void myFunction(int c) {
    QDebugStateSaver stateSaver;
    qDebug() << "Entering myFunction(" << c << ")";
    // Function code...
}

五、QLoggingCategory其他常见用法

QLoggingCategory除了我们上面提到的控制日志输出规则和级别的功能之外，还有以下一些常见的用法:

1、将日志输出重定向到文件
通过QLoggingCategory::installMessageHandler函数，可以自定义日志输出的处理回调函数，将日志信息重定向写入到文件中，而不是直接输出到控制台。这在某些场景下非常有用，比如在服务器环境中捕获程序运行日志。

下面我们通过一个完整的示例代码来说明具体的实现步骤:

#include <QCoreApplication>
#include <QLoggingCategory>
#include <QFile>
#include <QTextStream>

// 定义日志类别
Q_LOGGINGCATEGORY(LOG_CATEGORY， "example.log")

// 自定义消息处理函数
void customMessageHandler(QtMsgType type， const QMessageLogContext &context， const QString &msg)
{
    // 打开日志文件
    static QFile logFile("log.txt");
    if (!logFile.isOpen()) {
        logFile.open(QIODevice::WriteOnly | QIODevice::Append);
    }

    // 将日志写入文件
    QTextStream stream(&logFile);
    stream << qPrintable(QDateTime::currentDateTime().toString("yyyy-MM-dd hh:mm:ss.zzz "));
    switch (type) {
    case QtDebugMsg:
        stream << "Debug: ";
        break;
    case QtInfoMsg:
        stream << "Info: ";
        break;
    case QtWarningMsg:
        stream << "Warning: ";
        break;
    case QtCriticalMsg:
        stream << "Critical: ";
        break;
    case QtFatalMsg:
        stream << "Fatal: ";
        break;
    }
    stream << msg << " (" << context.file << ":" << context.line << "， " << context.function << ")" << endl;
}

int main(int argc， char *argv[])
{
    QCoreApplication a(argc， argv);

    // 安装自定义消息处理函数
    qInstallMessageHandler(customMessageHandler);

    // 使用日志类别输出日志
    qCDebug(LOG_CATEGORY) << "This is a debug message";
    qCInfo(LOG_CATEGORY) << "This is an info message";
    qCWarning(LOG_CATEGORY) << "This is a warning message";
    qCCritical(LOG_CATEGORY) << "This is a critical message";

    return a.exec();
}

这个示例中，我们首先定义了一个名为LOG_CATEGORY的日志类别。

然后实现了一个自定义的消息处理函数customMessageHandler。这个函数会在Qt输出日志时被调用，我们在函数内部打开了一个名为log.txt的文件，并将日志信息以特定的格式写入到文件中。

在main函数中，我们通过qInstallMessageHandler函数将自定义的customMessageHandler安装为Qt的全局消息处理程序。

接下来，我们就可以使用qCDebug、qCInfo等带类别的日志输出函数来输出日志了。由于我们已经安装了自定义的处理程序，所以这些日志信息会被重定向写入到log.txt文件中。

运行这个程序后，您可以查看log.txt文件的内容，里面会包含程序输出的各种级别的日志信息，格式类似于:

2023-05-18 14:36:52.131 Debug: This is a debug message (main.cpp:30， main)
2023-05-18 14:36:52.132 Info: This is an info message (main.cpp:31， main)
2023-05-18 14:36:52.132 Warning: This is a warning message (main.cpp:32， main)
2023-05-18 14:36:52.132 Critical: This is a critical message (main.cpp:33， main)

可以看到，每一条日志都包含了时间戳、日志级别、消息内容以及文件名、行号、函数名等上下文信息，方便我们分析和定位问题。

通过这种方式，我们就可以将Qt程序的日志信息持久化存储到文件中，不再依赖于控制台输出，从而方便了日志的收集和管理。您也可以根据实际需求，对这个自定义消息处理函数进行修改和扩展，比如增加日志文件的循环滚动等功能。

2、条件日志输出

通过 QtMsgType 参数，QLoggingCategory可以让你有条件地输出日志，比如只输出WARNING及以上级别的日志信息。这在生产环境中很有用，可以过滤掉一些不太重要的DEBUG级别的日志。

QLoggingCategory::setFilterRules("qt.example.main.info=false");
qCDebug(QT_EXAMPLE_MAIN) << "Too verbose"; //不会输出
qCWarning(QT_EXAMPLE_MAIN) << "Important warning"; //会输出

总之，在开发Qt应用的过程中，我们需要时刻保持对代码"内疾外馁"的警惕，及时发现并排查问题。QLoggingCategory这一强大的日志框架将是你的得力助手，指引你走出调试困境，让应用程序运转更加健康稳定。