Logging macros

Use logging macros to write messages to the log. More...

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

Detailed Description

Use logging macros to write messages to the log.

These macros are used to implement compile-time message filtering described in Message classification and filtering.

Macro Definition Documentation

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

To use custom logger to write log messages, use kzLog macro.

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 within the Default Logger (see 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 message. For format description see LogMessageStructureSection.

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 writeOverride() function. It stores logs in the container.
        // The logs could be retrieved with get() function.
        class SimpleLogger : public AbstractLogger
        {
        public:
            // Kanzi calls this function to write message to the log.
            //
            // This function stores the log message in a container. To retreive all log messages use get() function.
            // Every log message along with message text itself includes the following information:
            // - the log level
            // - the log category
            // - if an error is reported, the file name and the line number where 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 file name where the message originated.
            // \param lineNumber The line number where 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);
                
                // Seperate the log level and the log category with a colon.
                logMessage += ':';
                
                // Aadd category name.
                logMessage.append(categoryName.data(), categoryName.length());
                
                if (level == LogLevelError)
                {
                    // The error is reported.
                    // Add the file name and the line number to the message to show the place in a code where the error was reported.
                    logMessage.append(fileName.data(), fileName.length());
                    
                    // Seperate the file name and the line number with a dot.
                    logMessage += '.';                    
                    logMessage += to_string(lineNumber);                    
                }

                // Finally, add an angle brace 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 log message using Simple Logger.
        kzLog(simpleLogger, KZ_LOG_LEVEL_INFO, KZ_LOG_CATEGORY_GENERIC, ("Lets log 1 + 2 = {}.", 1 + 2));

        // Prints to console: info:generic> Lets log 1 + 2 = 3.
        std::cout << simpleLogger.getLog()[0] << std::endl;

#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 message. For format description see LogMessageStructureSection.

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

#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 message. For format description see LogMessageStructureSection.

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

#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 message. For format description see LogMessageStructureSection.

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

#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 message. For format description see LogMessageStructureSection.

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

#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 message. For format description see LogMessageStructureSection.

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