Logging macros

Collaboration diagram for Logging macros:

Macros
#define	kzLog(logger, level, category, message)
	Use the kzLog macro to write log messages using a custom logger.
#define	kzLogDebug(message)
	To write debug log messages with the Default Logger, use kzLogDebug macro.
#define	kzLogError(category, message)
	To write error log messages with the Default Logger, use kzLogError macro.
#define	kzLogInfo(category, message)
	To write info log messages with the Default Logger, use kzLogInfo macro.
#define	kzLogTrace(category, message)
	To write trace log messages with the Default Logger, use kzLogTrace macro.
#define	kzLogWarning(category, message)
	To write warning log messages with the Default Logger, use kzLogWarning macro.

Detailed Description

Use logging macros to write messages to the log. These macros are used to implement compile-time message filtering described in Classifying and filtering log messages.

Macro Definition Documentation

kzLog

#define kzLog	(		logger,
			level,
			category,
			message )

Use the kzLog macro to write log messages using a custom logger.

This macro assigns the log level and the log category to the message and writes it to the log using the logger you provided. If you want to use your logger to write all the application log messages, register your logger in kanzi::DefaultLogger.

Parameters

logger	The logger you want to use to write the message to the log.
level	The log level of the message.
category	The log category of the message.
message	The log message.

See also

Log message formatting

Examples

To implement your own 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.
            void writeOverride(LogLevel level, string_view levelName, string_view categoryName,
                                       string_view fileName, size_t lineNumber, string_view message) override
            {
                // 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 your own logger to write a message to the log:

        // SimpleLogger inherits from kanzi::AbstractLogger and implements writeOverride.
        SimpleLogger simpleLogger;
 
        // Write a log message using SimpleLogger.
        kzLog(simpleLogger, KZ_LOG_LEVEL_INFO, KZ_LOG_CATEGORY_GENERIC, ("Lets log 1 + 2 = {}.", 1 + 2));

kzLogError

#define kzLogError	(		category,
			message )

To write error log messages with the Default Logger, use kzLogError macro.

This macro assigns KZ_LOG_LEVEL_ERROR log level and the log category you provided to the message. For more information about the Default Logger, see kanzi::DefaultLogger.

Parameters

category	The log category assigned to the message.
message	The log message.

See also

Log message formatting

Example

To write the error message to the log:

        // Log error message with generic log category.
        // Output: Error message 1, 2.
        kzLogError(KZ_LOG_CATEGORY_GENERIC, ("Error message {}, {}.", 1, 2));

kzLogWarning

#define kzLogWarning	(		category,
			message )

To write warning log messages with the Default Logger, use kzLogWarning macro.

This macro assigns KZ_LOG_LEVEL_WARNING log level and the log category you provided to the message. For more information about the Default Logger, see kanzi::DefaultLogger.

Parameters

category	The log category assigned to the message.
message	The log message.

See also

Log message formatting

Example

To write the warning message to the log:

        // Log warning message with generic log category.
        // Output: Warning message 1, 2.
        kzLogWarning(KZ_LOG_CATEGORY_GENERIC, ("Warning message {}, {}.", 1, 2));

kzLogInfo

#define kzLogInfo	(		category,
			message )

To write info log messages with the Default Logger, use kzLogInfo macro.

This macro assigns KZ_LOG_LEVEL_INFO log level and the log category you provided to the message. For more information about the Default Logger, see kanzi::DefaultLogger.

Parameters

category	The log category assigned to the message.
message	The log message.

See also

Log message formatting

Example

To write the info message to the log:

        // Log info message with generic log category.
        // Output: Info message 1, 2.
        kzLogInfo(KZ_LOG_CATEGORY_GENERIC, ("Info message {}, {}.", 1, 2));

kzLogTrace

#define kzLogTrace	(		category,
			message )

To write trace log messages with the Default Logger, use kzLogTrace macro.

This macro assigns KZ_LOG_LEVEL_TRACE log level and the log category you provided to the message. For more information about the Default Logger, see kanzi::DefaultLogger.

Parameters

category	The log category assigned to the message.
message	The log message.

See also

Log message formatting

Example

To write the trace message to the log:

        // Log trace message with generic log category.
        // Output: Trace message 1, 2.
        kzLogTrace(KZ_LOG_CATEGORY_GENERIC, ("Trace message {}, {}.", 1, 2));

kzLogDebug

#define kzLogDebug

(

message

)

To write debug log messages with the Default Logger, use kzLogDebug macro.

This macro assigns KZ_LOG_LEVEL_INFO log level and KZ_LOG_CATEGORY_DEBUG log category to the message. For more information about the Default Logger, see kanzi::DefaultLogger.

Parameters

message

The log message.

See also

Log message formatting

Example

To write the debug message to the log:

        // Log debug message with info log level and debug log category.
        // Output: Debug message 1, 2.
        kzLogDebug(("Debug message {}, {}.", 1, 2));