Logging

Use the Kanzi logging system to print messages to the Log window, the Kanzi debug console, standard output, and the system log on your target device. For example, use logging to find problems in your Kanzi application, and to inform the user about the status of your application.

You can:

• Print log messages using the Kanzi logging macros. See Printing log messages.
• Use log levels to show log messages based on their severity. See Setting the log level.
• Use log categories to group log messages that contain information related to specific functionality. See Using log categories.
• Redirect all Kanzi log messages using a custom logger. See Creating a custom logger.

Printing log messages

Use the Kanzi logging macros to print messages to the log. Most of the logging macros use a fixed log level to indicate the severity of the information in the message. See Setting the log level.

Kanzi has these logging macros:

To print log messages:

1. In your application code, use a logging macro where you want to print a log message.
   For example:
   • Debug macro:

     // Print "This is a debug message.".
     kzLogDebug(("This is a debug message."));

     Prints to the log:

     info:debug> This is a debug message.

   • Error macro:

     // Print "This is an error message." using the log category MY_LOG_CATEGORY.
     // Use log categories to group your log messages based on the functionality to which they are related. See Using log categories.
     kzLogError(MY_LOG_CATEGORY, ("This is an error message."));

     Prints to the log the path to the file, the line number where the error originated, and the error message:

     error:My category:c:\kanziworkspace\projects\myproject\application\src\myproject.cpp:196> This is an error message.

   • Info macro:

     // Print "1 plus 2 equals 3." using the log category MY_LOG_CATEGORY. See Using log categories.
     kzLogInfo(MY_LOG_CATEGORY, ("{} plus {} equals {}.", 1, 2, 1+2));
     int length = 100;
     // Print "The length is 100.".
     kzLogInfo(MY_LOG_CATEGORY, ("The length is {}.", length));

     Prints to the log:

     info:My category> 1 plus 2 equals 3.
     info:My category> The length is 100.

2. Build and run your application. See Deploying Kanzi applications.
   For example, on Windows build your application in Visual Studio using the GL_vs2015_Debug build configuration. When you run the application and reach in the code the point where you call the logging macro, Kanzi prints the message to the debug console.

Setting the log level

Use log levels to show log messages based on their severity. For example, to log critical issues during application execution, use the error log level (KZ_LOG_LEVEL_ERROR).

The Kanzi logging system has these log levels:

These log levels are enabled by default:

• KZ_LOG_LEVEL_ERROR
• KZ_LOG_LEVEL_WARNING
• KZ_LOG_LEVEL_INFO

To set the log level, use the KZ_LOG_LEVEL_ENABLED_THRESHOLD macro.
For example, to set a log level that enables all log levels:

#define KZ_LOG_LEVEL_ENABLED_THRESHOLD KZ_LOG_LEVEL_TRACE

You can create you own log levels. See KZ_LOG_CREATE_LEVEL.

Using log categories

Use log categories to group log messages that contain information related to specific functionality.

The Kanzi logging system has these default log categories:

To create and use a log category:

1. Create a log category with the KZ_LOG_CREATE_CATEGORY macro:

   // Create a log category named "My category" and set the state of the category to enabled.
   // The Kanzi logging system uses category state to filter log messages.
   // To disable a log category, use KZ_LOG_DISABLED_CATEGORY.
   #define MY_LOG_CATEGORY    KZ_LOG_CREATE_CATEGORY(KZ_LOG_ENABLED_CATEGORY, "My category")

2. Print a log message in the log category that you created:

   // Print to the log "This is an info message." using the MY_LOG_CATEGORY log category.
   kzLogInfo(MY_LOG_CATEGORY, ("This is an info message."));

3. Build and run your application or interact with your application in the Kanzi Studio Preview. When your application reaches the code where you created the log message, Kanzi prints the message to the debug console or to the Kanzi Studio Log window:

   info:My category> This is an info message.

Creating a custom logger

To redirect log messages, you can implement a custom logger class, which inherits from AbstractLogger, and push the custom logger to the Kanzi logging system. Make your logger class override the AbstractLogger::writeOverride function.

To write log messages using your custom logger, use the kzLog macro.

If you want to use your custom logger to write all the application log messages, register the logger in the Default Logger (DefaultLogger). The Default Logger inherits from AbstractLogger and contains a chain of loggers through which every log message passes. These loggers are by default registered in the Default Logger:

To implement a logger:

// Use this logger to store log messages in a container for later retrieval.
//
// This class inherits from kanzi::AbstractLogger and implements the writeOverride() function. It stores logs in the container.
// To retrieve the logs, use the get() function.
class SimpleLogger : public AbstractLogger
{
public:
    // Kanzi calls this function to write messages to the log.
    //
    // This function stores the log message in a container. To retrieve all log messages, use the get() function.
    // Each log message includes:
    // - The message text
    // - The log level
    // - The log category
    // - If the message is an error, the file name and the line number where the error occured
    //
    // \param level The log level of the message.
    // \param levelName The string representation of the log level.
    // \param categoryName The string representation of the log category.
    // \param fileName The name of the file in which the message originated.
    // \param lineNumber The number of the line on which the message originated.
    // \param message The message.
    virtual void writeOverride(LogLevel level, string_view levelName, string_view categoryName,
                               string_view fileName, size_t lineNumber, string_view message)
    {
        // Start the log with the level name.
        string logMessage(levelName);

        // Separate the log level and the log category with a colon.
        logMessage += ':';

        // Add the category name.
        logMessage.append(categoryName.data(), categoryName.length());

        if (level == LogLevelError)
        {
            // The error is reported.
            // To show where in the code the error was reported, add the file name and the line number to the message.
            logMessage.append(fileName.data(), fileName.length());

            // Separate the file name and the line number with a colon.
            logMessage += ':';
            logMessage += to_string(lineNumber);
        }

        // Add an angle bracket and the message text.
        logMessage += "> ";
        logMessage.append(message.data(), message.length());

        // Append the log message to the log vector.
        m_log.push_back(logMessage);
    }

    // Get log vector reference.
    vector<string>& getLog()
    {
        return m_log;
    }

private:
    // Log vector.
    vector<string> m_log;
};

To use a logger explicitly:

// SimpleLogger inherits from kanzi::AbstractLogger and implements writeOverride.
SimpleLogger simpleLogger;

// Write a log message using the SimpleLogger.
kzLog(simpleLogger, KZ_LOG_LEVEL_INFO, KZ_LOG_CATEGORY_GENERIC, ("Lets log 1 + 2 = {}.", 1 + 2));

To use a logger in a logger chain:

// SimpleLogger inherits from kanzi::AbstractLogger and implements writeOverride.
AbstractLoggerUniquePtr simpleLogger(new SimpleLogger());

// Before adding SimpleLogger to the logger chain, get the pointer to it.
// After you add SimpleLogger to the logger chain, the logger chain controls the lifetime of SimpleLogger.
SimpleLogger* simpleLoggerPtr = static_cast<SimpleLogger*>(simpleLogger.get());

// Push SimpleLogger to the logger chain. Now both SimpleLogger and the rest of the loggers handle every logged message.
DefaultLogger::pushLogger(kanzi::move(simpleLogger));

// Write a log message. SimpleLogger handles this message.
kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Lets log 1 + 2 = {}.", 1 + 2));

To set your logger to handle all the log messages:

// SimpleLogger inherits from kanzi::AbstractLogger and implements writeOverride.
AbstractLoggerUniquePtr simpleLogger(new SimpleLogger());

// Before adding SimpleLogger to the logger chain, get the pointer to it.
// After you add SimpleLogger to the logger chain, the logger chain controls the lifetime of SimpleLogger.
SimpleLogger* simpleLoggerPtr = static_cast<SimpleLogger*>(simpleLogger.get());

// Remove all default loggers from the logger chain.
// This way you make only SimpleLogger, which you push to the chain later, handle the logged messages.
DefaultLogger::popAllLoggers();

// Push SimpleLogger to the logger chain. Now only SimpleLogger handles every logged message.
DefaultLogger::pushLogger(kanzi::move(simpleLogger));

// Write a log message. SimpleLogger handles this message.
kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Lets log 1 + 2 = {}.", 1 + 2));

See also

Best practices

Measuring application performance

Troubleshooting the performance of your application

Logging Kanzi Engine performance profiling data

Logging application code performance profiling data

Logging resource profiling data

Open topic with navigation