04 日志输出(log)

作者：王世豪

一、LuatOS 日志输出介绍

LuatOS 使用 log 核心库进行日志输出，通过 log 库可以输出不同等级的用户日志；

1.1 日志的等级（日志输出函数）

日志的等级指的是日志输出函数本身的级别：

debug：调试内容输出，为日志输出优先级第 4 等级，优先级最低；

info：信息输出，为日志输出优先级第 3 等级，仅比 debug 级别高；

warn：警告输出，为日志输出优先级第 2 等级；

error：错误输出，为日志输出优先级第 1 等级，级别最高；

注：LuatOS 默认日志等级是 debug，可以输出 debug 及以上等级的日志；

如：log.debug(PROJECT, "debug message")，debug 为 log 模块的函数，使用小写英文字母；

1.2 日志输出等级（日志过滤级别）

日志输出等级指的是通过 log.setLevel() 设置的过滤级别，用于控制哪些级别的日志会被实际输出：

SILENT： 静默所有日志，即禁止日志有任何内容输出；

DEBUG： 输出 debug 及以上级别的日志；

INFO： 输出 info 及以上级别的日志；

WARN： 输出 warn 及以上级别的日志；

ERROR： 输出 error 级别的日志；

如：log.setLevel("INFO")，INFO 作为 setLevel 函数的参数存在，使用大写英文字母；

1.3 重要区别

debug（小写）：指的是 log.debug() 函数，用于输出 debug 级别的日志内容；

DEBUG（大写）：指的是 log.setLevel("DEBUG") 参数，用于设置输出 debug 及以上级别的日志；

其他级别（info/INFO、warn/WARN、error/ERROR）同理；

使用过程要注意大小写的区别，它们在不同的上下文中具有不同的作用；

1.4 使用关系

日志输出等级决定了哪些日志等级的日志会被实际输出：

当设置 log.setLevel("INFO") 时：

log.debug() 的日志不会被输出（因为 debug < info）
log.info()、log.warn()、log.error() 的日志会被输出

当设置 log.setLevel("ERROR") 时：

只有 log.error() 的日志会被输出
log.debug()、log.info()、log.warn() 的日志不会被输出

二、演示功能概述

本文使用 Air780EPM/EHM 核心板，输出不同日志等级，以便开发者能快速了解日志功能的使用。

三、准备硬件环境

3.1 Air780EHV 核心板

使用 Air780EHV 核心板，如下图所示：

此核心板的详细使用说明参考：硬件手册和证书中的 Air780EHV 核心板使用说明。

3.2 PC 电脑

WINDOWS 系统，其他暂无特别要求；

3.3 数据通信线

USB 数据线（其一端为 Type-C 接口，用于连接 Air780EHV 核心板）。

Air780EHV 核心板和数据线的硬件接线方式为：

Air780EHV 核心板通过 TYPE-C USB 口供电，核心板正面的 ON/OFF 拨动开关拨到 ON 一端；
TYPE-C USB 数据线直接插到核心板的 TYPE-C USB 座子，另外一端连接电脑 USB 口；

四、准备软件环境

4.1 软件环境

烧录工具：Luatools 下载调试工具
内核固件：Air780EHV 固件
脚本文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EHM_Air780EHV_Air780EGH/demo/log
LuatOS 运行所需要的 lib 文件：使用 Luatools 烧录时，勾选添加默认 lib 选项，使用默认 lib 脚本文件。

准备好软件环境之后，接下来查看如何烧录项目文件到 Air780EHV 核心板中，将本篇文章中演示使用的项目文件烧录到 Air780EPM/EHM 核心板中。

4.2 API 介绍

log 库：https://docs.openluat.com/osapi/core/log/

五、程序结构

log/
├── main.lua
├── log_test.lua
|── readme.md

5.1 文件说明

main.lua：主程序入口文件。
log_test.lua：演示不同日志输出等级的示例代码。

六、代码详解

6.1 main.lua

主程序文件 main.lua 是整个项目的入口点。它负责初始化系统环境。

6.2 log_test.lua

--[[
@module  log_test
@summary log功能测试模块
@version 1.0
@date    2025.11.19
@author  王世豪
@usage
本demo演示的核心功能为：
1. log.debug 日志等级测试
2. log.info 日志等级测试
3. log.warn 日志等级测试
4. log.error 日志等级测试

]]

local function test_log_output(level_name)
    print(string.format("测试日志级别: %s", level_name))

    log.debug(PROJECT, "debug message") 
    log.info(PROJECT, "info message")
    log.warn(PROJECT, "warn message")
    log.error(PROJECT, "error message")
end

local function logtest_task()
    -- 打印当前默认日志输出等级
    local default_level = log.getLevel()
    print("日志功能测试开始")
    print(string.format("默认日志级别: %s", default_level))

    -- 实验1：使用默认日志输出等级测试
    test_log_output(default_level)

    -- 实验2：设置为INFO级别，只输出info及以上级别的日志
    log.setLevel("INFO")
    test_log_output("INFO")

    -- 实验3：设置为WARN级别，只输出warn及以上级别的日志
    log.setLevel("WARN")
    test_log_output("WARN")

    -- 实验4：设置为ERROR级别，只输出error级别的日志
    log.setLevel("ERROR")
    test_log_output("ERROR")

    -- 实验5：设置为SILENT级别，完全关闭日志输出
    log.setLevel("SILENT")
    test_log_output("SILENT")

    -- 实验6：恢复默认日志输出等级，验证日志输出恢复
    log.setLevel(default_level)
    print("恢复默认日志输出等级: " .. log.getLevel())

    -- 测试不同参数类型的日志输出
    log.info(PROJECT, "数值:", 123, "布尔值:", true, "表:", {name="test", value=456})
end

-- 启动测试任务
sys.taskInit(logtest_task)

七、运行结果展示

注：详细日志输出内容，在程序中有增强注释说明，请详细查看。

八、总结

至此，我们已使用 Air780EHV 核心板验证了不同日志输出等级下的日志打印效果。