SDK提供了设备诊断服务, 当设备的MQTT建联信息、心跳信息和协议的收发延时超过一定的范围后发出告警信息。

功能说明

用户可以设置设备使用MQTT连接平台的正常时间、心跳信息和协议报文的收发延时,当延时超过指定的范围后进行本地报警或者通过日志上报物联网平台。

注意 只适用于使用MQTT连接物联网平台的设备。

API列表

以下是设备诊断的API列表及简要说明 (详见components/diag/aiot_diag_api.h)

接口名 说明
aiot_diag_init 初始化diag实例并设置默认参数
aiot_diag_setopt 配置diag选项, 详见Diag选项配置说明
aiot_diag_deinit 释放diag实例句柄的资源
aiot_diag_start 开始诊断SDK内部信息
aiot_diag_stop 停止诊断SDK内部信息

每个用户可设置的告警项均可使能或者失效,可设置的选项包括:

  • 是否向设备的事件回调函数中输出告警信息;
  • 是否将告警信息作为日志上报物联网平台;
  • MQTT连接时长告警配置,默认值超过800ms即会产生Warning级别的告警,超过1.5秒会产生Fatal级别的告警;
  • 心跳消息时长告警配置,
  • 系统消息时长告警配置,默认值超过600ms会产生Warning级别的告警,超过1秒会产生Fatal级别的告警

例程讲解

现对照components/diag/demos/diag_basic_demo.c例程, 分步骤讲解如何使用API

设置设备的三元组

例程使用的三元组是公用的, 所以应用于实际业务时, 请替换如下的TODO部分, 传入用户自己真实的三元组

    /* TODO: 替换为自己设备的producKey和deviceName */
    char *product_key       = "a13FN5TplKq";
    char *device_name       = "diag_basic_demo";
			

进入程序入口, 给SDK配置全局的底层依赖和日志回调

底层依赖描述了硬件平台的资源使用方式, 比如怎样获取时钟, 分配内存等, 日志回调是用户的函数, SDK有log输出的时候会进入这个函数

int main(int argc, char *argv[])
{
    ...
    ...
    /* 配置SDK的底层依赖 */
    aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
    /* 配置SDK的日志输出 */
    aiot_state_set_logcb(demo_state_logcb);
			

给Diag会话配置参数

这些连接参数包括用于上报诊断信息的MQTT句柄和输出SDK内部诊断信息的事件回调函数,SDK为诊断模块设置了默认的阈值,这些阈值可通过aiot_diag_setopt进行配置, 具体的配置方法可参考aiot_diag_setoptDiag选项配置说明

    /* 创建1个MQTT客户端实例并内部初始化默认参数 */
    mqtt_handle = aiot_mqtt_init();
    if (mqtt_handle == NULL) {
        printf("aiot_mqtt_init failed\n");
        return -1;
    }

    diag_handle = aiot_diag_init();
    if (diag_handle == NULL) {
        printf("aiot_diag_init failed\n");
        return -1;
    }

    aiot_diag_setopt(diag_handle, AIOT_DIAGOPT_MQTT_HANDLE, mqtt_handle);
    aiot_diag_setopt(diag_handle, AIOT_DIAGOPT_EVENT_HANDLER, demo_diag_event_handler);

    /* 开始诊断SDK内部信息 */
    aiot_diag_start(diag_handle);

    /* 建立MQTT连接, 并开启保活线程和接收线程 */
    res = demo_mqtt_start(mqtt_handle, product_key, device_name, device_secret);
    if (res < 0) {
        printf("demo_mqtt_start failed\n");
        return -1;
    }
			

运行例程

当MQTT建联时长过长、心跳应答过慢或丢失、alink协议应答事件过长时,会触发告警,SDK会将告警信息上报至云端,可在控制台的日志服务中进行查看,下面以MQTT建联超时为例

EdendeMacBook-Pro:united-sdk edentao$ ./output/diag-basic-demo 
[1591956326.465][LK-0313] MQTT user calls aiot_mqtt_connect api, connect
[1591956326.465][LK-0317] diag_basic_demo&a13FN5TplKq
[1591956326.465][LK-0318] 26BB00DA74423B286612C969969E31FA2D8AA81AD606C52896DD81070758E0F7
establish mbedtls connection with server(host='a13FN5TplKq.iot-as-mqtt.cn-shanghai.aliyuncs.com', port=[443])
success to establish tcp, fd=5
success to establish mbedtls connection, fd = 5(cost 44957 bytes in total, max used 47869 bytes)
[1591956326.805][LK-0313] MQTT connect success in 340 ms
AIOT_MQTTEVT_CONNECT
AIOT_DIAGEVT_ALERT, module name: DiagMqttConnection, level: WARN, desc: MQTT connection establish time 340 ms
[1591956326.806][LK-0309] pub: /sys/a13FN5TplKq/diag_basic_demo/thing/log/post

[LK-030A] > 7B 22 69 64 22 3A 22 31  22 2C 22 76 65 72 73 69 | {"id":"1","versi
[LK-030A] > 6F 6E 22 3A 22 31 2E 30  22 2C 22 70 61 72 61 6D | on":"1.0","param
[LK-030A] > 73 22 3A 5B 7B 22 75 74  63 54 69 6D 65 22 3A 22 | s":[{"utcTime":"
[LK-030A] > 31 35 39 31 39 35 36 33  32 36 38 30 36 22 2C 22 | 1591956326806","
[LK-030A] > 6C 6F 67 4C 65 76 65 6C  22 3A 22 57 41 52 4E 22 | logLevel":"WARN"
[LK-030A] > 2C 22 6D 6F 64 75 6C 65  22 3A 22 44 69 61 67 4D | ,"module":"DiagM
[LK-030A] > 71 74 74 43 6F 6E 6E 65  63 74 69 6F 6E 22 2C 22 | qttConnection","
[LK-030A] > 63 6F 64 65 22 3A 22 31  36 22 2C 22 74 72 61 63 | code":"16","trac
[LK-030A] > 65 43 6F 6E 74 65 78 74  22 3A 22 31 22 2C 22 6C | eContext":"1","l
[LK-030A] > 6F 67 43 6F 6E 74 65 6E  74 22 3A 22 4D 51 54 54 | ogContent":"MQTT
[LK-030A] > 20 63 6F 6E 6E 65 63 74  69 6F 6E 20 65 73 74 61 |  connection esta
[LK-030A] > 62 6C 69 73 68 20 74 69  6D 65 20 33 34 30 20 6D | blish time 340 m
[LK-030A] > 73 22 7D 5D 7D                                   | s"}]}
			

上报的告警信息可在控制台的日志服务中查看