DLOG 日志系统

简介

日志(log)是对发生某个事件的记录，并进行显示或者保存到文件。

DLOG 日志系统主要有以下特性:

• 默认支持输出到串口终端，支持添加后端实现多路日志，可支持串口、网络、文件、闪存等后端形式。
• 输出被设计为任务线程安全的方式，并支持异步输出模式。
• 支持在中断等复杂上下文环境下使用。
• 支持浮点数格式。
• 支持 4 个等级，优先级由高到低 LOG_LVL_ERROR LOG_LVL_WARNING LOG_LVL_INFO LOG_LVL_DEBUG。
• 支持按等级进行全局过滤，高于配置等级的将输出日志。
• 支持标签方式过滤，添加标签过滤器后，高于标签过滤器等级的标签相关日志将输出。使用了标签过滤器，全局过滤将不再对此标签起作用，直到删除标签过滤器。
• 支持全局标签过滤，设置了全局标签后，只有此标签的日志输出，直到删除全局标签。
• 支持全局关键字过滤，设置了全局关键字后，只有含关键字的日志输出，直到删除全局关键字。
• 支持全部编译和部分编译两种使用方式，在部分编译方式下，可以有效降低产品版本发布时对 ROM 空间的占用。
• 输出格式可进行配置，配置项包含时间、任务、函数名称，文件行号，颜色等。
• 配置支持 shell 操作，简单易用。

DLOG 日志系统整体框架如下：

1. dlog 前端

(1) dlog 前端兼容 linux syslog 接口（需包含 syslog.h 头文件），接口形式如下： void syslog(int priority, const char *format, ...) 注：若想兼容 linux syslog 接口，需要同时打开 dlog 的编译宏 OS_USING_DLOG 和 syslog 的编译宏 DLOG_USING_SYSLOG，否则不支持。

(2)除了兼容 linux syslog 接口，dlog 前端还提供 2 套接口，一套是所有级别的日志全部编译到烧录文件中，使用 LOG_X 接口形式，需包含 os_dbg.h 头文件；另外一套是各种级别的日志打印根据用户定义的编译级别选择是否编译到烧录文件中，使用 LOG_EXT_X 接口形式，需包含 os_dbg_ext.h；这 2 套接口不能在同一个.c 文件中同时使用，即不能同时包含 os_dbg.h 和 os_dbg_ext.h 头文件，否则会出现编译错误。

2. dlog 核心

(1) 前过滤器包括标签过滤、全局过滤和全局标签过滤，当标签级别过滤器中存在本条日志的标签时，则按照此标签对应的输出级别进行日志输出控制；若不存在，则按照全局的输出级别进行输出控制，标签级别过滤优先于全局级别过滤。当日志级别过滤完成后，进行全局标签过滤，即：若设置了全局过滤标签，则只打印包含此标签的日志。

(2) 格式化模块可以控制哪些日志信息是否输出，可以控制是否支持浮点数打印、是否支持颜色输出、是否支持时间输出以及何种类型的时间、是否输出日志级别信息、是否输出标签信息、是否输出任务线程的名称。

(3) 后过滤器包含全局关键字过滤，即：若设置了全局过滤关键字，则只打印包含此关键字的日志。

(4)dlog 支持异步输出和同步输出。在异步输出模式下，会把日志先存到缓冲区中，待系统空闲时，调用专门的任务线程输出日志到后端；在同步输出模式下，不切换任务（或中断）上下文，直接把日志输出到后端。另外，不管在异步输出模式还是在同步输出模式，都支持在中断上下文打印（需要使能 DLOG_USING_ISR_LOG 编译开关）。

3. dlog 后端

dlog 可以同时支持形式多样的日志后端，如串口、文件、网络。dlog 提供了统一接口对日志后端进行管理。

目前，dlog 组件已经支持日志后端的文件系统记录功能，以文件的形式将日志信息记录在文件系统中，需要使能 DLOG_BACKEND_USING_FILESYSTEM 编译开关，添加 dlog 日志后端文件系统记录日志功能。用户也可以通过 dlog_backend_register 函数注册自己的后端。

重要定义及数据结构

结构体

struct dlog_backend
{
    os_slist_node_t list;
    char            name[OS_NAME_MAX + 1];          /* Name of log backend. */
    os_bool_t       support_color;                  /* Whether backend support color. */
    os_bool_t       support_isr;                    /* Whether backend support isr. */

    void (*init)  (struct dlog_backend *backend);   /* Initialize backend. */
    void (*deinit)(struct dlog_backend *backend);   /* De-initialize backend. */

    void (*output)(struct dlog_backend *backend,
                   os_uint16_t          level,
                   const char          *tag,
                   os_bool_t            is_raw,
                   const char          *log,
                   os_size_t            len);       /* Output log to backend */

    void (*flush) (struct dlog_backend *backend);   /* Flush logs in the buffer of backend */
};

struct os_klog_ctrl_info
{
    os_list_node_t tag_lvl_list;                            /* The filter list */
    os_uint16_t    global_level;                            /* The global filter level */
    char           log_buff[OS_LOG_BUFF_SIZE];              /* Buffer of formatted log information */
};

API 列表

dlog_backend_register

该函数用于向 dlog 日志模块注册日志后端，函数原型如下：

os_err_t dlog_backend_register(dlog_backend_t *backend);

dlog_backend_unregister

该函数用于向 dlog 日志模块注册日志后端，函数原型如下：

os_err_t dlog_backend_unregister(dlog_backend_t *backend);

dlog_tag_lvl_filter_set

该函数用于配置标签过滤器等级，函数原型如下：

os_err_t dlog_tag_lvl_filter_set(const char *tag, os_uint16_t level);

dlog_tag_lvl_filter_get

该函数用于获取标签过滤器等级，函数原型如下：

os_err_t dlog_tag_lvl_filter_get(const char *tag, os_uint16_t *level);

dlog_tag_lvl_filter_del

该函数用于获取标签过滤器等级，函数原型如下：

os_err_t dlog_tag_lvl_filter_del(const char *tag);

dlog_global_filter_tag_set

该函数用于配置全局过滤器的标签，函数原型如下：

void dlog_global_filter_tag_set(const char *tag);

dlog_global_filter_tag_get

该函数用于获取全局过滤器的标签，函数原型如下：

const char *dlog_global_filter_tag_get(void);

dlog_global_filter_tag_del

该函数用于删除全局过滤器的标签，函数原型如下：

void dlog_global_filter_tag_del(void);

dlog_global_filter_kw_set

该函数用于配置全局过滤器的关键字，函数原型如下：

void dlog_global_filter_kw_set(const char *keyword);

dlog_global_filter_kw_get

该函数用于获取全局过滤器的关键字，函数原型如下：

const char *dlog_global_filter_kw_get(void);

dlog_global_filter_kw_del

该函数用于删除全局过滤器的关键字，函数原型如下：

void dlog_global_filter_kw_del(void);

宏列表

LOG_E

该宏为 LOG_LVL_ERROR 等级日志输出，LOG_LVL_ERROR 等级不低于 DBG_EXT_LVL 时添加到编译，实际定义如下：

#define LOG_E(tag, fmt, ...)

LOG_W

该宏为 LOG_LVL_WARNING 等级日志输出，LOG_LVL_WARNING 等级不低于 DBG_EXT_LVL 时添加到编译，实际定义如下：

#define LOG_W(tag, fmt, ...)

LOG_I

该宏为 LOG_LVL_INFO 等级日志输出，LOG_LVL_INFO 等级不低于 DBG_EXT_LVL 时添加到编译，实际定义如下：

#define LOG_I(tag, fmt, ...)

LOG_D

该宏为 LOG_LVL_DEBUG 等级日志输出，LOG_LVL_DEBUG 等级不低于 DBG_EXT_LVL 时添加到编译，实际定义如下：

#define LOG_D(tag, fmt, ...)

LOG_RAW

该宏为常规日志输出，实际定义如下：

#define LOG_RAW(fmt, ...)

LOG_HEX

该宏为把数据转化为十六进制输出，实际定义如下：

#define LOG_HEX(tag, width, buf, size)

LOG_EXT_E

该宏为 LOG_LVL_ERROR 等级日志输出，实际定义如下：

#define LOG_EXT_E(tag, fmt, ...)

LOG_EXT_W

该宏为 LOG_LVL_WARNING 等级日志输出，实际定义如下：

#define LOG_EXT_W(tag, fmt, ...)

LOG_EXT_I

该宏为 LOG_LVL_INFO 等级日志输出，实际定义如下：

#define LOG_EXT_I(tag, fmt, ...)

LOG_EXT_D

该宏为 LOG_LVL_DEBUG 等级日志输出，实际定义如下：

#define LOG_EXT_D(tag, fmt, ...)

LOG_EXT_RAW

该宏为常规日志输出，实际定义如下：

#define LOG_EXT_RAW(fmt, ...)

LOG_EXT_HEX

该宏为把数据转化为十六进制输出，实际定义如下：

#define LOG_EXT_HEX(tag, width, buf, size)

shell 列表

dlog_glvl_ctrl

该命令用于控制调试日志全局过滤器等级，包括设置，获取等操作，相对应的函数原型如下:

static os_err_t sh_dlog_global_level_control(os_int32_t argc, char **argv);

dlog_tlvl_ctrl

该函数用于控制调试日志标签过滤器等级的 shell 函数实现，包括设置，获取，删除等操作，函数原型如下:

static os_err_t sh_dlog_tag_level_control(os_int32_t argc, char **argv);

dlog_gtag_ctrl

该函数用于控制内核日志全局标签过滤器等级的 shell 函数实现，包括设置，获取等操作，函数原型如下:

static os_err_t sh_dlog_global_tag_control(os_int32_t argc, char **argv);

dlog_gkw_ctrl

该函数用于控制内核日志全局关键字过滤器的 shell 函数实现，包括设置，获取等操作，函数原型如下:

static os_err_t sh_dlog_global_keyword_control(os_int32_t argc, char **argv);

使用示例

全部编译示例代码

本示例代码使用全部编译宏打印了所有等级的日志，后续使用 shell 命令来过滤日志信息。

#include <oneos_config.h>
#include <os_util.h>
#include <os_dbg.h>
#include <shell.h>

#define TAG_A               "TAG_A"
#define TAG_B               "TAG_B"

void sh_dlog_test(os_int32_t argc, char **argv)
{
    LOG_E(TAG_A, "TAG_A DLOG_ERROR");
    LOG_D(TAG_A, "TAG_A DLOG_WARNING");
    LOG_I(TAG_A, "TAG_A DLOG_INFO");
    LOG_D(TAG_A, "TAG_A DLOG_DEBUG");

    LOG_E(TAG_B, "TAG_B DLOG_ERROR");
    LOG_D(TAG_B, "TAG_B DLOG_WARNING");
    LOG_I(TAG_B, "TAG_B DLOG_INFO");
    LOG_D(TAG_B, "TAG_B DLOG_DEBUG");
}
SH_CMD_EXPORT(dlog_test, sh_dlog_test, "test dlog tag level");

调整全局过滤器等级示例

本示例主要演示全局过滤器等级由 LOG_LVL_WARNING 调整 LOG_LVL_ERROR 日志，使得只有 LOG_LVL_ERROR 以上等级的日志输出，运行结果如下：

sh>dlog_glvl_ctrl
Command format:
dlog_glvl_ctrl [-s | -g] [-l global level]
parameter Usage:
         -s     Set global level option.
         -g     Get global level option.
         -l     Specify a global level that want to be set.
                level: 3-error, 4-warning, 6-info, 7-debug
sh>
sh>dlog_glvl_ctrl -g
Level is: 4
sh>
sh>dlog_test
[1976] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[1976] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[1977] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[1977] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]
sh>
sh>dlog_glvl_ctrl -s -l 3
Set global level(3) of dlog success
sh>
sh>dlog_test
[3536] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[3536] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]

调整标签过滤器等级示例

本示例主要演示添加一个标签过滤器，其过滤等级 LOG_LVL_ERROR 日志，使得这个标签只有 LOG_LVL_ERROR 以上等级日志输出，运行结果如下：

sh>dlog_tlvl_ctrl
Command format:
dlog_tlvl_ctrl [-s | -g | -d] [-n tag name] [-l tag level]
parameter Usage:
         -s     Set tag level option.
         -g     Get tag level option.
         -d     Delete tag level option.
         -n     Specify the tag name that want set level.
         -l     Specify a tag level that want to be set.
                level: 3-error, 4-warning, 6-info, 7-debug
sh>
sh>dlog_test
[2878] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[2878] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[2879] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[2879] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]
sh>
sh>dlog_tlvl_ctrl -s -n TAG_A -l 3
Set tag level of dlog success, tag: TAG_A, level: 3
sh>
sh>dlog_tlvl_ctrl -g -n TAG_A
Level of tag(TAG_A) is: 3
sh>
sh>dlog_test
[6317] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[6317] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[6318] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]
sh>
sh>dlog_tlvl_ctrl -d -n TAG_A
Del tag(TAG_A) level success
sh>
sh>dlog_test
[8226] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[8226] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[8227] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[8227] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]

全局标签过滤器示例

本示例主要演示使用全局标签过滤器，使得只有这个标签的日志输出，运行结果如下：

sh>dlog_gtag_ctrl
Command format:
dlog_gtag_ctrl [-s | -g | -d] [-n tag name]
parameter Usage:
         -s     Set global tag option.
         -g     Get global tag option.
         -d     Delete global tag option.
         -n     Specify the global tag name.

sh>
sh>dlog_test
[1722] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[1722] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[1723] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[1723] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]
sh>
sh>dlog_gtag_ctrl -s -n TAG_A
Set global filter tag(TAG_A) of dlog success
sh>
sh>dlog_gtag_ctrl -g
The global filter tag of dlog is TAG_A
sh>
sh>dlog_test
[3800] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[3800] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
sh>
sh>dlog_gtag_ctrl -d
Del global filter tag of dlog success
sh>
sh>dlog_test
[5549] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[5549] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[5550] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[5550] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]

全局关键字使用示例

本示例主要演示使用关键字过滤器，使得只有带有这个关键字的日志输出，运行结果如下：

sh>dlog_gkw_ctrl
Command format:
dlog_gkw_ctrl [-s | -g | -d] [-k keyword]
parameter Usage:
         -s     Set global keyword option.
         -g     Get global keyword option.
         -d     Delete global keyword option.
         -k     Specify the gobal keyword.

sh>
sh>dlog_test
[1211] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[1211] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[1212] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[1212] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]
sh>
sh>dlog_gkw_ctrl -s -k WARNING
Set global filter keyword(WARNING) of dlog success
sh>
sh>dlog_gkw_ctrl -g
The global filter keyword of dlog is WARNING
sh>
sh>dlog_test
[5239] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[5239] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]
sh>
sh>dlog_gkw_ctrl -d
Del global filter keyword of dlog success
sh>
sh>dlog_test
[6485] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test][34]
[6485] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test][35]
[6486] E/TAG_B: TAG_B DLOG_ERROR [sh_dlog_test][39]
[6486] W/TAG_B: TAG_B DLOG_WARNING [sh_dlog_test][40]

部分编译示例代码

本示例代码使用部分编译宏打印了所有等级的日志，默认编译的等级为 INFO 级别，后续使用 shell 命令来展示部分编译的效果。

#include <oneos_config.h>
#include <shell.h>

#define DBG_EXT_TAG "TAG_A"
#define DBG_EXT_LVL DBG_EXT_INFO

#include <os_dbg_ext.h>

void sh_dlog_test_ext(os_int32_t argc, char **argv)
{
    LOG_EXT_E("TAG_A DLOG_ERROR");
    LOG_EXT_W("TAG_A DLOG_WARNING");
    LOG_EXT_I("TAG_A DLOG_INFO");
    LOG_EXT_D("TAG_A DLOG_DEBUG");
}
SH_CMD_EXPORT(dlog_test_ext, sh_dlog_test_ext, "test dlog tag level");

部分编译示例

本示例主要演示使用部分编译，默认编译的等级为 INFO 级别，由于 DEBUG 级别低于 INFO 级别，DEBUG 级别日志未加入编译。虽然调整全局过滤器为 DEBUG 级别，DEBUG 级别日志不会显示。运行结果如下：

sh>dlog_test_ext
[646] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test_ext][35]
[646] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test_ext][36]
sh>
sh>dlog_glvl_ctrl
Command format:
dlog_glvl_ctrl [-s | -g] [-l global level]
parameter Usage:
         -s     Set global level option.
         -g     Get global level option.
         -l     Specify a global level that want to be set.
                level: 3-error, 4-warning, 6-info, 7-debug
sh>
sh>dlog_glvl_ctrl -s -l 7
Set global level(7) of dlog success
sh>
sh>dlog_test_ext
[2455] E/TAG_A: TAG_A DLOG_ERROR [sh_dlog_test_ext][35]
[2455] W/TAG_A: TAG_A DLOG_WARNING [sh_dlog_test_ext][36]
[2456] I/TAG_A: TAG_A DLOG_INFO [sh_dlog_test_ext][37]