深入理解LuatOS核心API之errDump：构建错误上报体系

在复杂多变的嵌入式运行环境中，程序异常难以完全避免。LuatOS通过其核心API之一的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秒)。上报成功后，本地日志自动清空。

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、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

示例

三、常量详解

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

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

3.1 errDump.TYPE_SYS

3.2 errDump.TYPE_USR

四、函数详解

errDump.dump(zbuff, type, isDelete)

功能

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

参数

zbuff

type

isDelete

返回值

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

有一个返回值 result

result

示例

errDump.record(message)

功能

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

参数

message

返回值

无

示例

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

功能

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

参数

enable

period

user_flag

custom_id

host

port

adapter

返回值

无

示例

五、模组支持说明

支持 LuatOS 开发的所有模组都支持 errDump 核心库。

今天的内容就分享到这里了~