errDump - 错误上报

作者：孟伟

一、概述

LuatOS 异常日志上报功能模块名叫：errDump，errDump 对"量产投放市场的设备，远程调试初步定位问题"至关重要，强烈建议客户一定要使用此功能

原理：errDump 就是将模块运行过程中产生的异常信息或者用户调试日志通过 UDP 上报到互联网上的指定服务器，技术人员可以在服务器上查阅日志，协助远程了解设备运行情况，或者故障诊断。

支持日志自动上报到合宙IOT平台，也支持自动上报到用户自己的UDP服务器，也支持手动读取出异常日志，通过tcp或者串口发送出去使用合宙云服务器时，迫于服务器压力，只有在iot平台手动打开 debug 开关，才有日志上报。需要注意的是，使用自动上报到自己的UDP服务器时，收到上报的errdump日志需要返回一个大写的“OK”，否则模组会认为没有上报成功，会重复上报。

下面是使用errdump的几种情况：

1.1 errDump有什么用？

errDump是LuatOS系统中的异常日志上报模块，主要用于远程调试与故障诊断。其核心价值体现在：

实时监控设备状态：将设备运行时的错误信息或用户调试日志通过UDP协议上报到指定服务器。
支持量产设备维护：对于已投放市场的设备，无需现场调试即可远程定位问题，显著降低维护成本。
灵活配置：用户可自定义上报周期、服务器地址及日志类型，适应不同场景需求。

1.2 errDump中存储的错误信息及日志类型

目前errdump支持2类错误日志的储存与上报：

1. errDump.TYPE_SYS

系统异常日志是指程序运行过程中产生的异常信息，例如程序崩溃、内存泄漏、死循环、脚本错误等。系统异常日志会自动写入到errDump模块中，如果使用自动上报到iot平台则在异常重启后会自动读取并上报，如果是自行读取上报的话可通过errDump.dump(buff,errDump.TYPE_SYS, ture) 来读取系统异常日志并根据自己需求自定义传输。

2. errDump.TYPE_USR

用户自行写入调试日志是通过 errDump.record() 接口来保存的，如果设置了定时上报周期的话则会定期上报到服务器中，如果自行读取上报的话可以通过 errDump.dump(buff, errDump.TYPE_USR, true) 来读取用户写入的调试日志并根据自己需求自定义传输。

1.3 存储区域与空间管理

日志文件都是储存在文件系统中。

errDump.TYPE_SYS和errDump.TYPE_USR的日志文件最大分别都是4KB；日志达到4KB时，新写入内容覆盖旧数据。

1.4 日志上报与读取方式

1. 自动上报

通过errDump.config(enable, period, user_flag, custom_id, host, port)配置服务器地址和周期(默认600秒)。上报成功后，本地日志自动清空。

--每小时上报到一次
errDump.config(true, 3600, nil, nil, "dev_msg1.openluat.com", 12425)

2. 手动读取使用errDump.dump(zbuff, type, isDelete)读取日志，支持指定类型（如系统日志、用户日志）并选择是否删除。

3. 自定义传输

禁用自动上报后，用户可通过errDump.dump()获取日志内容，再通过MQTT、TCP、UART等方式发送出去。

1.5 日志清除机制

1. 自动清除：

设置自动模式的话，上报到服务器成功后，本地日志自动删除。

2. 手动清除：

设置手动读取模式，调用errDump.dump(nil, type, true)指定日志类型并删除。

3. 覆盖策略：

系统/用户日志达到4KB时，新写入内容覆盖旧数据。

二、核心示例

1、核心示例是指：使用本库文件提供的核心API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的demo，请参考 LuatOS仓库中各个产品目录下的demo/errDump

示例

-- 基本用法, 10分钟上报一次,如果有需要上报的数据.
if errDump then
    errDump.config(true, 600)
end

-- 默认上报到合宙服务器 dev_msg1.openluat.com 端口 12425
-- 查看上报的数据，登录iot.openluat.com，选择调试日志，输入IMEI，选择好时间段，点搜索

三、常量详解

核心库常量，顾名思义是由合宙LuatOS内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

3.1 errDump.TYPE_SYS

常量含义：系统异常日志类型标识，用于读取由系统自动捕获的运行时的异常日志(如程序崩溃、内存泄漏、死循环、脚本错误等)
数据类型：number；
取值范围：0；
示例代码：errDump.dump(err_buff, errDump.TYPE_SYS)
注意事项：只在手动读取模式下使用。

3.2 errDump.TYPE_USR

常量含义：用户调试日志类型标识，用于读取通过 errDump.record() 接口手动写入的业务层日志
数据类型：number；
取值范围：1；
示例代码：errDump.dump(err_buff, errDump.TYPE_USR)
注意事项：只在手动读取模式下使用。

四、函数详解

errDump.dump(zbuff, type, isDelete)

功能

手动读取异常日志，主要用于用户将日志发送给自己的服务器而不是合宙IOT平台，如果在errDump.config配置了周期上传，则不能使用本函数

参数

zbuff

参数含义：日志信息缓存区，用于存储读取到的日志数据
数据类型：zbuff 或 nil
取值范围：有效的 zbuff 对象或 nil
是否必选：否
注意事项：如果为 nil，则不会读出日志数据。
参数示例：local buff = zbuff.create(4096)  -- 创建 4KB 缓冲区
         errDump.dump(buff, errDump.TYPE_SYS, false)  -- 读取系统异常日志到 buff

type

参数含义：指定要读取的日志类型
数据类型：number
取值范围：errDump.TYPE_SYS或者errDump.TYPE_USR
是否必选：是
注意事项：仅支持两种常量值，errDump.TYPE_SYS和errDump.TYPE_USR。
参数示例：errDump.dump(buff, errDump.TYPE_USR, false)  -- 读取用户自定义异常日志到 buff

isDelete

参数含义：是否删除日志
数据类型：boolean
取值范围：true删除，false不删除
是否必选：是
注意事项：暂无
参数示例：false

返回值

local result = errDump.dump(buff, errDump.TYPE_SYS, false)

有一个返回值 result

result

含义说明：true表示从上次读取完到本次读取中间有写入数据，false表示从上次读取完到本次读取中间没有写入数据；
         是否读取到数据，可以通过zbuff:used()的长度去判断。
数值类型：boolean
取值范围：true或false
注意事项：如果不是读取完立马删除，那么在删除日志前，最好再读一下确保没有新的数据写入了

示例

--读出系统记录的异常日志
local new_flag = errDump.dump(err_buff, errDump.TYPE_USR)
    if err_buff:used() > 0 then
        log.info(err_buff:toStr(0, err_buff:used()))    -- 打印出异常日志
        --清除用户记录的调试日志
        errDump.dump(nil, errDump.TYPE_USR, true)
    else
        log.info("没有新数据")
    end

errDump.record(message)

功能

写入用户自定义日志，注意最大只有4KB，超过部分新的覆盖旧的，开启自动上传后会上传到合宙IOT平台

参数

message

参数含义：日志内容
数据类型：string
取值范围：任意长度的字符串
是否必选：是
注意事项：日志内容不能超过4KB，否则会被截断。
参数示例："socket long time no connect"

返回值

无

示例

errDump.record("socket long time no connect") --记录下"socket long time no connect"

errDump.config(enable, period, user_flag, custom_id, host, port)

功能

配置errdump日志记录功能，这里的日志包括引起luavm异常退出的日志和用户通过record写入的日志。

参数

enable

参数含义：是否启用errdump日志记录功能
数据类型：boolean
取值范围：true启用，false禁用
是否必选：是
注意事项：暂无
参数示例：true

period

参数含义：定时上传周期，单位秒，
数据类型：int
取值范围：0-65535，默认600秒，
是否必选：否
注意事项：这个是自动上传时候后的重试时间，在开机后或者有record操作后会很快尝试上传到合宙IOT平台一次；
         如果为0，则不会上传，由用户自己调用dump函数手动读取。
参数示例：600

user_flag

参数含义：用户的特殊标识
数据类型：nil或string
取值范围：任意长度的字符串
是否必选：否
注意事项：暂无
参数示例："123456"
         例如：以下是将 user_flag 配置为 "123456" 时上报的一条完整日志示例
         errdump_demo_LuatOS-SoC_V2014_Air8000,001.000.000,ABC,123456,
         poweron reason:3
         auto_dump_udp_srv.lua:40: attempt to index a nil value (global 'lllllllllog')
         stack traceback:
         auto_dump_udp_srv.lua:40: in function <auto_dump_udp_srv.lua:37>
         测试一下用户的调试日志记录功能

custom_id

参数含义：设备识别号
数据类型：nil或string
取值范围：如果为nil,则4G设备默认是imei,wifi设备默认STA MAC,其他设备默认是mcu.unique_id()接口获取的唯一id
         如果是string，则上报这个字符串
是否必选：否
注意事项：暂无
参数示例："ABC"
         例如：以下是将 custom_id 配置为 "ABC" 时上报的一条完整日志示例
         errdump_demo_LuatOS-SoC_V2014_Air8000,001.000.000,ABC,123456,
         poweron reason:3
         auto_dump_udp_srv.lua:40: attempt to index a nil value (global 'lllllllllog')
         stack traceback:
         auto_dump_udp_srv.lua:40: in function <auto_dump_udp_srv.lua:37>
         测试一下用户的调试日志记录功能

host

参数含义：用户自定义UDP服务器域名或IP
数据类型：string
取值范围：任意长度的字符串
是否必选：否
注意事项：收到上报的errdump日志需要返回一个大写的“OK”，否则模组会认为没有上报成功，会重复上报。
参数示例："112.125.89.8"

port

参数含义：用户自定义UDP服务器端口
数据类型：int
取值范围：0-65535
是否必选：否
注意事项：收到上报的errdump日志需要返回一个大写的“OK”，否则模组会认为没有上报成功，会重复上报。
参数示例：46416

返回值

无

示例

--一个小时尝试上次一次，上传时会在imei后附加上12345678
errDump.config(true, 3600, "12345678")

--关闭记录功能，不再上传
errDump.config(false)

--记录，但是不会主动上传，由用户实现上传功能
errDump.config(true, 0)

-- 2023.09.22新增custom_id参数
--一个小时尝试上次一次，上传时使用自定义的设备识别号ABC
errDump.config(true, 3600, nil, "ABC")

-- 2023.12.8 新增host和port参数
errDump.config(true, 3600, nil, nil, "dev_msg1.openluat.com", 12425)

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 errDump 核心库。