Класс QLoggingCategory

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

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

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

Типы

Общедоступные функции

Статические общедоступные члены

Макросы

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

Класс 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(). Начиная с Qt 5.3, правила регистрации также можно установить в переменной окружения QT_LOGGING_RULES, и они автоматически загружаются из раздела [Rules] файла конфигурации регистрации. Такие файлы конфигурации ищутся в каталоге конфигурации QtProject или явно задаются в переменной окружения QT_LOGGING_CONF.

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

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

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

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

Порядок оценки:

• [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".

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

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

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

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

QLoggingCategory::~QLoggingCategory()

Удаляет объект QLoggingCategory.

const char *QLoggingCategory::categoryName() const

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

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

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

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

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

[static] CategoryFilter QLoggingCategory::installFilter(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());