为 Linux 编写插件

使用 Python 或 Shell 编写您自己的插件，按您的方式监控所需数据。为各个属性设置阈值，并在设定值被超过时收到告警。

注意

请确保服务器中已安装最新版本的 Site24x7 Linux 监控代理。

插件输出格式
编写插件的步骤
单个插件脚本中的多配置
编辑/修改已添加的插件监视器
编辑插件模板
Python 示例插件 - 监控 Linux 服务器中的打开文件数
Shell 示例插件 - 监控 Linux 服务器中的文件和目录数量
许可
故障排除提示

插件输出格式

插件脚本应返回一个 JSON 对象。请仅提供一级键值对形式的 JSON 数据。要发布到 Site24x7 服务器的 JSON 数据应采用以下格式：

{
"plugin_version" : 1,
"heartbeat_required" : true,
"cpu" : 42.7,
"memory" : 65.8,
"network" : 156,
"units" :
{
"cpu" : "%" ,
"memory" : "%" ,
"network" : "MB"
}
}

如果您希望在插件监视器下看到表格视图，JSON 格式可以是两级嵌套 JSON。但是，要使插件成功注册，至少需要存在一个父级整数属性。

例如，以下是可发布到 Site24x7 以获得表格视图的 JSON 数据格式：

{
  "plugin_version": 1,
  "heartbeat_required": true,
  "units": {
    "Tablespace_Details": {
      "Tablespace_Size": "mb",
      "Used_Percent": "%",
      "Used_Space": "mb"
    }
  },
  "Tablespace_Details": [
    {
      "name": "SDSCLN",
      "Used_Space": 103.93,
      "Tablespace_Size": 32767.98,
      "Used_Percent": 0.31,
      "TB_Status": 1,
      "status": 1
    },
    {
      "name": "SDSCLNCDR",
      "Used_Space": 1,
      "Tablespace_Size": 32767.98,
      "Used_Percent": 0.003,
      "TB_Status": 1,
      "status": 1
    }
  ],
  "Tablespace_Count": 2,
}

注意

子 JSON 中的 name 字段是唯一支持的字符串值。它是保留关键字，区分大小写，必须严格按照规定方式使用。
所有其他列值必须为数值类型（整数或小数）。不支持任何非数值类型的值（name 字段除外）。
每个表格最多可包含 25 行。不支持单个表格中超过 25 行的数据。

上述内容中：

plugin_version：表示插件的版本号
- 这是必填字段，必须严格按照规定方式使用
- 当 plugin_version 发生变化时，Site24x7 数据中心会更新模板并为该版本创建新模板
- 默认值为 1。如果对插件进行了任何更改，用户必须将 plugin_version 加 1
- plugin_version 只能为整数，例如 1、2、3……
注意
在什么情况下需要更改插件版本？
units：被监控属性的单位
- 这是可选字段
- 它是键值对形式，键为插件中被监控属性的名称，值为对应的单位
- 例如，在插件中测量 CPU 利用率百分比时
  units : {'cpu':'%'}
status：表示监视器的可用性。
- 其值可以为：
  - 1，表示状态为正常运行，指标已成功收集；或
  - 0，表示状态为宕机，由于脚本错误或无法连接到远程服务器或 API，无法收集指标。
- 这是保留键，不得在插件脚本中用于其他功能。
- 将 status 字段捕获为异常，并在自定义脚本中将其设置为 0。这可确保插件执行出错时监视器进入宕机状态。status 字段默认设置为 0。
- 除 status 外，您还可以配置 msg 字段，以捕获插件执行时的错误消息。
msg：监视器的消息
- 这是可选字段
- 如果监视器处于宕机状态，配置的错误消息将显示在 Site24x7 网页客户端中
- 此属性应与数据属性平行放置

编写插件的步骤

在您的服务器中下载并安装最新版本的 Site24x7 Linux 代理。
转到 服务器 > 插件集成 > 编写您自己的插件。
从可用格式中下载示例代码：Shell 或 Python 脚本。
在下载的示例脚本中，找到名为 getData( ) 的方法，并使用您自己的逻辑对其进行编辑，以返回所需的性能数据。
注意
- 在示例代码中，请不要删除 #Mandatory Fields（必填字段）。
- 编写插件时，不要在自定义脚本中使用保留键。请参阅所有保留键的列表。
- 您可以通过在终端手动执行插件脚本来验证其输出。
  示例："python mysql.py"
在 /opt/site24x7/monagent/plugins/ 中创建一个文件夹，并将插件脚本文件放入该文件夹。 请确保文件名和文件夹名称完全相同。 例如，如果您正在为 Apache 编写插件，插件脚本文件应命名为 apache.py，文件夹应命名为 Apache。
注意
对于 Docker 代理，请执行以下命令进入相应容器：
```
docker exec -it site24x7-agent /bin/bash
```
然后，在 /opt/site24x7/monagent/plugins/ 中创建一个文件夹，并将插件脚本文件放入该文件夹。

在下次代理数据采集时，插件将被发现并标记为正在监控。您可以在 服务器 > 插件集成下看到该监视器。插件监视器也将在相应服务器监视器的插件标签页下列出（服务器 > 服务器监视器 > 服务器 > 点击所需服务器监视器 > 插件）。您还可以设置阈值配置文件，并在配置值被超过时收到告警。

注意

所有插件日志均捕获在代理日志目录下的 plugins.txt 文件中，可用于插件故障排除。日志文件路径：opt/site24x7/monagent/logs/details

单个插件脚本中的多配置

当一个插件有多个配置需要执行时，为每个配置（使用不同名称）创建新监视器既耗时又费力。为解决这一问题，Site24x7 插件监控支持使用单个插件脚本执行多个配置。

示例 1：使用单个插件监控同一主机上运行的多个 MySQL 实例
示例 2：使用单个插件监控多个文件夹中的文件或目录数

示例 1：

假设您的环境中运行着多个 MySQL 实例，例如 production_master 和 production_slave。您无需使用多个 MySQL 插件，而是可以定义所有配置并使用单个插件脚本文件全部执行。在开始之前，请确保已安装运行插件所需的依赖模块。然后，请按照以下步骤操作：

创建一个名为 mysql 的文件夹，并将插件脚本文件 mysql.py 放入该文件夹中。

创建一个与插件同名的配置文件 mysql.cfg，并将其放入 mysql 文件夹中。在 mysql.cfg 文件中按如下方式定义配置：

[production_master]
hostname='193.167.1.0' 
port = 3306
username = 'test'
password = 'test'

[production_slave]
hostname='194.168.2.0' 
port = 3306
username = 'test'
password = 'test'

在 mysql.py 脚本文件的 main 函数中添加以下代码，以读取 mysql.cfg 文件中配置的参数。如果插件脚本文件中已有该代码，请忽略此步骤。

注意

复制粘贴以下代码后，请确保插件脚本文件中的缩进正确。

  import argparse
  parser = argparse.ArgumentParser()
  parser.add_argument('--host', help="mysql host",type=str)
  parser.add_argument('--port', help ="mysql port",type=str)
  parser.add_argument('--username', help='mysql username', type=str)
  parser.add_argument('--password', help='mysql password', type=str)

args = parser.parse_args()

  if args.host:
     MYSQL_HOST = args.host
  if args.port:
     MYSQL_PORT = args.port
  if args.username:
     MYSQL_USERNAME = args.username
  if args.password:
     MYSQL_PASSWORD = args.password

通过执行以下命令，检查 mysql.cfg 中定义的配置是否正常运行：
```
/usr/bin/python mysql.py --host=192.168.1.0 --port=3306 --username=test --password=test 
 /usr/bin/python mysql.py --host=192.168.2.0 --port=3306 --username=test --password=test
```
注意
请确保 MySQL 性能指标以 JSON 格式输出返回。如有错误，请修复后再继续下一步。
将 mysql 文件夹复制粘贴到代理的插件目录 /opt/site24x7/monagent/plugins/。在下次数据采集时，Linux 代理将加密 .cfg 文件中的值，执行 mysql.py 文件，并在 Site24x7 网页客户端中为每个配置（在 mysql.cfg 文件中定义的）添加一个新的插件监视器。加密后的示例配置文件如下：
```
[production_master]
encrypted.password = ojhVVrdlXKdW/s3YPJuhzCKhBcQF8PIUThEvqGeUijI= 

[production_slave]
encrypted.password = XzIGEreeTblUFrvUJWDcIArzN5qi0qHFxZVUt1KqjyY=
```

在 Site24x7 网页客户端中，将添加三个插件监视器进行监控。Site24x7 网页客户端中插件监视器的显示名称格式为 --。
例如：在上述示例配置中，其中一个监视器的显示名称将为 mysql.py-production_master-

插件配置详情的加密：

默认情况下，Linux 服务器监控代理会加密插件配置文件中的 'password' 字段。插件执行后，配置文件将更新如下：

[production_master]
 host=192.168.1.0
 port = 3306
 username = 'test'
 encrypted.password = ojhVVrdlXKdW/s3YPJuhzCKhBcQF8PIUThEvqGeUijI=

[production_slave]
 host=192.168.2.0
 port = 3306
 username = 'test'
 encrypted.password = XzIGEreeTblUFrvUJWDcIArzN5qi0qHFxZVUt1KqjyY=

如果需要对除密码之外的其他字段也进行加密，请在 mysql.cfg 文件的 global_configurations 部分进行配置。

[global_configurations]
 keys_to_encrypt=password,username

[production_master]
 host=192.168.2.0
 port = 3306
 username = 'test'
 password = 'test'
 
[production_slave]
 host=192.168.2.0
 port = 3306
 username = 'test'
 password = 'test'

编辑配置详情：
如果配置文件中的任何值发生变化，您可以通过从已定义键中删除 'encrypted.' 参数来进行编辑。
例如，如果 [production_master] 部分的密码发生变化，请编辑 mysql.cfg 文件，从 encrypted.passsword 键中删除 'encrypted.' 参数，并输入新密码。在下次连续数据采集时，代理将检测到配置变更，加密新值，并相应更新文件。
示例 2：
假设您需要监控多个文件夹中的文件或目录数。您无需使用多个插件，而是可以定义所有配置并使用单个插件脚本文件全部执行。操作步骤如下：

创建一个名为 check_file_count 的文件夹。
从我们的 GitHub 仓库下载 check_file_count.cfg 和 check_file_count.py 文件，并将其放入 check_file_count 文件夹中。
编辑 check_file_count.cfg 文件以相应更改配置。
注意
默认情况下，文件中已配置了两组文件夹配置。创建新部分即可扩展配置。
配置阈值，以便在文件或目录数超过给定值时收到通知。在 check_file_count.cfg 文件中，按如下方式配置阈值：
/usr/bin/python check_file_count.py --folder_name=/ --file_count_threshold=20 --directory_count_threshold=10
/usr/bin/python check_file_count.py --folder_name=/opt --file_count_threshold=20
将 check_file_count 文件夹复制粘贴到代理的插件目录 /opt/site24x7/monagent/plugins/。在下次数据采集时，Linux 代理将执行 check_file_count.py 文件，并在 Site24x7 网页客户端中为每个配置（在 check_file_count.cfg 文件中定义的）添加一个新的插件监视器。

编辑/修改已添加的插件监视器

插件监视器成功添加后，您可以转到 服务器 > 插件 > 点击您已添加的插件监视器。
将鼠标悬停在显示名称旁边的汉堡图标上，点击编辑。
在编辑插件监视器页面中，您可以编辑或替换现有显示名称。
设置数据采集的轮询间隔，范围从一分钟到一天。
自定义插件脚本的 脚本执行超时时间。默认超时值为 50 秒。
在高级配置下，
- 阈值与可用性：保留默认阈值配置文件，或从下拉菜单中选择现有配置文件，或使用 (+) 图标添加新配置文件，并在资源超过配置的阈值时收到通知。
- 通知配置文件：保留默认配置文件，或选择现有配置文件，或添加新配置文件（使用 + 图标），并配置宕机时通知的时间和人员。
- 用户告警组：选择现有用户组或添加用户告警组，以便在中断期间收到告警。默认情况下将选择用户的管理员组。
- 关联监视器组：选择现有监视器组或新建一个。
- 标签：通过应用唯一标签对账户中的相关资源进行分类和排序。使用"添加标签"来新建标签。
- IT 自动化：从下拉菜单中选择现有自动化配置文件或添加自动化。配置触发该自动化的条件。
- 第三方集成：将 Site24x7 告警集成到首选的第三方服务。
保存您的更改。

编辑插件模板

添加插件监视器后，可以对插件模板进行编辑。转到管理 > 服务器监控 > 插件模板配置 > 编辑模板定义（或）服务器 > 插件 > 点击具有关联模板的插件监视器 > 自定义视图。

点击了解如何编辑模板

Python 示例插件 - 监控 Linux 服务器中的打开文件数

#!/usr/bin/python3

import sys,json

#if any impacting changes to this plugin kindly increment the plugin version here.
PLUGIN_VERSION = "1"

#Setting this to true will alert you when there is a communication problem while posting plugin data to server
HEARTBEAT="true"


PROC_FILE = "/proc/sys/fs/file-nr"

METRIC_UNITS = {'open_files': 'units', 'total_files': 'units'}
def metricCollector():
   data = {}
   data['plugin_version'] = PLUGIN_VERSION 
   data['heartbeat_required']=HEARTBEAT 
   try:
        open_nr, free_nr, max = open(PROC_FILE).readline().split("\t")
        open_files = int(open_nr) - int(free_nr)
        data["open_files"] = open_files
        data["total_files"] = int(max)
        data["units"] = METRIC_UNITS
   except Exception as e:
        data["status"] = 0
        data["msg"] = str(e)
        
   return data

if __name__ == "__main__":
      result = metricCollector()
      print(json.dumps(result, indent=4, sort_keys=True))

注意

#!/usr/bin/python：在插件文件顶部添加"shebang 字符"(#!)。这将是执行插件文件所用的 Python 路径
Python 脚本应返回 JSON 数据

JSON 输出：

{
   "open_files": 12512,
   "total_files": 1620019,
    "units": {
                   "open_files": "units",
                   "total_files": "units"
                  }
}

数据在 Site24x7 仪表板中的展示方式：

Shell 示例插件 - 监控 Linux 服务器中的文件和目录数量

#!/bin/bash

##### Site24x7 Configuration Constants #####
PLUGIN_VERSION=1 # Set version of the plugin template used. For each plugin version, there will be a set of metrics monitored.
HEARTBEAT=false # Set if plugin has to be alerted when data is not collected for sometime


##### Plugin Input Constants #####
DIRNAME=. # Location in Which the File Count and Directory Count will be Taken
SEARCH_LEVEL=1 # Upto Which Level of Inner Directories to count the Directories and Files


##### Plugin Code #####
PLUGIN_OUTPUT=""
PLUGIN_OUTPUT=$PLUGIN_OUTPUT"plugin_version:$PLUGIN_VERSION|"
PLUGIN_OUTPUT=$PLUGIN_OUTPUT"heartbeat_required:$HEARTBEAT|"


##### Plugin Logic to get the number of files and directories
FILES=`find $DIRNAME -maxdepth $SEARCH_LEVEL -type f | wc -l`
DIRS=`find $DIRNAME/* -maxdepth $SEARCH_LEVEL -type d | wc -l`


##### Add Key and value to be monitored
##### Replace the sample keys with the metrics you want to monitor
##### Execute the commands and store the values in a variable
##### Replace the dummy values with the variables to monitor
PLUGIN_OUTPUT=$PLUGIN_OUTPUT"file_count:$FILES|"
PLUGIN_OUTPUT=$PLUGIN_OUTPUT"dir_count:$DIRS"


##### Add the units for the values to be monitored #####
UNITS="units:{"
UNITS=$UNITS"file_count-count,"
UNITS=$UNITS"dir_count-count"
UNITS=$UNITS"}"

##### Remove if not required
PLUGIN_OUTPUT="$PLUGIN_OUTPUT|$UNITS"


##### Print the data
echo "$PLUGIN_OUTPUT"

注意

#!/bin/bash：在插件文件顶部添加"shebang 字符"(#!)。这表示脚本应始终使用 bash 运行
输出将包含键值对，每对之间以分隔符 (|) 分隔

示例 JSON 输出：

plugin_version:1|heartbeat_required:false|file_count:18|dir_count:26|units:{file_count-count,dir_count-count}

数据在 Site24x7 仪表板中的展示方式：

注意

查看使用 jq 库的示例插件脚本。

许可

为服务器监视器添加的第一个插件是免费的。此后，每个插件监视器均被视为基础监视器。

故障排除提示

注意

编写插件遇到困难？或有特定需求？无需担心！在我们的社区论坛中发帖，我们将为您解决。

相关文章

本页内容