AI Под капотом qDebug(): как устроено логирование в Qt и что с этим можно сделать

[AI]

Как должно выглядеть логирование в Qt

Каждый Qt-разработчик начинает знакомство с фреймворком с магической строчки qDebug() << "Hello World". Но задумывались ли вы, что происходит внутри этого вызова? Как Qt обрабатывает логи, какие есть ограничения, и главное — как это можно расширить под свои нужды?

В этой статье я разберу внутреннее устройство системы логирования Qt, покажу её сильные и слабые стороны, а затем представлю свою библиотеку QtLogger — надстройку, которая превращает базовый механизм в полноценную систему логирования корпоративного уровня.

Если вам не интересно вникать во внутренности qDebug(), но интересно узнать как решить его проблемы, то сразу переходите к разделу QtLogger — расширяем возможности.

Как работает логирование в Qt


В Qt есть пять макросов для логирования: qDebug(), qInfo(), qWarning(), qCritical() и qFatal(). Все они определены в <QtGlobal> и возвращают временный объект QDebug. Вот как выглядит определение qDebug() в исходниках Qt:

#define qDebug QMessageLogger(QT_MESSAGELOG_FILE, QT_MESSAGELOG_LINE, \
QT_MESSAGELOG_FUNC).debug

Макросы __FILE__, __LINE__ и __func__ захватывают информацию о месте вызова. QMessageLogger создаёт контекст сообщения и передаёт его дальше, а метод debug() возвращает объект QDebug, который и делает всю работу.

Когда вы пишете qDebug() << "text", происходит следующее: создаётся QMessageLogger с информацией о файле и строке, он возвращает объект QDebug, тот накапливает данные через перегруженные операторы <<, и наконец в деструкторе отправляет всё в глобальный message handler.

QDebug — это по сути обёртка над QTextStream, которая накапливает данные во внутренний буфер. Вот упрощённая структура:

class QDebug {
public:
QDebug(QtMsgType type, const QMessageLogContext &context)
: stream(new Stream(type, context))
{}

// Копирующий конструктор увеличивает счётчик ссылок
QDebug(const QDebug &other) : stream(other.stream) {
++stream->ref;
}

// Деструктор — ключевой момент!
~QDebug() {
if (--stream->ref == 0) {
qt_message_output(stream->type, stream->context, stream->buffer);
delete stream;
}
}

// Операторы возвращают ссылку на себя — это позволяет строить цепочки
QDebug &operator<<(const QString &s) {
stream->ts << s;
return *this;
}

private:
struct Stream {
QAtomicInt ref = 1;
QTextStream ts;
QString buffer;
QtMsgType type;
QMessageLogContext context;
};
Stream *stream;
};

Ключевой момент — оператор << возвращает ссылку QDebug&, а не новый объект. Благодаря этому работает цепочка вызовов:

qDebug() << "User:" << userName << "Age:" << age;

// Раскрывается в:
QDebug temp = qDebug(); // ref = 1, buffer = ""
temp << "User:"; // buffer = "User:"
temp << userName; // buffer = "User: John"
temp << "Age:"; // buffer = "User: John Age:"
temp << age; // buffer = "User: John Age: 25"
// Конец выражения — деструктор отправляет сообщение в handler

Qt определяет операторы для множества типов — примитивных (bool, int, double), Qt-классов (QString, QByteArray, QDateTime) и даже контейнеров через шаблоны. По умолчанию QDebug добавляет пробелы между элементами и кавычки вокруг строк. Это можно отключить через nospace() и noquote().

Каждое сообщение сопровождается структурой QMessageLogContext:

struct QMessageLogContext {
const char *file; // Имя файла
int line; // Номер строки
const char *function; // Имя функции
const char *category; // Категория логирования
};

Обратите внимание: file, function и category — это const char*, а не QString. Это осознанное решение для производительности. Строковые литералы вроде __FILE__ хранятся в секции .rodata исполняемого файла и существуют всё время работы программы. При копировании const char* копируется только указатель (8 байт), тогда как для QString потребовалась бы аллокация в куче и конвертация из UTF-8 в UTF-16. При тысячах сообщений в секунду разница критична.

А вот message передаётся как QString, потому что формируется динамически через operator<< и может содержать что угодно.

Важный нюанс: в release-сборках file, line и function могут быть пустыми — Qt отключает их для оптимизации. Чтобы включить, нужно определить QT_MESSAGELOGCONTEXT до включения заголовков.

Из-за const char* возникает сложность: если нужно сохранить контекст (например, для асинхронного логирования), указатели могут стать невалидными. Как я решаю это в QtLogger — расскажу ниже.

Message Handler и форматирование


Ключевой механизм расширения — функция qInstallMessageHandler():

typedef void (*QtMessageHandler)(QtMsgType, const QMessageLogContext &, const QString &);
QtMessageHandler qInstallMessageHandler(QtMessageHandler handler);

По умолчанию Qt выводит сообщения в stderr (или в logcat на Android, os_log на macOS/iOS). Вы можете установить свой handler:

void myMessageHandler(QtMsgType type, const QMessageLogContext &context,
const QString &msg)
{
fprintf(stderr, "[%s] %s\n", context.category, msg.toLocal8Bit().constData());
}

int main(int argc, char *argv[])
{
qInstallMessageHandler(myMessageHandler);
// ...
}

Qt поддерживает настройку формата через переменную окружения QT_MESSAGE_PATTERN или функцию qSetMessagePattern(). Доступны плейсхолдеры: %{message}, %{type}, %{file}, %{line}, %{function}, %{category}, %{time}, %{threadid} и условные блоки %{if-debug}...%{endif}.

Начиная с Qt 5.2 появилась система категорий:

Q_LOGGING_CATEGORY(lcNetwork, "app.network")

qCDebug(lcNetwork) << "Connecting to server";

Фильтрация настраивается через QT_LOGGING_RULES или QLoggingCategory::setFilterRules(). Чуть ниже расскажу об этом подробнее.

Механизм отключения логирования


Qt предоставляет несколько способов отключить логирование — на этапе компиляции и во время выполнения.

Компиляционные макросы — самый радикальный способ. Если определить QT_NO_DEBUG_OUTPUT до включения заголовков Qt, макрос qDebug() превращается в заглушку:

#define QT_NO_DEBUG_OUTPUT
#include <QDebug>

qDebug() << expensiveFunction(); // Не компилируется вообще!

В исходниках Qt это реализовано примерно так:

#ifdef QT_NO_DEBUG_OUTPUT
#define qDebug QT_NO_QDEBUG_MACRO
#define QT_NO_QDEBUG_MACRO while (false) QMessageLogger().noDebug
#endif

Конструкция while (false) гарантирует, что код после qDebug() никогда не выполнится, а компилятор полностью удалит его как dead code. Аналогично работают QT_NO_INFO_OUTPUT и QT_NO_WARNING_OUTPUT.

Runtime-фильтрация через QLoggingCategory — более гибкий подход. Каждая категория хранит флаги для каждого уровня логирования:

class QLoggingCategory {
// ...
bool isDebugEnabled() const { return m_debugEnabled; }
bool isInfoEnabled() const { return m_infoEnabled; }
bool isWarningEnabled() const { return m_warningEnabled; }
bool isCriticalEnabled() const { return m_criticalEnabled; }
private:
bool m_debugEnabled;
bool m_infoEnabled;
// ...
};

Когда вы вызываете qCDebug(lcNetwork), макрос сначала проверяет lcNetwork().isDebugEnabled(). Если категория отключена, создание QDebug и форматирование пропускаются:

#define qCDebug(category, ...) \
for (bool qt_category_enabled = category().isDebugEnabled(); qt_category_enabled; qt_category_enabled = false) \
QMessageLogger(...).debug(category, __VA_ARGS__)

Хитрость с for вместо if — это приём для избежания проблем с else в макросах. Если isDebugEnabled() возвращает false, тело цикла не выполняется вообще.

Правила фильтрации задаются через переменную окружения QT_LOGGING_RULES или программно:

// Отключить debug для всех категорий, начинающихся с "app."
QLoggingCategory::setFilterRules("app.*.debug=false");

// Или через переменную окружения:
// export QT_LOGGING_RULES="app.*.debug=false;network.*=true"

Формат правил: <категория>[.<тип>]=<true|false>, где тип — это debug, info, warning или critical. Поддерживаются wildcard-паттерны (*). Правила применяются по порядку, последнее совпадение выигрывает.

Важный момент: для категорий проверка isDebugEnabled() происходит до форматирования сообщения. А вот для обычного qDebug() (без категории) runtime-отключения нет — сообщение всегда форматируется и передаётся в handler. Поэтому для production-кода рекомендуется использовать категории.

Нюансы производительности и ограничения


Есть несколько моментов, о которых стоит знать. Во-первых, каждый qDebug() << ... создаёт временные QString с аллокациями и конкатенациями — в горячих участках кода это заметно.

Во-вторых, хотя для категорий проверка isDebugEnabled() происходит до создания QDebug, аргументы операторов << вычисляются в любом случае:

qCDebug(lcNetwork) << expensiveToString(data); // expensiveToString() вызовется!

Это особенность C++: аргументы функции вычисляются до её вызова. Для оптимизации нужно явно проверять категорию: if (lcNetwork().isDebugEnabled()) { ... }.

В-третьих, стандартный handler использует mutex для потокобезопасности. При интенсивном логировании из нескольких потоков это становится узким местом. И в-четвёртых, запись происходит синхронно — медленный диск может заблокировать ваше приложение.

Главные ограничения встроенной системы:

• 
  Только один handler — нельзя отправить логи одновременно в файл, консоль и по сети
  
  
• 
  Нет ротации файлов — приходится писать самому или использовать внешние инструменты
  
  
• 
  Нет асинхронной записи — логирование блокирует вызывающий поток
  
  
• 
  Нет фильтрации по содержимому — только по категориям и уровням
  
  
• 
  Нет подавления дубликатов — одинаковые сообщения будут повторяться
  
  
• 
  Нет сжатия старых логов — управление дисковым пространством на вас
  

QtLogger — расширяем возможности


Столкнувшись с этими ограничениями в реальных проектах, я создал QtLogger — библиотеку, которая использует тот же механизм qInstallMessageHandler(), но предоставляет полноценную систему логирования с пайплайнами, фильтрами, форматтерами и множественными выходами.

Главный принцип — zero code changes. QtLogger работает с существующими qDebug(), qInfo(), qWarning(). Вам не нужно переписывать код или учить новый API:

#include "qtlogger.h"

int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);

gQtLogger.configure(); // Одна строка — и всё работает!

qDebug() << "It just works!";

return app.exec();
}

Архитектура


В основе лежит концепция пайплайна — цепочки обработчиков, через которую проходит каждое сообщение:

Все обработчики наследуются от Handler и реализуют метод process(LogMessage &lmsg), который возвращает true (продолжить) или false (прервать цепочку).

AttrHandler добавляет атрибуты к сообщению — например, порядковый номер или информацию о хосте. Filter решает, пропустить сообщение или нет — по уровню, категории, регулярному выражению или для подавления дубликатов. Formatter преобразует сообщение в строку — по шаблону, в JSON или в красивый цветной формат для консоли. Sink отправляет результат в точку назначения — консоль, файл, HTTP-endpoint, syslog, Android logcat или macOS os_log.

В отличие от стандартного QMessageLogContext, класс LogMessage содержит расширенную информацию:

class LogMessage {
public:
// Стандартные поля уже присутствующие в Qt
QtMsgType type() const;
QMessageLogContext context() const;
QString message() const;

// Дополнительные поля вводимые библиоткеой QtLogger
QDateTime time() const; // Время создания
quint64 threadId() const; // ID потока

QString formattedMessage() const;
void setFormattedMessage(const QString &);

// Пользовательские атрибуты
QVariant attribute(const QString &name) const;
void setAttribute(const QString &name, const QVariant &value);

private:
const QDateTime m_time = QDateTime::currentDateTime();
const quintptr m_qthreadptr =
reinterpret_cast<quintptr>(QThread::currentThreadId());
};


Время и ID потока захватыва��тся в момент создания, а не записи — это важно для асинхронного логирования.

Помните проблему с const char* указателями? В LogMessage я решаю её копированием строк в QByteArray:

class LogMessage {
const QByteArray m_file;
const QByteArray m_function;
const QByteArray m_category;
const QMessageLogContext m_context;

public:
LogMessage(const LogMessage &other)
: m_file(other.m_context.file),
m_function(other.m_context.function),
m_category(other.m_context.category),
m_context(m_file.constData(),
other.m_context.line,
m_function.constData(),
m_category.constData())
{}
};


Каждая копия владеет своими строками, и указатели всегда валидны.

Конфигурация


QtLogger использует Fluent API для конфигурации:

gQtLogger
.moveToOwnThread() // Асинхронное логирование
.addSeqNumber() // Добавить номер сообщения
.pipeline()
.filterLevel(QtWarningMsg) // Только warnings и выше
.filterDuplicate() // Подавлять дубликаты
.formatPretty(true) // Красивый формат в цвете
.sendToStdErr() // В консоль
.end()
.pipeline()
.format("%{time} [%{category}] %{type}: %{message}")
.sendToFile("app.log", 1024*1024, 5, // Храним до 5 файлов по 1 Мб
RotatingFileSink::Compression) // И старые файлы архивируем
.end();


Каждый пайплайн независим — сообщение, отфильтрованное в одном, всё равно попадёт в другие.

Асинхронность


По умолчанию логирование синхронное и защищено мьютексом. При вызове moveToOwnThread() создаётся фоновый поток:

template<typename BaseHandler>
class OwnThreadHandler : public BaseHandler {
public:
OwnThreadHandler &moveToOwnThread() {
m_thread = new QThread();
m_worker = new Worker(this);
m_worker->moveToThread(m_thread);
m_thread->start();
return *this;
}

bool process(LogMessage &lmsg) override {
if (m_worker) {
QCoreApplication::postEvent(m_worker, new LogEvent(lmsg));
} else {
BaseHandler::process(lmsg);
}
return true;
}
};


Сообщения передаются через postEvent() как QEvent. Worker в фоновом потоке обрабатывает их последовательно. При завершении приложения ждём обработки всех накопленных сообщений.

Форматирование


PatternFormatter парсит шаблон в набор токенов при создании, а затем эффективно собирает строку. Каждый токен умеет оценивать свою длину, что позволяет зарезервировать память один раз:

QString format(const LogMessage &lmsg) {
size_t estimatedLength = 0;
for (const auto &token : m_tokens) {
estimatedLength += token->estimatedLength();
}

QString result;
result.reserve(estimatedLength); // Одна аллокация!

for (const auto &token : m_tokens) {
token->appendToString(lmsg, result);
}
return result;
}


Поддерживаемые плейсхолдеры: %{message}, %{type}, %{line}, %{file}, %{function}, %{category}, %{time}, %{time yyyy-MM-dd}, %{time process} (время от старта), %{threadid}, %{shortfile}, %{func} (сокращённые версии), %{if-debug}...%{endif}, %{attr_name} (пользовательские атрибуты), спецификаторы формата %{category:>20} для выравнивания.

PrettyFormatter — специализированный форматтер для консоли с ANSI-цветами, сжатым представлением потоков (T0, T1, T2 вместо длинных ID) и автоматическим выравниванием категорий.

Ротация логов


RotatingFileSink поддерживает ротацию по размеру, ежедневную ротацию, ротацию при старте и gzip-сжатие старых файлов:

void rotate() {
file()->close();

const auto rotatedFileName = generateRotatedFileName(rotationDate, nextIndex);
QFile::rename(currentFileName, rotatedFileName);

if (m_compression) {
compressFile(rotatedFileName);
}

removeOldFiles();
file()->open(QIODevice::WriteOnly | QIODevice::Append);
}

Фильтры и выходы


Фильтры: filterLevel(QtWarningMsg) — по уровню, filterCategory("app.network.debug=false") — по категориям, filter("^(?!.*password.*$") — по регулярному выражению, filterDuplicate() — подавление дубликатов.

Выходы: StdOutSink/StdErrSink — консоль с цветами, FileSink/RotatingFileSink — файлы, HttpSink — HTTP-endpoint для Seq/Logstash/Loki, SyslogSink — syslog, SdJournalSink — systemd journal, AndroidLogSink — logcat, OsLogSink — macOS/iOS os_log, WinDebugSink — Windows debugger, SignalSink — Qt-сигнал для GUI.

Можно сконфигурировать из INI-файла:

[logger]
filter_rules = "*.debug=false"
message_pattern = "%{time} [%{category}] %{type}: %{message}"
path = "app.log"
max_file_size = 1048576
max_file_count = 5
rotate_on_startup = true
compress_old_files = true
async = true


gQtLogger.configureFromIniFile("config.ini");


QtLogger можно использовать как header-only (просто скопируйте qtlogger.h), CMake-библиотеку или через qmake.

Почему вам стоит использовать QtLogger в своих проектах?


Zero code changes — работает с существующими qDebug(), не нужно переписывать код. Гибкая архитектура — пайплайны позволяют направить разные сообщения в разные места. Асинхронность — логирование не блокирует основной поток. Ротация и сжатие — встроенная ротация с gzip, не нужен logrotate. Кроссплатформенность — Linux, Windows, macOS, iOS, Android с платформо-специфичными выходами. Широкая поддержка — Qt 5.9 — Qt 6.10. Подавление дубликатов и regex-фильтрация — защита от спама и sensitive data. JSON-формат — готовый вывод для ELK, Seq, Loki. Fluent API — читаемая конфигурация.

Заключение


Система логирования Qt — мощный, но базовый инструмент. Для production-приложений часто не хватает множественных выходов, асинхронности, ротации файлов и гибкой фильтрации. QtLogger решает эти проблемы, оставаясь полностью совместимым с существующим кодом.

Проект распространяется под лицензией MIT и доступен на GitHub: github.com/yamixst/qtlogger

P.S. Если вы используете Qt и вам не хватает возможностей стандартного логирования — попробуйте QtLogger. Интеграция занимает одну строку. Буду рад звёздочкам на GitHub и pull request'ам!

Полезные ссылки:

• 
  Документация Qt по логированию
  
  
• 
  QLoggingCategory
  
  
• 
  Исходники Qt (qlogging.cpp)
  

Буду рад вопросам и предложениям в комментариях!