Logs

#include <Luna/Runtime/Log.hpp>

Luna SDK contains a log system that can be used for logging and debugging purposes.

Log message

LogMessage structure represents one log entry. Every log message contains four properties:

  1. sender: The name of the function or module that emits this log, which can be used to filter logs.
  2. message: The log message, which is a UTF-8 string.
  3. verbosity: The verbosity level of the log, which can be used to filter logs based on verbosity level.
  4. extra: Extra arguments attached to the log entry, represented by one Variant object.

One log message can be submitted to the log system by constructing one LogMessage object and passing it tolog function manually. It can also be submitted conveniently by calling log_verbose, log_info, log_warning and log_error based on the verbosity level of your log message.

Log handler

Log handlers are entities that handle log messages to display or save them. For example, you may implement a log handler to display the log message on your game HUD or editor window. When one log is submitted to the log system, it will be dispatched to all handlers, the handler should decide whether to handle or skip this log by its filter and verbosity level settings.

One log handler can be registered to the log system by register_log_callback, and unregistered from the log system by unregister_log_callback. When one log handler callback function is invoked, the same LogMessage object passed by the user or generated by the system will be provided, but is read-only to the handler.

Built-in log handlers

The log system includes two built-in log handlers: the STD log handler and the file log handler.

STD log handler

STD log handler outputs log messages to the standard output (stdout) of the program using printf. The STD log handler is disabled by default, the user can call set_log_std_enabled to enable/disable it at any time. The verbosity level of STD log handler can be configured by set_log_std_verbosity.

File log handler

File log handler outputs log messages to the file specified by the user. The file log handler is disabled by default, the user can call set_log_file_enabled to enable/disable it at any time. The user can call set_log_file to set the destination file of the log messages. If no file is set by the user, the handler will output logs to Log.txtfile on the current working directory. For performance reasons, log messages will not be written to file immediately when being handled, but will be buffered internally and written to the file only when the buffer is full. You can also call flush_log_to_file manually if you want the buffer to be flushed immediately.