日志系统

[English]

公共头文件： #include "brookesia/lib_utils/log.hpp"

概述

log 提供统一的日志接口与格式化能力，可在 ESP_LOG 与标准输出之间切换， 并支持基于 std::source_location 的上下文信息。

特性

  • 支持多级别日志输出（Trace/Debug/Info/Warn/Error）

  • 统一的格式化接口，兼容 boost::format 风格占位符

  • 自动提取函数名、文件名等上下文，便于定位问题

  • 提供 Trace Guard 用于自动记录函数进入/退出

API 参考

Header File

Classes

class Log

Logging backend facade used by the public logging macros.

Public Functions

inline void print(int level, const std::source_location &loc, const char *tag, const char *format)

Print a preformatted message.

参数

  • level – Log level defined by BROOKESIA_UTILS_LOG_LEVEL_*.

  • loc – Source location used for metadata extraction.

  • tag – Log tag string.

  • format – Message string passed through without argument formatting.

template<typename ...Args>
inline void print(int level, const std::source_location &loc, const char *tag, const char *format, Args&&... args)

Format a message and print it.

模板参数

Args – Format argument types.

参数

  • level – Log level defined by BROOKESIA_UTILS_LOG_LEVEL_*.

  • loc – Source location used for metadata extraction.

  • tag – Log tag string.

  • format – Boost-format-style message format.

  • args – Format arguments forwarded through the type-erased formatter.

Public Static Functions

static inline Log &getInstance()

Get the singleton logging facade.

返回

Reference to the shared Log instance.

static void write(int level, const std::source_location &loc, const char *tag, const std::string &message)

Emit a fully formatted message through the selected backend.

参数

  • level – Log level defined by BROOKESIA_UTILS_LOG_LEVEL_*.

  • loc – Source location used for metadata extraction.

  • tag – Log tag string.

  • message – Final message body.

static std::string format_message(const char *format, std::initializer_list<FormatArg> args)

Format a message using boost::format-style placeholders.

参数

  • format – Format string.

  • args – Type-erased format arguments.

返回

Formatted message string.

static std::string_view extract_function_name(const char *func_name)

Extract the display-friendly function name from a source location string.

参数

func_name – Raw function signature string.

返回

Trimmed function name view.

static std::string_view extract_file_name(const char *file_path)

Extract the leaf file name from a source path.

参数

file_path – Raw source file path.

返回

File name view without directory components.

template<bool Enabled>
class LogTraceGuard

RAII helper that logs function entry and exit at trace level.

模板参数

Enabled – Compile-time flag that removes all work when false.

Public Functions

inline LogTraceGuard(const void *this_ptr = nullptr, const std::source_location &loc = std::source_location::current(), const char *tag = esp_brookesia::lib_utils::TAG)

Construct a trace guard for the current scope.

参数

  • this_ptr – Optional object pointer logged for member functions.

  • loc – Source location captured for the scope.

  • tag – Log tag string.

inline ~LogTraceGuard()

Log scope exit when trace logging is enabled.

Macros

_BROOKESIA_LOG_FORMAT_THREAD_NAME

Helper macros to assemble format string and arguments based on enabled macros These macros use string literal concatenation (adjacent string literals are automatically concatenated)

_BROOKESIA_LOG_FORMAT_FILE_LINE
_BROOKESIA_LOG_FORMAT_FUNCTION
_BROOKESIA_LOG_FORMAT_MESSAGE
_BROOKESIA_LOG_FORMAT_STRING
_BROOKESIA_LOG_ARGS_THREAD_NAME(thread_name)
_BROOKESIA_LOG_ARGS_FILE_LINE(file_name, line)
_BROOKESIA_LOG_ARGS_FUNCTION(func_name)
_BROOKESIA_LOG_ARGS_MESSAGE(format_str)
_BROOKESIA_LOG_ARGS(thread_name, file_name, line, func_name, format_str)
BROOKESIA_LOGT_IMPL(tag, format, ...)

Macros to simplify logging calls with a fixed tag

BROOKESIA_LOGD_IMPL(tag, format, ...)
BROOKESIA_LOGI_IMPL(tag, format, ...)
BROOKESIA_LOGW_IMPL(tag, format, ...)
BROOKESIA_LOGE_IMPL(tag, format, ...)
BROOKESIA_LOG_DISABLE_DEBUG_TRACE

Per-file switch that disables BROOKESIA_LOGT, BROOKESIA_LOGD, and trace-guard helpers.

Users can define this macro before including this header to override the default behavior.

#define BROOKESIA_LOG_DISABLE_DEBUG_TRACE 1  // Disable all debug & trace features for this file
#include "brookesia/lib_utils/log.hpp"
BROOKESIA_LOGT(format, ...)

Compile-time log level filtering macros.

Calls below the configured log level expand to no-ops.

Emit a trace-level log message for the current translation unit tag.

BROOKESIA_LOGD(format, ...)

Emit a debug-level log message for the current translation unit tag.

BROOKESIA_LOGI(format, ...)

Emit an info-level log message for the current translation unit tag.

BROOKESIA_LOGW(format, ...)

Emit a warning-level log message for the current translation unit tag.

BROOKESIA_LOGE(format, ...)

Emit an error-level log message for the current translation unit tag.

_BROOKESIA_LOG_TRACE_FORMAT_ENTER_WITH_PTR
_BROOKESIA_LOG_TRACE_FORMAT_ENTER
_BROOKESIA_LOG_TRACE_FORMAT_EXIT_WITH_PTR
_BROOKESIA_LOG_TRACE_FORMAT_EXIT
_BROOKESIA_LOG_TRACE_FORMAT_ENTER_WITH_PTR_STRING
_BROOKESIA_LOG_TRACE_FORMAT_ENTER_STRING
_BROOKESIA_LOG_TRACE_FORMAT_EXIT_WITH_PTR_STRING
_BROOKESIA_LOG_TRACE_FORMAT_EXIT_STRING
_BROOKESIA_LOG_TRACE_ARGS_WITH_PTR(thread_name, file_name, line, func_name, this_ptr)
_BROOKESIA_LOG_CONCAT(a, b)

Create a scope guard that logs entry and exit for the current function.

BROOKESIA_LOG_CONCAT(a, b)
BROOKESIA_LOG_TRACE_GUARD()
BROOKESIA_LOG_TRACE_GUARD_WITH_THIS()

Create a scope guard that logs entry and exit and includes this.