linux环境下ulog,ulog日志

环境下ulog,ulog日志"/>

linux环境下ulog,ulog日志

ulog 日志

ulog 简介

日志的定义：日志是将软件运行的状态、过程等信息，输出到不同的介质中(例如：文件、控制台、显示屏等)，并进行显示和保存。为软件调试、维护过程中的问题追溯、性能分析、系统监控、故障预警等功能，提供参考依据。可以说，日志的使用，几乎占用的软件生命周期的至少 80% 的时间。

日志的重要性：对于操作系统而言，由于其软件的复杂度非常大，单步调试在一些场景下并不适合，所以日志组件在操作系统上几乎都是标配。完善的日志系统也能让操作系统的调试事半功倍。

ulog 的起源: RT-Thread 一直缺少小巧、实用的日志组件，而 ulog 的诞生补全了这块的短板。它将作为 RT-Thread 的基础组件被开源出来，让我们的开发者也能用上简洁易用的日志系统，提高开发效率。

ulog 是一个非常简洁、易用的 C/C++ 日志组件，第一个字母 u 代表 μ，即微型的意思。它能做到最低ROM<1K, RAM<0.2K的资源占用。ulog 不仅有小巧体积，同样也有非常全面的功能，其设计理念参考的是另外一款 C/C++ 开源日志库：EasyLogger(简称 elog)，并在功能和性能等方面做了非常多的改进。主要特性如下：

日志输出的后端多样化，可支持例如：串口、网络，文件、闪存等后端形式。

日志输出被设计为线程安全的方式，并支持异步输出模式。

日志系统高可靠，在中断 ISR 、Hardfault 等复杂环境下依旧可用。

日志支持运行期 / 编译期设置输出级别。

日志内容支持按关键词及标签方式进行全局过滤。

API 和日志格式可兼容 linux syslog。

支持以 hex 格式 dump 调试数据到日志中。

兼容 rtdbg (RTT 早期的日志头文件)及 EasyLogger 的日志输出 API。

ulog 架构

下图为 ulog 日志组件架构图：

前端：该层作为离应用最近的一层，给用户提供了 syslog 及 LOG_X 两类 API 接口，方便用户在不同的场景中使用。

核心：中间核心层的主要工作是将上层传递过来的日志，按照不同的配置要求进行格式化与过滤然后生成日志帧，最终通过不同的输出模块，输出到最底层的后端设备上。

后端：接收到核心层发来的日志帧后，将日志输出到已经注册的日志后端设备上，例如：文件、控制台、日志服务器等等。

配置选项

ENV 工具中使用 menuconfig 配置 ulog 的路径如下所示：

RT-Thread Components → Utilities → Enable ulog

ulog 配置选项说明如下所示，一般情况下使用默认配置即可：

[*] Enable ulog /* 使能 ulog */

The static output log level./* 选择静态的日志输出级别。选择完成后，比设定级别低的日志(这里特指使用 LOG_X API 的日志)将不会被编译到 ROM 中 */

[ ] Enable ISR log. /* 使能中断 ISR 日志，即在 ISR 中也可以使用日志输出 API */

[*] Enable assert check. /* 使能断言检查。关闭后，断言的日志将不会被编译到 ROM 中 */

(128) The log's max width. /* 日志的最大长度。由于 ulog 的日志 API 按行作为单位，所以这个长度也代表一行日志的最大长度 */

[ ] Enable async output mode. /* 使能异步日志输出模式。开启这个模式后，日志不会立刻输出到后端，而是先缓存起来，然后交给日志输出线程(例如：idle 线程)去输出 */

log format ---> /* 配置日志的格式，例如：时间信息，颜色信息，线程信息，是否支持浮点等等 */

[*] Enable console backend. /* 使能控制台作为后端。使能后日志可以输出到控制台串口上。建议保持开启。 */

[ ] Enable runtime log filter. /* 使能运行时的日志过滤器，即动态过滤。使能后，日志将支持按标签、关键词等方式，在系统运行时进行动态过滤。 */

配置日志的格式(log format)选项描述如下所示：

[ ] Enable float number support. It will using more thread stack. /* 浮点型数字的支持(传统的 rtdbg/rt_kprintf 均不支持浮点数日志) */

[*] Enable color log. /* 带颜色的日志 */

[*] Enable time information. /* 时间信息 */

[ ] Enable timestamp format for time. /* 包括时间戳 */

[*] Enable level information. /* 级别信息 */

[*] Enable tag information. /* 标签信息 */

[ ] Enable thread information. /* 线程信息 */

日志级别

日志级别代表了日志的重要性，在 ulog 中由高到低，有如下几个日志级别：

级别

名称

描述

LOG_LVL_ASSERT

断言

发生无法处理、致命性的的错误，以至于系统无法继续运行的断言日志

LOG_LVL_ERROR

错误

发生严重的、不可修复的错误时输出的日志属于错误级别日志

LOG_LVL_WARNING

警告

出现一些不太重要的、具有可修复性的错误时，会输出这些警告日志

LOG_LVL_INFO

信息

给本模块上层使用人员查看的重要提示信息日志，例如：初始化成功，当前工作状态等。该级别日志一般在量产时依旧保留

LOG_LVL_DBG

调试

给本模块开发人员查看的调试日志，该级别日志一般在量产时关闭

在 ulog 中日志级别还有如下分类：

静态级别与动态级别：按照日志是否可以在运行阶段修改进行分类。可在运行阶段修改的称之为动态级别，只能在编译阶段修改的称之为静态级别。比静态级别低的日志(这里特指使用 LOG_X API 的日志)将不会被编译到 ROM 中，最终也不会输出、显示出来。而动态级别可以管控的是高于或等于静态级别的日志。在 ulog 运行时，比动态级别低的日志会被过滤掉。

全局级别与模块级别：按照作用域进行的分类。在 ulog 中每个文件(模块)也可以设定独立的日志级别。全局级别作用域大于模块级别，也就是模块级别只能管控那些高于或等于全局级别的模块日志。

综合上面分类可以看出，在 ulog 可以通过以下 4 个方面来设定日志的输出级别：

全局静态日志级别：在 menuconfig 中配置，对应 ULOG_OUTPUT_LVL 宏。

全局动态日志级别：使用 void ulog_global_filter_lvl_set(rt_uint32_t level) 函数来设定。

模块静态日志级别：在模块(文件)内定义 LOG_LVL 宏，与日志标签宏 LOG_TAG 定义方式类似。

模块动态日志级别：使用 int ulog_tag_lvl_filter_set(const char *tag, rt_uint32_t level) 函数来设定。

它们的作用范围关系为：全局静态>全局动态>模块静态>模块动态。

日志标签

由于日志输出量的不断增大，为了避免日志被杂乱无章的输出出来，就需要使用标签(tag)给每条日志进行分类。标签的定义是按照模块化的方式，例如：Wi-Fi 组件包括设备驱动(wifi_driver)、设备管理(wifi_mgnt)等模块，则 Wi-Fi 组件内部模块可以使用 wifi.driver、wifi.mgnt 等作为标签，进行日志的分类输出。

每条日志的标签属性也可以被输出并显示出来，同时 ulog 还可以设置每个标签(模块)对应日志的输出级别，当前不重要模块的日志可以选择性关闭，不仅降低 ROM 资源，还能帮助开发者过滤无关日志。

参见 rt-thread\examples\ulog_example.c ulog 例程文件，在文件顶部有定义 LOG_TAG 宏：

#define LOG_TAG "example" // 该模块对应的标签。不定义时，默认：NO_TAG

#define LOG_LVL LOG_LVL_DBG // 该模块对应的日志输出级别。不定义时，默认：调试级别

#include // 必须在 LOG_TAG 与 LOG_LVL 下面

需要注意的，定义日志标签必须位于 #include 的上方，否则会使用默认的 NO_TAG(不推荐定义在头文件中定义这些宏)。

日志标签的作用域是当前源码文件，项目源代码通常也会按照模块进行文件分类。所以在定义标签时，可以指定模块名、子模块名作为标签名称，这样不仅在日志输出显示时清晰直观，也能方便后续按标签方式动态调整级别或过滤。

日志初始化

初始化

int ulog_init(void)

返回

描述

>=0

成功

-5

失败，内存不足

在使用 ulog 前必须调用该函数完成 ulog 初始化。如果开启了组件自动初始化，该函数也将被自动调用。

去初始化

void ulog_deinit(void)

当 ulog 不再使用时，可以执行该 deinit 释放资源。

日志输出 API

ulog 主要有两种日志输出宏 API，源代码中定义如下所示：

#define LOG_E(...) ulog_e(LOG_TAG, __VA_ARGS__)

#define LOG_W(...) ulog_w(LOG_TAG, __VA_ARGS__)

#define LOG_I(...) ulog_i(LOG_TAG, __VA_ARGS__)

#define