Класс QLoggingCategory

Класс QLoggingCategory представляет категорию или «область» в инфраструктуре ведения логов. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются безопасными для потоков.

Типы Public

Public Функции

Статические Public члены

Макросы

Подробное описание

Класс QLoggingCategory представляет категорию, или 'область' в инфраструктуре ведения логов.

QLoggingCategory представляет определённую категорию ведения логов — идентифицируемую строкой — во время выполнения. Категорию можно настроить для включения или отключения ведения логов сообщений по типу сообщения. Можно проверить, включён ли тип сообщения с помощью методов isDebugEnabled(), isInfoEnabled(), isWarningEnabled() и isCriticalEnabled().

Все объекты предназначены для настройки общим реестром (см. также Настройка категорий). Разные объекты также могут представлять одну и ту же категорию. Поэтому не рекомендуется экспортировать объекты через граничные области модулей, непосредственно манипулировать объектами или наследоваться от QLoggingCategory.

Создание объектов категории

Макросы Q_DECLARE_LOGGING_CATEGORY() и Q_LOGGING_CATEGORY() удобно объявляют и создают объекты QLoggingCategory:

// in a header
Q_DECLARE_LOGGING_CATEGORY(driverUsb)

// in one source file
Q_LOGGING_CATEGORY(driverUsb, "driver.usb")

Примечание: Имена категорий — свободный текст. Однако для удобной настройки категорий с помощью Правил ведения логов имена должны соответствовать некоторым правилам:

• Используйте только буквы и цифры.
• Далее структурируйте категории в общие области, используя точки.
• Избегайте имён категорий debug, info, warning, и critical.
• Имена категорий, начинающиеся с qt, зарезервированы для модулей Qt.

Объекты QLoggingCategory, неявно определённые с помощью Q_LOGGING_CATEGORY(), создаются при первом использовании потокобезопасным способом.

Проверка конфигурации категории

QLoggingCategory предоставляет isDebugEnabled(), isInfoEnabled(), isWarningEnabled(), isCriticalEnabled(), а также isEnabled() для проверки того, должны ли сообщения заданного типа записываться в журнал.

Примечание: Макросы qCDebug(), qCWarning(), qCCritical() предотвращают оценку аргументов, если соответствующие типы сообщений не включены для категории, поэтому явная проверка не требуется:

    // usbEntries() will only be called if driverUsb category is enabled
    qCDebug(driverUsb) << "devices: " << usbEntries();

Настройка категории по умолчанию

Как конструктор QLoggingCategory, так и макрос Q_LOGGING_CATEGORY() принимают необязательный аргумент QtMsgType, который отключает все типы сообщений с меньшей степенью важности. То есть, категория, объявленная

Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)

будет записывать сообщения типа QtWarningMsg, QtCriticalMsg, QtFatalMsg, но пропустит сообщения типа QtDebugMsg и QtInfoMsg.

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

Настройка категорий

Значения по умолчанию для категорий можно переопределить, установив правила ведения журнала или подключив пользовательский фильтр.

Правила ведения журнала

Правила ведения журнала позволяют гибко включать или отключать ведение журнала для категорий. Правила задаются в текстовом формате, где каждая строка должна иметь формат

    <category>[.<type>] = true|false

<category> — это имя категории, возможно, с * в качестве символа подстановки в начале или конце (или в обоих позициях). Необязательный <type> должен быть равен debug, info, warning, или critical. Строки, не соответствующие этому формату, игнорируются.

Правила обрабатываются в текстовом порядке, от первой к последней. То есть, если два правила применимы к категории/типу, применяется правило, которое указано позже.

Правила можно задать через setFilterRules():

    QLoggingCategory::setFilterRules("*.debug=false\n"
                                     "driver.usb.debug=true");

Начиная с Qt 5.3, правила ведения журнала также автоматически загружаются из раздела [Rules] файла конфигурации ведения журнала. Такие файлы конфигурации ищутся в каталоге конфигурации QtProject или явно задаются в переменной среды QT_LOGGING_CONF.

    [Rules]
    *.debug=false
    driver.usb.debug=true

Начиная с Qt 5.3, правила ведения журнала также можно задать в переменной среды QT_LOGGING_RULES. А начиная с Qt 5.6, несколько правил можно разделить точкой с запятой.

    QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"

Правила, заданные с помощью setFilterRules(), имеют приоритет над правилами, указанными в каталоге конфигурации QtProject, и, в свою очередь, могут быть переопределены правилами из файла конфигурации, указанного через QT_LOGGING_CONF, и правилами, заданными через QT_LOGGING_RULES.

Порядок обработки:

• [QLibraryInfo::DataPath]/qtlogging.ini
• QtProject/qtlogging.ini
• setFilterRules()
• QT_LOGGING_CONF
• QT_LOGGING_RULES

Файл QtProject/qtlogging.ini ищется во всех каталогах, возвращаемых QStandardPaths::GenericConfigLocation, например:

• на macOS и iOS: ~/Library/Preferences
• на Unix: ~/.config, /etc/xdg
• на Windows: %LOCALAPPDATA%, %ProgramData%, QCoreApplication::applicationDirPath(), QCoreApplication::applicationDirPath() + "/data"

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

Установка пользовательского фильтра

В качестве альтернативы текстовым правилам на более низком уровне вы также можете реализовать пользовательский фильтр с помощью installFilter(). В этом случае все правила фильтрации игнорируются.

Вывод категории

Используйте заполнитель %{category} для вывода категории в обработчике сообщений по умолчанию:

    qSetMessagePattern("%{category} %{message}");

Документация по типу членов

typedef QLoggingCategory::CategoryFilter

Это псевдоним для указателя на функцию со следующим сигнатуром:

void myCategoryFilter(QLoggingCategory *);

Функцию с этим сигнатуром можно подключить с помощью installFilter().

Документация по функциям-членам

QLoggingCategory::QLoggingCategory(const char *category)

Создаёт объект QLoggingCategory с заданным именем категории category. Все типы сообщений для этой категории включены по умолчанию.

Если category равно 0, имя категории изменяется на "default".

Обратите внимание, что category должен оставаться валидным в течение всего времени жизни этого объекта.

QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel)

Создаёт объект QLoggingCategory с заданным именем категории category и включает все сообщения с типами, более тяжёлыми или равными enableForLevel.

Если category равно 0, имя категории изменяется на "default".

Обратите внимание, что category должен оставаться валидным в течение всего времени жизни этого объекта.

Эта функция была добавлена в Qt 5.4.

QLoggingCategory::~QLoggingCategory()

Уничтожает объект QLoggingCategory.

const char *QLoggingCategory::categoryName() const

Возвращает имя категории.

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

Возвращает указатель на глобальную категорию "default", которая используется, например, qDebug(), qInfo(), qWarning(), qCritical(), qFatal().

Примечание: Возвращаемый указатель может быть нулевым во время уничтожения статических объектов.

Примечание: Владение категорией не передаётся, не delete возвращаемый указатель.

[static] QLoggingCategory::CategoryFilter QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)

Устанавливает функцию filter, используемую для определения, какие категории и типы сообщений должны быть включены. Возвращает указатель на предыдущий установленный фильтр.

Каждый созданный объект QLoggingCategory передаётся фильтру, и фильтр свободен изменять соответствующую конфигурацию категории с помощью setEnabled().

Фильтр может вызываться из разных потоков, но никогда не одновременно. Фильтр не должен вызывать какие-либо статические функции класса QLoggingCategory.

Пример:

QLoggingCategory::CategoryFilter oldCategoryFilter;

void myCategoryFilter(QLoggingCategory *category)
{
    // configure driver.usb category here, otherwise forward to to default filter.
    if (qstrcmp(category->categoryName(), "driver.usb") == 0)
        category->setEnabled(QtDebugMsg, true);
    else
        oldCategoryFilter(category);
}

Альтернативный способ конфигурирования фильтра по умолчанию — через setFilterRules().

bool QLoggingCategory::isCriticalEnabled() const

Возвращает true, если сообщения критической важности должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макрос qCCritical() уже выполняет эту проверку перед выполнением любого кода. Однако вызов этого метода может быть полезен для предотвращения дорогостоящего генерации данных, которые используются только для отладки.

bool QLoggingCategory::isDebugEnabled() const

Возвращает true, если сообщения отладки должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макрос qCDebug() уже выполняет эту проверку перед выполнением любого кода. Однако вызов этого метода может быть полезен для предотвращения дорогостоящего генерации данных, которые используются только для отладки.

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

Возвращает true, если сообщение типа msgtype для категории должно отображаться. Возвращает false в противном случае.

bool QLoggingCategory::isInfoEnabled() const

Возвращает true, если информационные сообщения должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макрос qCInfo() уже выполняет эту проверку перед выполнением любого кода. Однако вызов этого метода может быть полезен для предотвращения дорогостоящего генерации данных, которые используются только для отладки.

Эта функция была введена в Qt 5.5.

bool QLoggingCategory::isWarningEnabled() const

Возвращает true, если предупреждающие сообщения должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макрос qCWarning() уже выполняет эту проверку перед выполнением любого кода. Однако вызов этого метода может быть полезен для предотвращения дорогостоящего генерации данных, которые используются только для отладки.

void QLoggingCategory::setEnabled(QtMsgType type, bool enable)

Изменяет тип сообщения type для категории на enable.

Этот метод предназначен для использования только изнутри фильтра, установленного с помощью installFilter(). См. Настройка категорий для общего обзора способов конфигурирования категорий глобально.

Примечание: QtFatalMsg изменить нельзя. Оно всегда останется true.

См. также isEnabled().

[static] void QLoggingCategory::setFilterRules(const QString &rules)

Настраивает категории и типы сообщений, которые должны быть включены, с помощью набора rules.

Пример:

    QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));

Примечание: Правила могут быть проигнорированы, если установлен пользовательский фильтр категории с помощью installFilter(), или если пользователь определил QT_LOGGING_CONF или QT_LOGGING_RULES переменную среды.

QLoggingCategory &QLoggingCategory::operator()()

Возвращает сам объект. Это позволяет использовать как переменную QLoggingCategory, так и метод-фабрику, возвращающий QLoggingCategory, в макросах qCDebug(), qCWarning(), qCCritical().

const QLoggingCategory &QLoggingCategory::operator()() const

Возвращает сам объект. Это позволяет использовать как переменную QLoggingCategory, так и метод фабрики, возвращающий QLoggingCategory, в макросах qCDebug(), qCWarning(), qCCritical().

    QLoggingCategory category("driver.usb");
    qCCritical(category) << "a critical message";

    QLoggingCategory category("driver.usb");
    qCCritical(category, "a critical message logged into category %s", category.categoryName());

    QLoggingCategory category("driver.usb");
    qCDebug(category) << "a debug message";

    QLoggingCategory category("driver.usb");
    qCDebug(category, "a debug message logged into category %s", category.categoryName());

    QLoggingCategory category("driver.usb");
    qCInfo(category) << "an informational message";

    QLoggingCategory category("driver.usb");
    qCInfo(category, "an informational message logged into category %s", category.categoryName());

    QLoggingCategory category("driver.usb");
    qCWarning(category) << "a warning message";

    QLoggingCategory category("driver.usb");
    qCWarning(category, "a warning message logged into category %s", category.categoryName());