为 Windows 编写插件

使用 VB、PowerShell、Batch 和 DLL 编写您自己的插件，以您想要的方式监控所需数据。为各个属性设置阈值，并在设定值超出时接收告警。

插件的 JSON 输出格式

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

{
"plugin_version" : "1",
"Name":"John","Age":40,"Role":"Admin","Salary":87000,"Experience":3.4,"Performance":98.99,
"units":{"Age":"year","Salary":"Dollars","Experience":"years","Performance":"%"},
"heartbeat":"True",
"displayname":"Employee",
"msg":"Poor Performance"
}

上述代码中：

plugin_version：表示插件的版本号
- 此为必填字段
- 当版本发生任何变更时，Site24x7 数据中心将更新模板并为该版本创建新模板
- 默认值为 1。如果对插件进行了任何更改，用户必须将版本号递增 1
- plugin_version 仅支持整数，例如 1、2、3...
units：受监控属性的单位
- 此为可选字段
- 它是一个键值对，其中键为插件中受监控属性的名称，值为各自的单位
- 例如，在插件中测量 CPU 利用率百分比时：
  units : {'cpu':'%'}
displayname：监视器在客户端中显示的名称。此为可选字段
msg：监视器的消息
- 此为可选字段
- 如果监视器宕机，已配置的错误消息将显示在 Site24x7 Web 客户端中
- 此属性应与数据属性并列放置

插件中表格视图的 JSON 输出格式

如果您希望在插件监视器下看到表格视图，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,
}

Note

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

编写自定义插件的步骤

下载并安装服务器上最新版本的 Windows 代理。
前往服务器 > 插件集成 (+) > 编写您自己的插件。
从可用格式（PowerShell、DLL、Batch 或 VB 脚本）中下载示例代码。
在下载的示例脚本中，找到名为 getData() 的方法，并根据您自己的逻辑进行编辑，以返回所需的性能数据。
Note
- 在示例代码中，请不要删除 #Mandatory Fields（必填字段）。
- 您可以通过在终端中手动执行插件脚本来验证其输出。例如：" powershell ./mysql.ps1"
在代理安装路径下的 Plugins 目录中创建一个文件夹，并将插件脚本文件和其他依赖文件放置于此。请确保插件文件夹名称与插件脚本文件名完全相同。例如，如果您正在为 DHCP 编写插件，文件夹名称应为 dhcp，插件脚本文件名应为 dhcp.ps1
示例： "C:\Program Files (x86)\Site24x7\WinAgent\monitoring\Plugins\dhcp\dhcp.ps1"

添加插件监视器后，您可以在服务器 > 插件集成下看到该监视器。该插件监视器还将在相应服务器监视器的插件选项卡下列出（服务器 > 服务器监视器 > 服务器 > 点击所需服务器监视器 > 插件）。您可以设置阈值配置文件，并在配置值超出时收到告警。

Note

所有插件日志将被记录到 [安装目录]\monitoring\logs\Details 下的 PluginLog.log 和 PluginRegisterLog.log 文件中。

在单个插件上执行多个配置

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

使用场景：

假设您有多个 DHCP 范围需要全部监控。您无需使用多个 DHCP 插件，而是可以定义所有配置并使用单个脚本执行它们。

解决方案：

创建文件夹"dhcp"，并将插件脚本"dhcp.ps1"放置于该文件夹内。
创建配置文件"dhcp.json"，并将其放置于"dhcp"文件夹内。

在"dhcp.json"文件中定义不同 DHCP 插件的配置。例如：

{ 
   "DHCP_Scope_172.2.0.0": { 
     "scopeid": "172.2.0.0" 
   }, 
    "DHCP_Scope_172.3.0.0": {
      "scopeid": "172.3.0.0" 
    }, 
    "DHCP_Scope_172.5.0.0": { 
     "scopeid": "172.5.0.0" 
    } 
}

在"dhcp.ps1"脚本文件顶部添加以下代码：
```
param([string]$scopeid)
```
将"dhcp"文件夹复制到代理的插件目录 C:\Program Files (x86)\Site24x7\WinAgent\monitoring\Plugins 中。

在下一次数据采集时，Windows 代理将加密 JSON 文件中的值，执行"dhcp.ps1"文件，并为"dhcp.json"文件中定义的每种配置在 Site24x7 Web 客户端中添加一个新的插件监视器。加密后的配置文件示例如下：

{ 
   "DHCP_Scope_172.2.0.0": { 
     "encrypted_scopeid": "NkcyMZYvZormEEnJi8AA1IDceMvI5OC4ul52v3E+BH0=" 
   }, 
    "DHCP_Scope_172.3.0.0": {
      "encrypted_scopeid": "ttkogqMVaRTiEtzTWX7Dkft0Q1sn5WsqBhJzJDbIZN0=" 
    }, 
    "DHCP_Scope_172.5.0.0": { 
     "encrypted_scopeid": "aakogqMVaRTiEtzTWX70Q1sn5WsqBhJzJDbIPQ70=" 
    } 
}

这将在 Site24x7 Web 客户端中添加三个插件监视器，显示名称分别为"DHCP_Scope_172.2.0.0-"、"DHCP_Scope_172.3.0.0-"和"DHCP_Scope_172.5.0.0-"。

Note

编辑配置详情：
如果配置文件中提供的任何值发生变更，您可以通过删除已定义键中的"encrypted"参数来进行编辑。例如，如果 DHCP_Scope_172.5.0.0 的 scopeid 发生变更，请在"dhcp.json"文件中删除键"encrypted_scopeid"中的"encrypted_"参数，并输入新的主机名。在下一次连续数据采集时，代理将检测到配置变更，对新值进行加密，并相应地更新文件。

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

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

VB 插件脚本示例

version = "1"

heartbeat = "True"

displayname = "Employee"

Name = "John"

Age = 40

Role = "Admin"

Salary = 87000

Experience = 3.4

Performance = 48.99

data = AddData(data,"name",name)
data = AddData(data,"Age",Age)
data = AddData(data,"Role",Role)
data = AddData(data,"Salary",Salary)
data = AddData(data,"Experience",Experience)
data = AddData(data,"Performance",Performance)

units = AddData(units,"Age","year")
units = AddData(units,"Salary","Dollars")
units = AddData(units,"Experience","years")
units = AddData(units,"Performance","%")

mainJson = AddData(mainJson,"version",version)
mainJson = AddObj(mainJson,"data",data)
mainJson = AddObj(mainJson,"units",units)
mainJson = AddData(mainJson,"heartbeat",heartbeat)
mainJson = AddData(mainJson,"displayname",displayname)

if Performance < 50 then
mainJson = AddData(mainJson,"msg","Poor Performance")
End If

Wscript.Echo mainJson

Function AddData(data,key,value)
   emptystr = ""
   If data = emptystr then
      data = "{"
   Else
      data = StrReverse(Replace(StrReverse(data),"}",",",1,1))
   End If
   AddData = data & """" & key & """" &" : " & """" & value & """" & "}"
End Function

Function AddObj(data,key,value)
   emptystr = "" 
   If data = emptystr then
      data = "{" Else data = StrReverse(Replace(StrReverse(data),"}",",",1,1))
   End If
   AddObj = data & """" & key & """" &" : " & value & "}"
End Function

JSON 输出：

{

"version" : "1",

"data":{"Name":"John","Age":40,"Role":"Admin","Salary":87000,"Experience":3.4,"Performance":98.99},

"units":{"Age":"year","Salary":"Dollars","Experience":"years","Performance":"%"},

"heartbeat":"True",

"displayname":"Employee",

"msg" : "Poor Performance"

}

参考我们的论坛帖子，查看使用 VB 脚本的平均磁盘队列长度插件文件示例

PowerShell 插件脚本示例

$plugin_version = 1  
$displayname = "Process Monitor"  
$heartbeat = "true"  
$processname = "avp.exe"
$Status = 1
$msg = $null
Function Get-Data()  
{
#It is enough to edit this function and return the metrics required in $data
    $data = @{}
    $ExecutablePath = ""
    $HandleCount = 0
    $instance = 0
    $ThreadCount = 0;
    $ProcessId = ""
    $cpu = 0
    $memory = 0
    try
    {
      $filter = "Name='"+$processname+"'"
      $wmiouptput = Get-WmiObject -Class Win32_Process -Namespace 'root\cimv2' -Property HandleCount,Name,ProcessId,Status,ThreadCount,ExecutablePath -Filter $filter -ErrorAction Stop

      foreach($dataelm in $wmiouptput)
      {
        $instance = $instance +1
        $Name= $dataelm.Name
        $ExecutablePath= $dataelm.ExecutablePath
        $HandleCount= $HandleCount + $dataelm.HandleCount
        if($instance -gt 1)
        {
          $ProcessId = $ProcessId +"," 
        }
        $ProcessId= $ProcessId + $dataelm.ProcessId
        $ThreadCount= $ThreadCount + $dataelm.ThreadCount
        $cpu = 19
        $memory = 80
      }
    }
    catch
    {
      $Script:Status = 0
      $Script:msg = $_.Exception.Message
    }

    $data.Add("Name",$Name)
    $data.Add("instance",$instance)
    $data.Add("HandleCount", $HandleCount)
    $data.Add("ProcessId", $ProcessId)
    $data.Add("ThreadCount", $ThreadCount)
    $data.Add("ExecutablePath", $ExecutablePath)
    $data.Add("CPU", $cpu)
    $data.Add("Memory", $Memory)
    return $data
}
Function Set-Units() #OPTIONAL - These units will be displayed in the Dashboard
{
    $units = @{}
    $units.Add("CPU","%")
    $units.Add("Memory", "MB")
    return $units
}

$mainJson = @{}
$mainJson.Add("plugin_version", $plugin_version)
$mainJson.Add("heartbeat_required", $heartbeat)
$mainJson.Add("displayname", $displayname) #Comment this if you don't display name
$mainJson.Add("data", (Get-Data))
$mainJson.Add("units", (Set-Units)) #Comment this if you don't have Units
if($Status -eq 0)
{
   $mainJson.Add("status",0)
}
if($msg -ne $null)
{
   $mainJson.Add("msg",$msg)
}
return $mainJson | ConvertTo-Json

JSON 输出：

{
    "plugin_version":  1,
    "units":  {
                  "CPU":  "%",
                  "Memory":  "MB"
             },
    "displayname":  "Process Monitor",
    "data":  {
                 "ProcessId":  "",
                 "ExecutablePath":  "",
                 "CPU":  0,
                 "Memory":  0,
                 "Name":  null,
                 "HandleCount":  0,
                 "ThreadCount":  0,
                 "instance":  0
             },
    "heartbeat_required":  "true"
}

Batch 插件脚本示例

@ECHO OFF

SET plugin_version="1"

SET heartbeat="True"

SET displayname="Network Traffic"

SET units={"Packets recieved":"sec","Packets sent":"sec","Bandwidth utilization":"Kbps","Speed":"Mbps"}

SET Packetsrecieved=10

SET Packetssent=4

SET Bandwidthutilization=12

SET Speed=87

SET Msg=""

IF %Bandwidthutilization% gtr 10 (
SET Msg="High Bandwidth Utilization"
)

SET data={"Packets recieved":%Packetsrecieved%,"Packets sent":%Packetssent%,"Bandwidth utilization":%Bandwidthutilization%,"Speed":%Speed%}

IF %Msg%=="" (
SET mainJson={"plugin_version" : %plugin_version%,"data" : %data%,"units" : %units%,"heartbeat" : %heartbeat%,"displayname" : %displayname%}
) ELSE (
SET mainJson={"plugin_version" : %plugin_version%,"data" : %data%,"units" : %units%,"heartbeat" : %heartbeat%,"displayname" : %displayname%,"msg" : %Msg%}
)

ECHO %mainJson%

JSON 输出：

{"plugin_version" : "1","data" : {"Packets recieved":10,"Packets sent":4,"Bandwidth utilization":12,"Speed":87},"units" : {"Packets recieved":"sec","Packets sent":"sec","Bandwidth utilization":"Kbps","Speed":"Mbps"},"heartbeat" : "True","displayname" : "Network Traffic","msg" : "High Bandwidth Utilization"}