Класс QLoggingCategory

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

Этот класс был представлен в Qt 5.2.

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

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

Типы public

Функции public

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

Макросы

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

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, QtMsgType enableForLevel)

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

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

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

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

QLoggingCategory::QLoggingCategory(const char *category)

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

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

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

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 logged into category %s", category.categoryName());

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

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

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

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

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

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

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