log.hpp File Reference

#include <kanzi/core/log/default_logger.hpp>
#include <kanzi/core/log/log_category.hpp>
#include <kanzi/core/log/log_level.hpp>
#include <kanzi/core/log/log_record.hpp>
#include <kanzi/core/log/log_specialization.hpp>

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

Logging subsystem

The Logging subsystem is responsible for writing messages to the log. Use Logging macros provided by the subsystem for writing the log messages. You can use the log level and the log category to filter the log messages at compile-time. See Message classification and filtering. You can write scalar values as well as formatted messages to the log. For log message format description refer to Log message formating.

Message classification and filtering

Use the log level to classify the messages based on the severity of the information they contain. For example, you can use the error log level (KZ_LOG_LEVEL_ERROR) to log critical problems which occured during the application execution, while you can use the info log level (KZ_LOG_LEVEL_INFO) to log normal application activity. For more information about the log levels, see Log Level.

Use the log category to group messages that contain information about the same functionality. For example, you can create the "Engine" log category to log messages related to the rendering engine activity, while you can group messages related to KZB file loading in the "kzb loading" log category. For detailed information on how to create log categories, see Log category.

The log message filtering is implemented in Logging macros. Kanzi filters the log messages at compile-time using the log level and the log category that you assign to these messages. The preprocessor removes the call to the logging macro, if you disable the log level or the log category, assigned to the message in that macro call. Otherwise, the macro is replaced with the code that writes message to the log. To learn how to enable/disabled the log level and the log category, see Log Level and Log category.

Note

Do not use the application critical code in the logging macro calls. If you place application critical code as an argument to the logging macro call and during compilation you disable the log level or the log category assigned to the message in the call, then the preprocessor will remove the logging macro call together with the application critical code.

Examples

Shows how you can filter log messages:

        // The log level KZ_LOG_LEVEL_INFO and all log levels with severity above it are enabled because
        // KZ_LOG_LEVEL_ENABLED_THRESHOLD is set to KZ_LOG_LEVEL_INFO by default.
        
        // Define and enable Texture log category.
#define TEXTURE_LOG_CATEGORY    KZ_LOG_CREATE_CATEGORY(KZ_LOG_ENABLED_CATEGORY, "texture")
        
        // Define and disable Geometry log category.
#define GEOMETRY_LOG_CATEGORY   KZ_LOG_CREATE_CATEGORY(KZ_LOG_DISABLED_CATEGORY, "geometry")
        
        // This message is written to the log because both KZ_LOG_LEVEL_INFO and TEXTURE_LOG_CATEGORY are enabled.
        // Output: Texture size 400x600.
        kzLogInfo(TEXTURE_LOG_CATEGORY, ("Texture size {}x{}.", 400, 600));

        // This macro call is removed by the preprocessor because the log category GEOMETRY_LOG_CATEGORY is disabled.
        kzLogInfo(GEOMETRY_LOG_CATEGORY, ("Model consists of {} nodes.", 30000));

        // This macro call is removed by preprocessor because KZ_LOG_LEVEL_TRACE level is disabled by KZ_LOG_LEVEL_ENABLED_THRESHOLD setting.
        // The KZ_LOG_LEVEL_ENABLED_THRESHOLD is set to KZ_LOG_LEVEL_INFO by default and KZ_LOG_LEVEL_TRACE 
        // severity is below the KZ_LOG_LEVEL_INFO severity.
        kzLogTrace(TEXTURE_LOG_CATEGORY, ("Detailed texture information... Removed by preprocessor..."));        
                
        // Undefine KZ_LOG_LEVEL_ENABLED_THRESHOLD to set new log level threshold.
#undef KZ_LOG_LEVEL_ENABLED_THRESHOLD
        
        // Set log level threshold to KZ_LOG_LEVEL_TRACE to enable the trace log level and all levels with severity above it.
#define KZ_LOG_LEVEL_ENABLED_THRESHOLD    KZ_LOG_LEVEL_TRACE

        // This message is written to the log because both TEXTURE_LOG_CATEGORY and KZ_LOG_LEVEL_TRACE are enabled.
        // Output: Texture name: pic.png.
        kzLogTrace(TEXTURE_LOG_CATEGORY, ("Texture name: {}.", "pic.png"));

Shows the danger of using application critical code in a call to the logging macro:

        // Define and disable geometry log category.
#define GEOMETRY_LOG_CATEGORY   KZ_LOG_CREATE_CATEGORY(KZ_LOG_DISABLED_CATEGORY, "geometry")

        // Define and enable rendering log category.
#define RENDERING_LOG_CATEGORY KZ_LOG_CREATE_CATEGORY(KZ_LOG_ENABLED_CATEGORY, "rendering")
        
        int numberOfNodes = 0;
        
        // In this example, the increment of the 'numberOfNodes' variable, used to log the message, 
        // is critical for the application. Because the geometry log category (GEOMETRY_LOG_CATEGORY) is disabled,
        // this macro call together with code incrementing the 'numberOfNodes' variable 
        // is removed by preprocessor.
        kzLogInfo(GEOMETRY_LOG_CATEGORY, ("Add node. Total number of nodes {}.", ++numberOfNodes));
                
        // This statement writes to the log "Number of nodes is 0.".
        kzLogInfo(RENDERING_LOG_CATEGORY, ("Number of nodes is {}.", numberOfNodes));