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

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

API позволяет журналировать работу программ, помещая сообщения о происходящих событиях в диагностический вывод. Эти сообщения представляют собой форматированные строки, аналогичные тем, которые создаются функциями семейства printf. Диагностический вывод осуществляется, например, через порт COM или USB (версии 3.0 или более поздней, с поддержкой DbC) в зависимости от конфигурации ядра KasperskyOS. Перед сборкой программы можно установить уровень журналирования, от которого зависит, какие макросы API раскроются в код для выполнения журналирования, а какие раскроются в фиктивный код. Чем выше уровень журналирования, тем больше макросов API будет активировано, то есть раскрыто в код для выполнения журналирования.

Сведения о макросах 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);

Разные уровни журналирования активируют разные наборы макросов API:

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.

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

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

#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)

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

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

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

дату и время создания сообщения – [<год>-<месяц>-<число>T<часы>:<минуты>:<секунды>.<миллисекунды>];
[только для уровня журналирования LOG_TRACE (уровня 6)] абсолютный путь к файлу исходного кода и номер строки, в которой указан макрос 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 succesfully 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

Макрос	Сведения о макросе
`TRACE()`	Назначение Помещает в диагностический вывод сообщение со сведениями для детального отслеживания работы программы. Параметры [in] `name` – имя компонента программы. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in,optional] `...` – последовательность параметров, значения которых нужно поместить в сообщение. Значения макроса Нет.
`DEBUG()`	Назначение Помещает в диагностический вывод сообщение со сведениями для отладки программы. Параметры [in] `name` – имя компонента программы. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in,optional] `...` – последовательность параметров, значения которых нужно поместить в сообщение. Значения макроса Нет.
`INFO()`	Назначение Помещает в диагностический вывод информационное сообщение о штатной работе программы. Параметры [in] `name` – имя компонента программы. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in,optional] `...` – последовательность параметров, значения которых нужно поместить в сообщение. Значения макроса Нет.
`WARN()`	Назначение Помещает в диагностический вывод сообщение о возникновении неблагоприятных условий, которые в дальнейшем могут привести к ошибкам. Параметры [in] `name` – имя компонента программы. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in,optional] `...` – последовательность параметров, значения которых нужно поместить в сообщение. Значения макроса Нет.
`ERR()`	Назначение Помещает в диагностический вывод сообщение об ошибке, которая нарушает работу программы, но не приводит к необходимости аварийно завершать программу. Параметры [in] `...` – последовательность параметров, в которой первым параметром является имя компонента программы, вторым параметром является указатель на строку форматирования (как для функций семейства `printf`), остальные опциональные параметры содержат значения, которые нужно поместить в сообщение. Значения макроса Нет.
`ERROR()`	Назначение Помещает в диагностический вывод сообщение об ошибке, которая нарушает работу программы, но не приводит к необходимости аварийно завершать программу. Параметры [in] `name` – имя компонента программы. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in,optional] `...` – последовательность параметров, значения которых нужно поместить в сообщение. Значения макроса Нет.
`FATAL()`	Назначение Помещает в диагностический вывод сообщение об ошибке, которая приводит к необходимости аварийно завершать программу. Параметры [in] `name` – имя компонента программы. [in] `fmt` – указатель на строку форматирования (как для функций семейства `printf`). [in,optional] `...` – последовательность параметров, значения которых нужно поместить в сообщение. Значения макроса Нет.

В начало