Writing a Plugin for Windows

Write your own plugin using VB, PowerShell, Batch, and DLL and monitor data that you need, the way you want. Set thresholds to individual attributes and get alerted if the set values exceed.

• Format of plugin output
• Steps to write a custom plugin
• Execute multiple configurations on a single plugin
• Edit/modify added plugin monitor
• Sample plugin scripts for: VB | PowerShell | Batch 
• Write your own plugin using DLL
• Licensing
• Troubleshooting Tips

Format of Plugin Output 

The plugin script should return a JSON object. Provide only one level of JSON data as key-value pair. The JSON data to be posted to the Site24x7 server should be in the following format:

{
"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"
}

{ 
"Key 1" : {"obj 1" : "value 1", "obj 2" : "value 2" ...}, 
"Key 2" : ["obj 1", "obj 2", .. ], 
... 
}

1. version: Denotes the version number of the plugin
   • This is a mandatory field
   • When there is any change in the version, the Site24x7 data centre updates the template and creates a new template for that version
   • The default value is 1. If any change is done in the plugin, user must increment the version by 1
   • version should be whole numbers only. E.g. 1,2,3...
2. units: Units of the attributes monitored
   • This is an optional field
   • It is a key value pair with keys as the name of the attributes monitored in the plugin and the values as their respective units
   • For example, while measuring the cpu utilization percentage in a plugin
     units : {'cpu':'%'}
3. displayname: The name of the monitor as displayed in the client. This is an optional field
4. msg: Messages for the monitor
   • This is an optional field
   • The configured error message would show up in the Site24x7 web client if the monitor is down
   • This attribute should be placed parallel to the data attribute

Steps to Write a Custom Plugin

1. Download and install the latest version of the Windows agent in your server.
2. Go to Server > Plugin Integrations (+) > Write your own Plugin.
3. Download the sample code from any of the available formats: PowerShell, DLL, Batch or VB script.
4. In the downloaded sample script, find the Method named getData( ) and edit this with your own logic to return the required performance data. 
   • In the sample code, please do not delete the #Mandatory Fields.
   • You can validate the output of your plugin script by executing it manually in the terminal. Example: " powershell ./mysql.ps1"
5. Create a folder under the Plugins directory in the agent installation path and place the plugin script file and other dependency files here. Make sure the name of plugin folder name and the plugin script file name are identical. For eg., if you are writing a plugin for DHCP, the folder name should be dhcp and the plugin script file name should be dhcp.ps1 
   Eg: "C:\Program Files (x86)\Site24x7\WinAgent\monitoring\Plugins\dhcp\dhcp.ps1"

Once the plugin monitor is added, you can see the monitor under Server > Plugin Integrations. The plugin monitor will also be listed under the respective server monitor's Plugins tab (Server > Server Monitor > Servers > click on the desired server monitor > Plugins). You can set up threshold profiles and be alerted when the configured value exceeds.

Execute Multiple Configurations on a Single Plugin

When there is more than one configuration for executing a plugin, creating a new monitor for every configuration (with different names) can turn time consuming and laborious. To resolve this, Site24x7 Plugin Monitoring supports executing multiple configurations using a single plugin script.

Use Case:

Consider having multiple DHCP scopes and you wish to monitor them all. Instead of using multiple DHCP plugins, you can define all the configurations and execute them using a single script.  

Solution:

1. Create a folder 'dhcp' and place the plugin script 'dhcp.ps1' inside this folder.
2. Create a configuration file 'dhcp.json' and place it inside the 'dhcp' folder.
3. Define the configuration of the different DHCP plugins in the 'dhcp.json' file. For example:

   { 
      "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" 
       } 
   }

4. Add the following piece of code in the top of the 'dhcp.ps1' script file:
   

   param([string]$scopeid)

5. Copy-paste the 'dhcp' folder to the agent's plugin directory C:\Program Files (x86)\Site24x7\WinAgent\monitoring\Plugins.

In the next data collection, the Windows agent will encrypt the values in the JSON file, execute the 'dhcp.ps1' file and add a new plugin monitor for each configuration (given in the 'dhcp.json' file) in the Site24x7 web client. A sample configuration file after encryption would look like:

{ 
   "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=" 
    } 
}

This would add three plugin monitors in the Site24x7 web client with display names 'DHCP_Scope_172.2.0.0-<host name>', 'DHCP_Scope_172.3.0.0-<host name>', and 'DHCP_Scope_172.5.0.0-<host name>'. 

Edit/Modify Added Plugin Monitor

1. Once a plugin monitor is successfully added, you can go to Server > Plugins > click on the plugin monitor that you have added.
2. Hover on the hamburger icon beside the display name and click on Edit.
3. You can edit or replace the existing display name with a new one in the Edit Plugin Monitor page. 
4. Set the Poll Interval for data collection, ranging from one minute to one day.
5. Customize the Script Execution Timeout for your plugin scripts. The default timeout value is 30 seconds.
6. Under Advanced Configuration,
   • Threshold and Availability: Retain the default threshold profile or select an existing one from the dropdown or add a new one using the (+) icon and get notified when a resource exceeds the configured threshold value.
   • Notification Profile: Retain the default profile or choose an existing one or add a new one using the (+) icon and configure when and who needs to be notifed in case of downtime.
   • User Alert Groups: Select an existing user group or Add a User Alert Group that needs to be alerted during an outage. The user's Admin Group will be selected by default.
   • Associate with Monitor Group(s): Choose an existing Monitor Group or create a new one. 
   • Tags: Classify and sort related resources in your account by applying unique labels. Use Add Tag to add a new one.
   • IT Automation: Select an existing automation profile or Add Automation from the dropdown. Map the condition when you want to execute that particular automation. 
   • Third Party Integration: Integrate Site24x7 alarms to a preferred third party service.
7. Save your changes.

Sample Plugin Script for 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 output:

{
"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"
}

Refer our forum post to view a sample plugin file using VB script for Average Disk Queue Length

Sample Plugin Script for PowerShell 

$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", $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 output:

Sample Plugin Script for Batch

@ECHO OFF
SET 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={"version" : %version%,"data" : %data%,"units" : %units%,"heartbeat" : %heartbeat%,"displayname" : %displayname%}
) ELSE (
SET mainJson={"version" : %version%,"data" : %data%,"units" : %units%,"heartbeat" : %heartbeat%,"displayname" : %displayname%,"msg" : %Msg%}
)
ECHO %mainJson%

JSON output:

Write your own Plugin using DLL

Know how to write a plugin using DLL. 

Licensing

The first plugin added for a server monitor is free. After that, each plugin monitor is considered as a basic monitor. Each plugin can have upto 25 attributes. 

Troubleshooting Tips

• Possible reasons why my Windows plugin is not added to my Site24x7 account
• Run python plugin scripts in Windows servers
• Add new attributes to an existing Windows plugin
• Under what conditions should I change my plugin version?
• Create object for my class in PowerShell script
• Mandatory requirements to write a Windows plugin using DLL

Related Articles

• Introduction to plugins | How to debug a plugin monitor?
• Plugin template configuration | Threshold profile for plugins
• Custom Linux plugin | Out-of-the-box plugins support
• Add a server monitor | Server monitoring architecture | Server metrics 
• IT Automation