Журналирование работы программ (trace.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/trace.h из состава KasperskyOS SDK.

API позволяет передавать сообщения о работе программ в систему журналирования, которая выводит диагностические данные, например, через UART или сохраняет в файл. Эти сообщения представляют собой форматированные строки, аналогичные тем, которые создаются функциями семейства printf. Можно регулировать уровень детализации и уровень журналирования. От уровня детализации зависит, какие макросы API раскроются в код для передачи сообщений в систему журналирования, а какие раскроются в фиктивный код. Чем выше уровень детализации, тем больше макросов API будет активировано, то есть раскрыто в код для передачи сообщений в систему журналирования. Уровень журналирования определяет максимальный уровень детализации, для которого выполняется журналирование. То есть сообщения, специфичные для более высоких уровней детализации, не передаются в систему журналирования. Например, если для библиотеки был установлен уровень детализации 5 (LOG_DEBUG), а для программы, включающей эту библиотеку, установлен уровень журналирования 4 (LOG_INFO), то сообщения от библиотеки, специфичные для уровня детализации 5 (соответствующие макросу DEBUG()), не будут передаваться в систему журналирования.

Сведения о макросах API приведены в таблице ниже.

Использование API

Разные макросы API предназначены для вывода разных сведений о работе программы. Макросы FATAL(), ERROR() и ERR() нужно использовать для вывода сообщений об ошибках. Макрос WARN() требуется применять, чтобы выводить сообщения о возникновении неблагоприятных условий, которые в дальнейшем могут привести к ошибкам. Для вывода информационных сообщений о штатной работе программы предусмотрен макрос INFO(). Вывод сообщений со сведениями для отладки программы является предназначением макроса DEBUG(). Макрос TRACE() должен использоваться, чтобы выводить сообщения со сведениями для детального отслеживания работы программы.

Каждый макрос принимает следующие данные:

• Условное имя компонента программы, который выводит сообщение.

  Это имя будет отображаться в заголовке сообщения.

• Строку форматирования (как для функций семейства printf).
• [Опционально] Последовательность параметров, значения которых нужно поместить в сообщение.

Примеры:

TRACE(BLKPART, "Port '%s' is opened.", name);

DEBUG(USBSTORAGE, "Failed to send a reset request.");

ERR(USB, "Can't find device class %s.", name);

WARN(

MOUNT,

"Failed to mount rootfs with type '%s' on '%s', error: %s(%d), will retry in %u msec",

fstab_mount.fsname,

fstab_mount.devname,

strerror(error),

error,

FSTAB_MOUNT_RETRY_DELAY_MS);

Чтобы установить уровень детализации, нужно определить макрос LOG_VERBOSITY. Это можно сделать в файле исходного кода либо в файле CMakeLists.txt.

Для определения макроса LOG_VERBOSITY нужно использовать следующие значения:

• LOG_OFF (уровень 0) деактивирует все макросы API.
• LOG_FATAL (уровень 1) активирует макрос FATAL().
• LOG_ERR (уровень 2) активирует макросы FATAL(), ERROR(), ERR().
• LOG_WARN (уровень 3) активирует макросы FATAL(), ERROR(), ERR(), WARN().
• LOG_INFO (уровень 4) активирует макросы FATAL(), ERROR(), ERR(), WARN(), INFO().
• LOG_DEBUG (уровень 5) активирует макросы FATAL(), ERROR(), ERR(), WARN(), INFO(), DEBUG().
• LOG_TRACE (уровень 6) активирует все макросы API.

Пример установки уровня детализации в файле исходного кода:

#define LOG_VERBOSITY LOG_DEBUG

#include <kos/trace.h>

В файле исходного кода директиву определения макроса LOG_VERBOSITY необходимо поместить перед директивой включения заголовочного файла trace.h. Также не рекомендуется включать заголовочный файл trace.h в другие заголовочные файлы, чтобы избежать транзитивного включения, которое может привести к неочевидному определению макроса LOG_VERBOSITY.

Чтобы определить макрос LOG_VERBOSITY в файле CMakeLists.txt, нужно использовать следующую CMake-команду:

target_compile_definitions(<имя цели сборки> PRIVATE LOG_VERBOSITY=<уровень детализации>)

Пример установки уровня детализации в файле CMakeLists.txt:

target_compile_definitions(client PRIVATE LOG_VERBOSITY=5)

По умолчанию для отладочной и выпускной версий программы установлены уровни детализации 5 (LOG_DEBUG) и 4 (LOG_INFO) соответственно.

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

Чтобы установить уровень журналирования, нужно задать переменную окружения INITIAL_LOG_LEVEL или определить глобальную переменную currentLogLevel типа int.

Для переменной окружения INITIAL_LOG_LEVEL нужно задать одно из следующих значений:

• CRITICAL (уровень 1);
• ERROR (уровень 2);
• WARNING (уровень 3);
• INFO (уровень 4);
• DEBUG (уровень 5);
• TRACE (уровень 6).

Пример установки уровня журналирования при упаковке в KPA-пакет с помощью переменной окружения в параметре RUN_CONFIGURATION->ENV CMake-команды add_kpa_component ():

add_kpa_component (${PACKAGE}

RUN_CONFIGURATION "default"

...

ENV "INITIAL_LOG_LEVEL=DEBUG")

Для инициализации переменной currentLogLevel нужно использовать те же значения, что и для определения макроса LOG_VERBOSITY, кроме LOG_OFF. Переменную currentLogLevel можно определить в любой единице трансляции из состава программы. В результате этого будет задан уровень журналирования для всей программы.

Пример установки уровня журналирования в файле исходного кода:

int currentLogLevel = LOG_DEBUG;

По умолчанию для отладочной и выпускной версий программы установлен уровень журналирования 4 (LOG_INFO).

Макрос LOG_FMT устанавливает, будут ли сообщения иметь заголовок. По умолчанию этот макрос имеет значение LOG_FMT_ON, что требует наличия у сообщений заголовка, который содержит следующие сведения:

• дату и время создания сообщения – [<год>-<месяц>-<число>T<часы>:<минуты>:<секунды>.<миллисекунды>];
• [только для уровня журналирования 6 (LOG_TRACE)] абсолютный путь к файлу исходного кода и номер строки, в которой находится макрос API, выполнивший передачу сообщения – [<абсолютный путь к файлу исходного кода>:<номер строки>];
• тип сообщения – [Fatal|Error|Warn|Info|Debug|Trace];
• имя процесса, который передал сообщение – [<имя процесса>];
• идентификатор процесса (PID) и идентификатор потока исполнения (TID), который передал сообщение – [<PID>:<TID>];
• условное имя компонента программы, который передал сообщение [<имя компонента программы>].

Примеры сообщений с заголовком:

[2025-04-16T12:54:34.191][Info][TestServer][5:5][SERVER] The server started.

[2025-04-16T13:56:12.310][/home/x/Documents/kos/kosdev/system/libs/em_transport/src/client.c:231][Trace][Einit][4:4][em_transport] EM transport successfully connected.

Чтобы убрать заголовок из сообщений, нужно определить макрос LOG_FMT значением символьной константы LOG_FMT_OFF. Как и в случае с макросом LOG_VERBOSITY, директиву определения макроса LOG_FMT необходимо поместить перед директивой включения заголовочного файла trace.h. Также можно определить макрос LOG_FMT нулевым значением, используя следующую CMake-команду:

target_compile_definitions(<имя цели сборки> PRIVATE LOG_FMT=0)

Сведения о макросах API

Макросы trace.h