03 运维日志
AirCloud 运维日志功能
作者：孟伟
一、功能概述
AirCloud 是 LuatOS 物联网设备云服务通信协议，提供设备连接、数据上报、远程控制和文件上传等核心功能。excloud 扩展库是 AirCloud 协议的实现，通过该库设备可以快速接入aircloud云服务平台（iot.luatos.com），实现远程监控和管理。
1.1 运维日志功能介绍
运维日志功能是 AirCloud 的重要特性之一，专为设备远程运维和故障诊断设计，实现：
- 设备运行状态记录
- 故障信息捕获与上传
- 远程日志查看与分析
- 设备健康状况评估
二、准备环境
2.1 硬件环境
参考：硬件环境清单第二章节内容，准备以及组装好硬件环境。
2.2 软件环境
在开始实践本示例之前，先筹备一下软件环境：
- 烧录工具： Luatools 工具；
- 内核固件：本demo开发测试时使用的固件为Air780EHV V2032 版本固件，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版本的内核固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试；
- LuatOS 需要的脚本和资源文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EHM_Air780EHV_Air780EGH/demo/aircloud
三、API 接口说明
详细 API 文档请参考：https://docs.openluat.com/osapi/ext/excloud/
四、运维日志功能实现
4.1 核心代码示例
--[[
本demo演示了excloud扩展库的运维日志功能，包括：
1. 设备连接与认证
2. 运维日志记录
3. 运维日志上传
4. 日志上传状态监听
]]
-- 导入excloud库
local excloud = require("excloud")
-- 注册回调函数
function on_excloud_event(event, data)
log.info("用户回调函数", event, json.encode(data))
if event == "connect_result" then
if data.success then
log.info("连接成功")
sys.publish("aircloud_connected")
else
log.info("连接失败: " .. (data.error or "未知错误"))
end
elseif event == "auth_result" then
if data.success then
log.info("认证成功")
else
log.info("认证失败: " .. data.message)
end
elseif event == "disconnect" then
log.warn("与服务器断开连接")
elseif event == "reconnect_failed" then
log.info("重连失败，已尝试 " .. data.count .. " 次")
elseif event == "mtn_log_upload_start" then
log.info("运维日志上传开始", "文件数量:", data.file_count)
elseif event == "mtn_log_upload_progress" then
log.info("运维日志上传进度",
"当前文件:", data.current_file,
"总数:", data.total_files,
"文件名:", data.file_name,
"状态:", data.status)
elseif event == "mtn_log_upload_complete" then
log.info("运维日志上传完成",
"成功:", data.success_count,
"失败:", data.failed_count,
"总计:", data.total_files)
end
end
-- 注册回调
excloud.on(on_excloud_event)
-- 主任务函数
function excloud_task_func()
-- 如果当前时间点设置的默认网卡还没有连接成功，一直在这里循环等待
while not socket.adapter(socket.dft()) do
log.warn("excloud_task_func", "wait IP_READY", socket.dft())
-- 在此处阻塞等待默认网卡连接成功的消息"IP_READY"
-- 或者等待1秒超时退出阻塞等待状态;
-- 注意：此处的1000毫秒超时不要修改的更长；
-- 因为当使用exnetif.set_priority_order配置多个网卡连接外网的优先级时，会隐式的修改默认使用的网卡
-- 当exnetif.set_priority_order的调用时序和此处的socket.adapter(socket.dft())判断时序有可能不匹配
-- 此处的1秒，能够保证，即使时序不匹配，也能1秒钟退出阻塞状态，再去判断socket.adapter(socket.dft())
sys.waitUntil("IP_READY", 1000)
end
-- 配置excloud参数，启用运维日志功能
local ok, err_msg = excloud.setup({
use_getip = true, -- 使用getip服务
device_type = 1, -- 4G设备
auth_key = "VmhtOb81EgZau6YyuuZJzwF6oUNGCbXi",
transport = "tcp", -- 使用TCP传输
auto_reconnect = true, -- 自动重连
reconnect_interval = 10, -- 重连间隔(秒)
max_reconnect = 5, -- 最大重连次数
mtn_log_enabled = true, -- 启用运维日志
mtn_log_blocks = 2, -- 日志文件块数
mtn_log_write_way = excloud.MTN_LOG_CACHE_WRITE -- 缓存写入方式
})
if not ok then
log.info("初始化失败: " .. err_msg)
return
end
log.info("excloud初始化成功")
-- 开启excloud服务
local ok, err_msg = excloud.open()
if not ok then
log.info("开启excloud服务失败: " .. err_msg)
return
end
log.info("excloud服务已开启")
-- 启动自动心跳，默认5分钟一次的心跳
excloud.start_heartbeat()
log.info("自动心跳已启动")
-- 记录启动日志
excloud.mtn_log("system", "设备启动完成", "version", "1.0.0")
-- 主循环：定期记录运维日志
while true do
-- 每1秒记录一次运维日志
sys.wait(1000)
-- 检查连接状态
local status = excloud.status()
if status.is_connected then
-- 记录运行状态日志
excloud.mtn_log("runtime", "设备运行中", "signal", "22", "battery", "95%")
end
end
end
-- 运维日志测试示例
function mtnlog_test_task()
local test_count = 0
while true do
test_count = test_count + 1
excloud.mtn_log("mtn_test", test_count)
-- 每1秒记录一次
sys.wait(1000)
end
end
-- 启动主任务
sys.taskInit(excloud_task_func)
-- 启动运维日志测试任务
sys.taskInit(mtnlog_test_task)
4.2 代码解析
4.2.1 回调函数注册
回调函数用于处理 AirCloud 的各种事件，特别是与运维日志相关的事件：
mtn_log_upload_start: 运维日志上传开始mtn_log_upload_progress: 运维日志上传进度mtn_log_upload_complete: 运维日志上传完成
这些事件可以用于监控日志上传的状态和结果。
4.2.2 运维日志配置
在 excloud.setup() 中配置运维日志相关参数：
mtn_log_enabled: 是否启用运维日志功能（必须设置为 true）mtn_log_blocks: 每个日志文件的大小（单位：block，通常 1 block = 4KB）mtn_log_write_way: 日志写入方式（excloud.MTN_LOG_CACHE_WRITE表示缓存写入）
4.2.3 运维日志记录
使用 excloud.mtn_log() 函数记录运维日志。
4.2.4 运维日志上传
运维日志上传由云端触发，当云平台下发日志上传指令时，设备会自动执行以下操作：
- 扫描所有运维日志文件
- 按顺序上传日志文件
- 通过回调函数通知上传状态
五、运维日志存储机制
5.1 文件结构
运维日志使用 4 个循环文件存储：
"/hzmtn1.trc" -- 文件1
"/hzmtn2.trc" -- 文件2
"/hzmtn3.trc" -- 文件3
"/hzmtn4.trc" -- 文件4
5.2 存储空间管理
- 默认大小：每个文件占用 1 个 block（通常 4KB），4 个文件共 4 个 block（16KB）
- 可配置：通过
mtn_log_blocks参数调整每个文件的大小 - 覆盖机制：采用循环覆盖机制，当文件写满时，会从第一个文件开始覆盖
5.3 上报逻辑
-- 设备端：等待云端触发上传
-- 云端下发信令25（MTN_LOG_UPLOAD_REQ_SIGNAL）时触发上传
-- 上传流程：
-- 1. 设备收到上传请求
-- 2. 扫描4个运维日志文件
-- 3. 按文件序号顺序上传
-- 4. 发送上传状态通知
六、云平台配置
6.1 平台配置步骤
- 需要先登录合宙 IOT 平台，如下图所示，没有账号的，可以先注册一个。客户向合宙采购 4G 模块时，如果采购人员没有告知合宙这批模块放在 iot 平台 上的哪个产品下，则合宙会以采购人的手机号为账号，默认密码 888888，创建一个"合宙标准模块"的项目，此次采购的所有模块都会放在这个项目下。
- 创建新项目或选择现有项目并获取项目 key (auth_key)，并将获取的项目 key 配置在代码中。
代码中配置过程如下：
- 然后同样的账号登录 iot.luatos.com 平台中查看设备上报报文。
七、功能验证
7.1 Luatools 日志查看
通过 Luatools 工具可以查看设备的运行日志，确认运维日志记录和上传是否正常：
运维日志记录日志：
7.2 下发运维日志指令
在云平台上下发运维日志上传指令：
7.3 设备收到日志上传指令
设备端日志显示收到上传指令：
依次上传文件，同时显示进度，上传完成后，设备会发送完成通知：
7.4 云平台查看运维日志
在云平台上点击更新，查看最新上传的运维日志：
同时可以点击小眼睛图标在线查看或者下载到本地查看：
八、常见问题与解决方案
8.1 运维日志上传失败
原因分析：
- 网络连接不稳定
- 日志文件损坏
解决方案：
- 检查网络连接状态
- 重启设备尝试重新生成日志文件
8.2 运维日志内容不完整
原因分析：
- 日志文件被循环覆盖
- 设备存储空间不足
- 日志写入失败
解决方案：
- 增加
mtn_log_blocks参数值，扩大日志文件大小 - 减少日志记录频率
- 检查设备存储空间状态
8.3 运维日志上传缓慢
原因分析：
- 网络带宽限制
- 日志文件过大
- 设备处理能力不足
解决方案：
- 优化网络连接
- 合理设置日志记录频率和内容
- 减少单次上传的日志量
九、总结
运维日志功能是 AirCloud 提供的强大工具，为物联网设备的远程运维和故障诊断提供了有力支持。通过合理使用运维日志功能，可以：
- 快速定位和解决设备故障
- 实时监控设备运行状态
- 积累设备运行数据，为产品优化提供依据
- 降低运维成本，提高设备可靠性
通过本教程的学习，用户可以快速掌握 AirCloud 运维日志功能的使用方法，为物联网设备的稳定运行保驾护航。