The API is defined in the header file sysroot-*-kos/include/kos/trace.h from the KasperskyOS SDK.
The API lets you log the operation of programs while putting messages about events into diagnostic output. These messages are formatted strings similar to those that are created by functions of the printf family. For example, diagnostic output is sent via the COM port or USB port (version 3.0 or later, with DbC support) depending on the configuration of the KasperskyOS kernel. Prior to building the program, you can set the log level that will determine which API macros are expanded into the code for logging and which are expanded into fictitious code. The higher the log level, the more API macros will be activated, meaning they will be expanded into code for logging.
Information about API macros is provided in the table below.
Using the API
Various macros of the API are intended for output of various data on program operation. The FATAL(), ERROR(), and ERR() macros must be used for output of error messages. The WARN() macro must be used for output of messages about unfavorable conditions that may subsequently lead to errors. The INFO() macro is provided for output of informational messages about normal operation of the program. The DEBUG() macro is intended for output of messages containing information for program debugging. The TRACE() macro must be used for output of messages containing information for detailed tracking of program operation.
Each macro accepts the following data:
This name will be displayed in the message header.
printf family).Examples:
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);
Various log levels activate different sets of API macros:
LOG_OFF (level 0) deactivates all macros of the API.LOG_FATAL (level 1) activates the FATAL() macro.LOG_ERR (level 2) activates the FATAL(), ERROR(), and ERR() macros.LOG_WARN (level 3) activates the FATAL(), ERROR(), ERR(), and WARN() macros.LOG_INFO (level 4) activates the FATAL(), ERROR(), ERR(), WARN(), and INFO() macros.LOG_DEBUG (level 5) activates the FATAL(), ERROR(), ERR(), WARN(), INFO(), and DEBUG() macros.LOG_TRACE (level 6) activates all macros of the API.To set the log level, you must define the LOG_VERBOSITY macro. This can be done in the source code file or in the CMakeLists.txt file.
Example of setting the log level in the source code file:
#define LOG_VERBOSITY LOG_DEBUG
#include <kos/trace.h>
In the source code file, you must position the directive for defining the LOG_VERBOSITY macro before the directive for including the header file trace.h. It is also advisable to refrain from including the header file trace.h in other header files to prevent transitive inclusion, which could lead to an obscure definition of the LOG_VERBOSITY macro.
To define the LOG_VERBOSITY macro in the CMakeLists.txt file, you must use the following CMake command:
target_compile_definitions(<build target name> PRIVATE LOG_VERBOSITY=<log level>)
Example of setting the log level in the CMakeLists.txt file:
target_compile_definitions(client PRIVATE LOG_VERBOSITY=5)
By default, the log levels LOG_DEBUG (level 5) and LOG_INFO (level 4) are used for the debug version and the release version of the program, respectively.
The program build process verifies that the formatting string is compliant with the types of parameters whose values must be put into the message. This verification is performed only for activated macros of the API. Therefore, to verify all of the API macros that are used in the program source code, you must set the maximum possible log level for this program.
The LOG_FMT macro defines whether messages will have a header. By default, this macro has the value LOG_FMT_ON, which requires that messages have a header containing the following data:
[<year>-<month>-<day>T<hours>:<minutes>:<seconds>.<milliseconds>].LOG_TRACE (level 6)] Absolute path of the source code file and the number of the string that specifies the API macro that printed the message output – [<absolute path to source code file>:<string number>].[Fatal|Error|Warn|Info|Debug|Trace].[<process name>].[<PID>:<TID>].[<program component name>].Examples of messages containing a header:
[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.
To remove the header from messages, you must define the LOG_FMT macro with the LOG_FMT_OFF symbolic constant value. Just like with the LOG_VERBOSITY macro, you must position the directive for defining the LOG_FMT macro before the directive for including the header file trace.h. You can also define the LOG_FMT macro as a null value by using the following CMake command:
target_compile_definitions(<build target name> PRIVATE LOG_FMT=0)
Information about API macros
trace.h macros
Macro |
Macro details |
|---|---|
|
Purpose Puts a message containing information for detailed tracking of program operation into diagnostic output. Parameters
Macro values N/A |
|
Purpose Puts a message containing program debug information into diagnostic output. Parameters
Macro values N/A |
|
Purpose Puts an information message about normal operation of the program into diagnostic output. Parameters
Macro values N/A |
|
Purpose Puts a message about unfavorable conditions that may subsequently lead to errors into diagnostic output. Parameters
Macro values N/A |
|
Purpose Puts a message about an error that disrupts program operation but will not lead to abnormal termination of the program into diagnostic output. Parameters
Macro values N/A |
|
Purpose Puts a message about an error that disrupts program operation but will not lead to abnormal termination of the program into diagnostic output. Parameters
Macro values N/A |
|
Purpose Puts a message about an error that will lead to abnormal termination of the program into diagnostic output. Parameters
Macro values N/A |