sysSentry软件安装与使用

安装sysSentry巡检框架

环境准备

• 安装openEuler-20.03-LTS-SP4系统，安装方法参考 《安装指南》。
• 安装sysSentry需要使用root权限。

安装操作

1. 配置yum源

   在/etc/yum.repos.d/创建新的repo文件（eg. /etc/yum.repos.d/openEuler.repo），文件内容如下：

   [root@openEuler ~]# cat /etc/yum.repos.d/openEuler.repo
   [osrepo]
   name=osrepo
   baseurl=https://repo.openeuler.org/openEuler-20.03-LTS-SP4/OS/$basearch/
   enabled=1
   gpgcheck=0
   
   [everything]
   name=everything
   baseurl=https://repo.openeuler.org/openEuler-20.03-LTS-SP4/everything/$basearch/
   enabled=1
   gpgcheck=0
   
   [update]
   name=update
   baseurl=https://repo.openeuler.org/openEuler-20.03-LTS-SP4/update/$basearch/
   enabled=1
   gpgcheck=0
   
   [source]
   name=update
   baseurl=https://repo.openeuler.org/openEuler-20.03-LTS-SP4/source/
   enabled=1
   gpgcheck=0
   

2. 安装sysSentry

   [root@openEuler ~]# yum install -y sysSentry pyxalarm
   

启动sysSentry巡检框架

sysSentry巡检框架提供三个相互独立的服务：

1. xalarmd服务，用于汇总巡检插件的告警信息，并向已注册告警的用户转发告警信息。
2. sentryCollector服务，用于周期性采集系统数据并提供给巡检插件。
3. sysSentry服务，用于管理巡检插件的服务。

三个服务均由systemd进行控制，用户在启动sysSentry时可仅启动需要的系统服务即可。

启动xalarmd服务

适用场景

1. 当巡检插件使用libxalarm或pyxalarm软件提供的接口，进行告警上报时，需要启动xalarmd服务；
2. 如需使用以下sysSentry提供的插件，请启动xalarmd服务：
   • 平均阈值慢io检测插件 -- avg_block_io
   • AI阈值慢io检测插件 -- ai_block_io

xalarmd服务配置介绍

xalarmd服务配置的路径位于/etc/sysSentry/xalarm.conf，以下为配置参数：

用户可自行调整参数配置，或直接采用默认配置，默认配置内容如下：

[filter]
id_mask = 1001-1128

[log]
level=info

启动方式

[root@openEuler ~]# systemctl start xalarmd

启动后可查询运行状态，状态为running即为成功：

[root@openEuler ~]# systemctl status xalarmd

（可选）设置开机启动

[root@openEuler ~]# systemctl enable xalarmd

启动sentryCollector服务

适用场景

1. 当巡检插件使用pysentry_collect软件提供的接口采集系统数据时，需要启动sentryCollector服务，目前sentryCollector仅支持io数据采集，默认使用ebpf采集方式，详细信息可参考《二次开发指南》；
2. 如需使用以下sysSentry提供的插件，请启动sentryCollector服务：
   • 平均阈值慢io检测插件 -- avg_block_io
   • AI阈值慢io检测插件 -- ai_block_io

sentryCollector服务配置介绍

sentryCollector服务配置文件路径是/etc/sysSentry/collector.conf，以下为配置参数：

用户可自行调整参数配置，或直接采用默认配置，默认配置内容如下：

[common]
modules=io

[io]
period_time=1
max_save=10
disk=default

[log]
level=info

启动方式

[root@openEuler ~]# systemctl start sentryCollector

启动后可查询运行状态，状态为running即为成功：

[root@openEuler ~]# systemctl status sentryCollector

（可选）设置开机启动

[root@openEuler ~]# systemctl enable sentryCollector

启动sysSentry服务

适用场景

sysSentry服务为必须启动的服务。

sysSentry服务配置介绍

sysSentry服务配置的路径位于/etc/sysSentry/inspect.conf，以下为配置参数：

用户可自行调整参数配置，或直接采用默认配置，默认配置内容如下：

[inspect]
Interval=3

[log]
level=info

启动方式

[root@openEuler ~]# systemctl start sysSentry

启动后可查询运行状态，状态为running即为成功：

[root@openEuler ~]# systemctl status sysSentry

（可选）设置开机启动

[root@openEuler ~]# systemctl enable sysSentry

使用sysSentry巡检框架

sysSentry巡检框架的主要向用户提供两部分能力：

1. 管理巡检插件 -- 通过sentryctl命令同时管理多款巡检插件的生命周期、查看告警信息等能力。
2. 注册/订阅巡检插件告警事件 -- 通过对外接口订阅插件的告警，实时接收插件上报的告警内容。

管理巡检插件

管理插件配置介绍

sysSentry可同时管理一款或多款巡检插件，每一款巡检插件都有自己的配置文件，配置文件路径为/etc/sysSentry/tasks/[插件名].mod，以下为配置参数：

示例：

# avg_block_io插件的配置文件如下，路径/etc/sysSentry/tasks/avg_block_io.mod
[common]
enabled=yes
task_start=/usr/bin/python3 /usr/bin/avg_block_io
task_stop=pkill -f /usr/bin/avg_block_io
type=oneshot
alarm_id=1002
alarm_clear_time=5

巡检插件管理命令

sysSentry提供了用于管理巡检插件的命令 -- sentryctl，可以用于启动/停止巡检插件任务、查看巡检插件运行状态、查看巡检插件上报信息等功能。

1. 启动指定巡检任务

   [root@openEuler ~]# sentryctl start <module_name>
   

2. 终止指定巡检任务

   [root@openEuler ~]# sentryctl stop <module_name>
   

3. 列出所有已加载的巡检任务及状态

   [root@openEuler ~]# sentryctl list
   

4. 查询指定巡检任务的状态

   [root@openEuler ~]# sentryctl status <module_name>
   

   巡检任务共存在四种状态，每种状态的回显信息及对应介绍如下：

   状态	描述
   RUNNING	巡检任务正在运行
   WAITING	仅period类型巡检任务可设置此状态，表示period巡检任务等待下一次被调度执行
   EXITED	巡检任务尚未执行，或者oneshot类型的巡检任务执行结束处于此状态
   FAILED	巡检任务未拉起成功，或者巡检任务未正常退出

5. 重载指定巡检任务的配置

   当用户修改了巡检任务的配置文件/etc/sysSentry/tasks/<module_name>.mod时，可通过以下命令重载配置文件：

   [root@openEuler ~]# sentryctl reload <module_name>
   

6. 查询指定任务的告警信息

   [root@openEuler ~]# sentryctl get_alarm <module_name> [options]
   

   options可选参数及释义如下：

   参数	描述
   -s TIME_RANGE, --time_range TIME_RANGE	展示用户指定时间长度内的告警信息，TIME_RANGE为整形，单位秒，范围为0~2^31-1，默认值为10，即显示10秒内的告警信息
   -d, --detailed	打印详细告警信息

   以avg_block_io为例，输出如下：

   [root@openEuler ~]# sentryctl get_alarm avg_block_io -s 1 -d
   [
       {
       	"alarm_id": 1002,
           "alarm_type": "ALARM_TYPE_OCCUR",
           "alarm_level": "MINOR_ALM",
           "timestamp": "YYYY-mm-DD HH:MM:SS",
           "alarm_info": {
               "driver_name": "sda",
               "reason": "disk_slow",
               "block_stack": "bio",
               "io_type": "read",
               "alarm_source": "avg_block_io",
               "details": {
                   "latency": "gettag: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], rq_driver: [0,0,0,0,0,437.9,0,0,0,0,517,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], bio: [0,0,0,0,0,521.1,0,0,0,0,557.8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], wbt: [0,0,0,0,0,0,8.5,0,0,0,0,12.0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]",
                   "iodump": "gettag: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], rq_driver: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], bio: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], wbt: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]"
               }
           }
   	},
       ...
   ]
   

   结果中各字段介绍：

   字段	描述
   alarm_id	用户上报告警的id，范围为1001～1128
   alarm_type	告警的类型，共两种： 1. ALARM_TYPE_OCCUR，告警产生 2. ALARM_TYPE_RECOVER，故障恢复
   alarm_level	告警的等级，共三级： 1. MINOR_ALM，一般告警，系统存在异常，并且已经尝试自动隔离等方式修复 2. MAJOR_ALM，严重告警，系统存在异常，需要通过重启等方式修复 3. CRITICAL_ALM，致命告警，系统或硬件存在无法修复问题，建议更换
   timestamp	告警上报的时间
   alarm_info	告警内容详细信息，由插件自定义，不同的巡检插件上报的内容不一致，其中details信息仅在指定"-d,--detailed"字段时展示

7. 查询指定巡检任务的巡检结果

   [root@openEuler ~]# sentryctl get_result <module_name>
   

   回显信息格式为json格式，内容格式如下：

   {
       "result": "xxx",
       "start_time": "YYYY-mm-DD HH:MM:SS",
       "end_time": "YYYY-mm-DD HH:MM:SS",
       "error_msg" : "xxx",
       "details":{}  # detail信息因巡检任务不同而不同，具体信息由巡检模块提供
   }
   

   其中"result"和"error_msg"对应关系如下：

   result	对应error_msg信息	含义
   PASS	""	巡检任务正常运行结束，无异常
   SKIP	"not supported.maybe some rpm package not be installed."	因缺少依赖、环境不支持等原因跳过/未执行巡检任务
   FAIL	"FAILED. config may be incorrect or the command may be invalid/killed!"	因执行命令错误等原因，巡检任务执行失败
   MINOR_ALM	"the command output shows that the status is 'INFO' or 'GENERAL_WARN'."	巡检任务结束，存在系统存在异常，并且已经尝试自动隔离等方式完成修复
   MAJOR_ALM	"the command output shows that the status is 'WARN' or 'IMPORTANT_WARN'."	巡检任务结束，系统存在异常，需要通过重启等方式修复
   CRITICAL_ALM	"the command output shows that the status is 'FAIL' or 'EMERGENCY_WARN'."	巡检任务结束，致命告警，系统或硬件存在无法修复问题，建议更换

订阅巡检插件告警事件

用户可通过创建新的进程订阅并接收告警上报内容，提供python与c两种语言的对外接口。

使用限制

1. 一个进程仅可订阅一次，不支持一个进程订阅多次告警。
2. 支持订阅的告警id范围为1001-1128，其中1001为内存巡检告警事件，1002为慢IO告警事件，其他告警id为用户自定义插件告警事件。
3. 告警模块目前支持多用户订阅，最大支持100个进程同时订阅告警消息，其中sysSentry getalarm功能固定占用一个进程资源。

python代码注册并获取告警内容

需要安装pyxalarm软件包：

[root@openEuler ~]# yum install -y pyxalarm

结构体 告警消息结构体定义

class Xalarm:
    def __init__(self, alarm_id, alarm_type, alarm_level,
                 tv_sec, tv_usec, msg1):
        self._alarm_id = alarm_id # 告警id
        self._alarm_type = alarm_type # 告警类型
        self._alarm_level = alarm_level # 告警级别
        self.timetamp = TimevalStu(tv_sec, tv_usec) # 时间戳
        self._msg1 = msg1 # 字符串类型，告警消息

接口一 告警订阅

接口二 取消告警订阅

接口三 更新告警订阅

接口四 获取告警id信息

接口五 获取告警类型信息

接口六 获取告警等级信息

接口七 获取告警时间信息

接口八 获取告警描述信息

示例：

[root@openEuler ~]# cat regi_xalarm.py
import sys
from xalarm.register_xalarm import (
    xalarm_register,
    xalarm_unregister,
    xalarm_upgrade,
    xalarm_getid,
    xalarm_getlevel,
    xalarm_gettype,
    xalarm_gettime,
    xalarm_getdesc,
    Xalarm,
    MAX_NUM_OF_ALARM_ID)
from datetime import datetime
from time import sleep

def milliseconds_to_formatted_date(milliseconds):
    seconds = milliseconds / 1000.0
    dt_object = datetime.fromtimestamp(seconds)
    formatted_date = dt_object.strftime('%Y-%m-%d %H:%M:%S')
    return formatted_date

id_filter = [True for _ in range(MAX_NUM_OF_ALARM_ID)]

def xalarm_callback(alarm_info: Xalarm) -> None:
    id_number = xalarm_getid(alarm_info)
    if id_number == 0:
        print("Recv unexpected alarm id 0.")
        return
    level = xalarm_getlevel(alarm_info)
    type_number = xalarm_gettype(alarm_info)
    time_msec = xalarm_gettime(alarm_info)
    desc = xalarm_getdesc(alarm_info)
    print(f"Recv from id: {id_number}: Level={level}, Type={type_number}, Time={milliseconds_to_formatted_date(time_msec)}, Desc={desc}")


if __name__ == "__main__":
    client_id = xalarm_register(xalarm_callback, id_filter)
    if client_id < 0:
        print("connect xalarmd service error!")
        sys.exit(1)
    sleep(10)
    xalarm_unregister(client_id)

c代码注册并获取告警内容

需要安装libxlaram软件包

[root@openEuler ~]# yum install -y libxlaram

开发环境还需要安装libxalarm-devel包（构建依赖，非运行依赖）

[root@openEuler ~]# yum install -y libxalam-devel

结构体 告警消息结构体定义

struct alarm_info {
    unsigned short usAlarmId;
    unsigned char ucAlarmLevel;
    unsigned char ucAlarmType;
    struct timeval AlarmTime;
    char pucParas[ALARM_INFO_MAX_PARAS_LEN];
};

接口一 注册告警

接口二 取消告警订阅

接口三 更新告警订阅

用户自定义callback回调函数，回调函数定义：

typedef void (*alarm_callback_func)(struct alarm_info *palarm);

下述接口四至接口八可以被回调函数触发，用于辅助用户获取告警信息。

接口四 获取告警id信息

接口五 获取告警类型信息

接口六 获取告警等级信息

接口七 获取告警时间信息

接口八 获取告警描述信息

示例：

[root@openEuler ~]# cat regi_xalarm.c
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <xalarm/register_xalarm.h>

#define SLEEP_TIME 10
#define ALARM_ID_1 1001
#define ALARM_ID_2 1002
#define ALARM_ID_3 1003
#define ID_LIST_LENGTH 3

void RefreshOutput(void)
{
    int ret = fflush(stdout);
    if (ret != 0) {
        printf("failed to fflush\n");
    }
}
 
void callback(struct alarm_info *param)
{
    int alarmid, alarmlevel, alarmtype;
    long long alarmtime;
    char *pucParas;

    alarmid = xalarm_getid(param);
    alarmlevel = xalarm_getlevel(param);
    alarmtype = xalarm_gettype(param);
    alarmtime = xalarm_gettime(param);
    pucParas = xalarm_getdesc(param);
 
    printf("[alarmid:%d] [alarmlevel:%d] [alarmtype:%d] [alarmtime:%lld ms] [msg:%s]\n",
        alarmid, alarmlevel, alarmtype, alarmtime, pucParas);

    RefreshOutput();
}

int main(int argc, char **argv)
{
    int clientId;
    int ret;
    struct alarm_subscription_info id_filter;
 
    printf("demo start\n");
    
    clientId = xalarm_Register(callback, id_filter);
    
    if (clientId < 0) {
        printf("demo register failed\n");
        return -1;
    } else {
        printf("xalarm register success, client id is %d\n", clientId);
    }
    printf("demo waiting alarm\n");
    RefreshOutput();
    sleep(SLEEP_TIME);

    xalarm_UnRegister(clientId);
    printf("unregister xalarm success\n");
    RefreshOutput();
    return 0;
}

[root@openEuler ~]# gcc regi_xalarm.c -o regi_xalarm -lxalarm

使用巡检插件

sysSentry目前对openEuler-20.03-LTS-SP4版本提供两个巡检插件：

• 平均阈值慢io检测插件（avg_block_io），通过平均阈值算法实现系统慢io检测，请参考《平均阈值慢盘检测插件》
• AI阈值慢io检测插件（ai_block_io），通过AI阈值算法实现系统慢io检测，请参考《AI阈值慢盘检测插件》

除sysSentry已提供的插件外，用户也可以使用sysSentry提供的对外接口开发新的插件，开发方法请参考《二次开发指南》

sysSentry使用限制

1. sysSentry主软件支持x86_64和aarch64两种架构，巡检插件支持的环境请参考具体插件的使用限制。
2. sysSentry中含有三个后台常驻服务进程，其中sysSentry.service服务为必需启动的进程，xalarmd.service和sentryCollector.service均非必选服务，可根据巡检插件要求启动。