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

Logging subsystem

The Logging subsystem is responsible for writing messages to the log. To write log messages, use the Logging macros provided by the subsystem.

To filter log messages at compile time, use log levels and log categories. See Classifying and filtering log messages.

You can write both scalar values and formatted messages to the log. See Log message formatting.

Classifying and filtering log messages

Use log levels to classify log messages based on the severity of the information that they contain. For example, to log critical problems, which occur during application execution, use the error log level KZ_LOG_LEVEL_ERROR. To log normal application activity, use the info log level KZ_LOG_LEVEL_INFO. See Log Level.

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

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

Note

Do not use 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, the preprocessor removes the logging macro call together with the application critical code.

Examples

This example 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"));

This example 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,
        // the preprocessor removes this macro call together with the code incrementing the 'numberOfNodes' variable.
        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));