feat: update log examples & doc (#69)

document/sphinx-cn/release_notes/v0_9_0.md

@@ -24,3 +24,5 @@
 - 为 aimrt_py 的 channel 功能提供了 Context 支持；
 - 现在支持 install aimrt::runtime::core；
 - 删除一些未使用的协议；
+- 支持日志自定义输出格式；
+

document/sphinx-cn/tutorials/cfg/log.md

@@ -65,8 +65,8 @@ aimrt:
 - `console`日志后端不允许重复注册，一个 AimRT 实例中只允许注册一个。
 - `color`配置了是否要彩色打印。此项配置有可能在一些操作系统不支持。
 - `module_filter`支持以正则表达式的形式，来配置哪些模块的日志可以通过本后端处理。这与模块日志等级不同，模块日志等级是全局的、先决的、影响所有日志后端的，而这里的配置只影响本后端。
-- `log_executor_name`配置了日志执行器。要求日志执行器是线程安全的，如果没有配置，则默认使用主线程打印日志。
+- `log_executor_name`配置了日志执行器。要求日志执行器是线程安全的，如果没有配置，则默认使用 guard 线程打印日志。
-- `pattern` 通过 `"%" + 字符` 的形式来进行格式化输出， 具体可输出格式如下：
+- `pattern` 通过 `"%" + 字符` 的形式来进行格式化输出，具体可输出格式如下：
   
  | 格式  | 解释                     | 举例                            |
  | ----- | ------------------------ | ------------------------------- |
@@ -138,7 +138,8 @@ aimrt:
 - 当单个日志文件尺寸超过`max_file_size_m`配置的大小后，就会新建一个日志文件，同时将老的日志文件重命名，加上`_x`这样的后缀。
 - 当日志文件数量超过`max_file_num`配置的值后，就会将最老的日志文件删除。如果配置为 0，则表示永远不会删除。
 - `module_filter`支持以正则表达式的形式，来配置哪些模块的日志可以通过本后端处理。这与模块日志等级不同，模块日志等级是全局的、先决的、影响所有日志后端的，而这里的配置只影响本后端。
-
+- `log_executor_name`配置了日志执行器。要求日志执行器是线程安全的，如果没有配置，则默认使用 guard 线程打印日志。
+- `pattern` 通过 `"%" + 字符` 的形式来进行格式化输出，具体可参考[console 控制台](#console-控制台日志后端)配置中的 `pattern` 字段说明。
 
 
 以下是一个简单的示例：

src/examples/cpp/logger/README.md

@@ -105,3 +105,31 @@
         type: simple_thread # 执行器类型（类型具体参考 AimRT 使用手册执行器部分）
 ```
 
+
+## logger format
+
+一个最基本的 cpp logger 示例，演示内容包括：
+- 如何使用自定义的 format 格式输出日志；
+
+核心代码：
+- [logger_module.cc](./module/logger_module/logger_module.cc)
+- [pkg_main.cc](./pkg/logger_pkg/pkg_main.cc)
+
+
+配置文件：
+- [examples_cpp_logger_format_cfg.yaml](./install/linux/bin/cfg/examples_cpp_logger_format_cfg.yaml)
+
+
+运行方式（linux）：
+- 开启 `AIMRT_BUILD_EXAMPLES` 选项编译 AimRT；
+- 直接运行 build 目录下`start_examples_cpp_logger_format.sh`脚本启动进程；
+- 键入`ctrl-c`停止进程；
+
+
+说明：
+- 此示例创建了一个 `LoggerModule`，会在其 `Start`的阶段循环打印各种等级的日志；
+- 此示例将 `LoggerModule` 集成到 `logger_pkg` 中，并在配置文件中加载此 Pkg；
+- 此示例配置了日志打印格式为`[%c.%f][%A][%l][%t][%n][%G] %v`，日志输出示例如下：
+```
+[2024-10-31 20:35:28.378443][Thursday][Info][126632][LoggerModule][logger_module.cc] Test info log
+```

src/examples/cpp/logger/install/linux/bin/cfg/examples_cpp_logger_cfg.yaml

@@ -6,8 +6,6 @@ aimrt:
     core_lvl: INFO # Trace/Debug/Info/Warn/Error/Fatal/Off
     backends:
       - type: console
-        options:
-          pattern: "[%c.%f][%A][%l][%t][%n][%G] %v"
   executor:
     executors:
       - name: work_executor

src/examples/cpp/logger/install/linux/bin/cfg/examples_cpp_logger_format_cfg.yaml

@@ -0,0 +1,21 @@
+# Copyright (c) 2023, AgiBot Inc.
+# All rights reserved.
+
+aimrt:
+  log:
+    core_lvl: INFO # Trace/Debug/Info/Warn/Error/Fatal/Off
+    backends:
+      - type: console
+        options:
+          pattern: "[%c.%f][%A][%l][%t][%n][%G] %v"
+  executor:
+    executors:
+      - name: work_executor
+        type: simple_thread
+  module:
+    pkgs:
+      - path: ./liblogger_pkg.so
+        enable_modules: [LoggerModule]
+    modules:
+      - name: LoggerModule
+        log_lvl: TRACE

src/examples/cpp/logger/install/linux/bin/start_examples_cpp_logger_format.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+./aimrt_main --cfg_file_path=./cfg/examples_cpp_logger_format_cfg.yaml

src/examples/cpp/logger/install/win/bin/cfg/examples_cpp_logger_format_cfg.yaml

@@ -0,0 +1,21 @@
+# Copyright (c) 2023, AgiBot Inc.
+# All rights reserved.
+
+aimrt:
+  log:
+    core_lvl: INFO # Trace/Debug/Info/Warn/Error/Fatal/Off
+    backends:
+      - type: console
+        options:
+          pattern: "[%c.%f][%A][%l][%t][%n][%G] %v"
+  executor:
+    executors:
+      - name: work_executor
+        type: simple_thread
+  module:
+    pkgs:
+      - path: ./logger_pkg.dll
+        enable_modules: [LoggerModule]
+    modules:
+      - name: LoggerModule
+        log_lvl: TRACE

src/examples/cpp/logger/install/win/bin/start_examples_cpp_logger_format.bat

@@ -0,0 +1,2 @@
+
+.\aimrt_main.exe --cfg_file_path=./cfg/examples_cpp_logger_format_cfg.yaml

src/runtime/core/logger/formatter.h

@@ -5,7 +5,7 @@
 
 #include <cassert>
 #include <functional>
-#include <iostream>
+
 #include "core/logger/log_data_wrapper.h"
 #include "core/logger/log_level_tool.h"
 #include "util/exception.h"
@@ -25,9 +25,7 @@ class LogFormatter {
   }
 
   void SetPattern(const std::string& pattern) {
-    if (pattern.empty()) [[unlikely]] {
+    AIMRT_ASSERT(!pattern.empty(), "Invalid argument: Logger's pattern cannot be empty");
-      throw aimrt::common::util::AimRTException("Invalid argument: Logger's pattern cannot be empty");
-    }
 
     try {
       format_handlers_.clear();
@@ -108,27 +106,27 @@ class LogFormatter {
               format_handlers_.emplace_back(format_thread_id);
               break;
             case 'n':  // module name (test_module)
-              estimated_size_ += 35;
+              estimated_size_ += 32;
               format_handlers_.emplace_back(format_module);
               break;
             case 'G':  // file name_short (test_module.cpp)
-              estimated_size_ += 35;
+              estimated_size_ += 32;
               format_handlers_.emplace_back(format_file_short);
               break;
             case 'g':  // file name (/XX/YY/ZZ/test_module.cpp)
-              estimated_size_ += 500;
+              estimated_size_ += 256;
               format_handlers_.emplace_back(format_file);
               break;
             case 'R':  // row number (20)
-              estimated_size_ += 6;
+              estimated_size_ += 8;
               format_handlers_.emplace_back(format_line);
               break;
             case 'C':  // column number (20)
-              estimated_size_ += 6;
+              estimated_size_ += 4;
               format_handlers_.emplace_back(format_column);
               break;
             case 'F':  // function name (TestFunc)
-              estimated_size_ += 30;
+              estimated_size_ += 32;
               format_handlers_.emplace_back(format_function);
               break;
             case 'v':  // message
@@ -265,6 +263,7 @@ class LogFormatter {
     buffer.append(data.function_name);
   }
 
+ private:
   using FormatHandler = std::function<void(const LogDataWrapper&, std::string&)>;
   std::vector<FormatHandler> format_handlers_;