Fortinet black logo

User Guide

24.2.0
24.2.0

Custom plugins for Windows

Custom plugins for Windows (FortiMonitor Agent)

You can add your own custom PowerShell plugins to the agent if there are any resources on your server that you would like to monitor, but that we do not currently support out of the box or where there is no PerfMon counter. For example, if you have created a custom application and would like to check its performance/functionality then you can write a custom plugin for that. Here are the steps:

  1. Create a new file in the %Program Files%/FortiMonitorAgent/ps_plugins directory named after the applications you're monitoring, such as my_app_plugin.ps1.

  2. Start with a copy of the template.ps1 file, which defines the overall layout of the plugin class and the methods necessary to operate.

  3. Implement Plugin-Configuration. Define a value for the variable textkey for your plugin. This is a unique string defining the very general service or a resource that your plugin is monitoring. The textkey should be prefixed with an identifier for your organization. For example, com.acme.myapplication.

  4. Implement Discover: This is the method that determines what aspects of the application/metric you're checking are able to be monitored. This returns an array of dictionaries that contain the metrics and the options the plugin can effectively monitor. Options can be static values or could be dynamically discovered based on the environment/server. Normally, if you're developing your own plugin, you probably won't have to do much in the way of making it portable for others, since you're assuming that your service is already available and monitorable, but if you need more flexibility in detection, Discover is where you'd exercise it. Each object in the array has an attribute and those attributes are explained below:

    • label: A human-readable string description of the metric, used for graph labels and alert messages in the control panel.

    • options: An optional list of strings describing different metric sources that could be monitored. For example, for the disk space plugin, the options are a list of all of the disk partitions on the server. If your metric doesn't have any options, you can set this to $null.

    • unit: A text string description of the units of measurement for the metric, for example, "MB" or "connections per second". Metrics from a plugin that share a common unit will be graphed together in the control panel.

  5. Implement Collect-Metric: This is responsible for actually doing the retrieval/calculation based on the metric textkey, an optional value, and other optional config parameters that you may have specified within the Agent's configuration file. Collect-Metric should be the bulk of your work. It should read, parse, chop, measure, compare, analyze, aggregate, monitor, slice, dice, mix, and mash whatever required to return a measurable value of your resource, and ultimately return an integer or float value for the metric. This function takes in two parameters. The $resource_textkey is a reference to the metric type which is being passed in from the agent to be collected. If your plugin supports multiple metrics (returned by the Discover function), you will need some branching logic here to execute different logic based on the resource_textkey. $option is a reference to the specific option value for that metric. This will influence the specific metric value you need to query/extract and return.

Plugin Configuration

If your plugin requires additional configuration to account for settings or environment-specific variables, you can leverage the Agent's configuration file. Plugin configuration is defined in your Agent's main XML configuration file, under its own section titled after the textkey of the plugin. To define your plugin's section, create a new XML block under config with the node matching the textkey from Plugin-Configuration. Underneath that new section, you can put different key/values that are better not hard-coded into your Collect-Metric method--things like login credentials and other adjustable parameters. An example would be:

Plugin Config

<config>
<systemp>
<add key="myparam" value="myvalue"/>
</systemp>
</config>

When your plugin's Discover and Collect-Metric methods are called, the Agent configuration file is parsed and searched for a plugin config section that matches the name of your plugin class. If any config is found, the variables and values are passed into the plugin functions.

Previous
Next

Custom plugins for Windows (FortiMonitor Agent)

You can add your own custom PowerShell plugins to the agent if there are any resources on your server that you would like to monitor, but that we do not currently support out of the box or where there is no PerfMon counter. For example, if you have created a custom application and would like to check its performance/functionality then you can write a custom plugin for that. Here are the steps:

  1. Create a new file in the %Program Files%/FortiMonitorAgent/ps_plugins directory named after the applications you're monitoring, such as my_app_plugin.ps1.

  2. Start with a copy of the template.ps1 file, which defines the overall layout of the plugin class and the methods necessary to operate.

  3. Implement Plugin-Configuration. Define a value for the variable textkey for your plugin. This is a unique string defining the very general service or a resource that your plugin is monitoring. The textkey should be prefixed with an identifier for your organization. For example, com.acme.myapplication.

  4. Implement Discover: This is the method that determines what aspects of the application/metric you're checking are able to be monitored. This returns an array of dictionaries that contain the metrics and the options the plugin can effectively monitor. Options can be static values or could be dynamically discovered based on the environment/server. Normally, if you're developing your own plugin, you probably won't have to do much in the way of making it portable for others, since you're assuming that your service is already available and monitorable, but if you need more flexibility in detection, Discover is where you'd exercise it. Each object in the array has an attribute and those attributes are explained below:

    • label: A human-readable string description of the metric, used for graph labels and alert messages in the control panel.

    • options: An optional list of strings describing different metric sources that could be monitored. For example, for the disk space plugin, the options are a list of all of the disk partitions on the server. If your metric doesn't have any options, you can set this to $null.

    • unit: A text string description of the units of measurement for the metric, for example, "MB" or "connections per second". Metrics from a plugin that share a common unit will be graphed together in the control panel.

  5. Implement Collect-Metric: This is responsible for actually doing the retrieval/calculation based on the metric textkey, an optional value, and other optional config parameters that you may have specified within the Agent's configuration file. Collect-Metric should be the bulk of your work. It should read, parse, chop, measure, compare, analyze, aggregate, monitor, slice, dice, mix, and mash whatever required to return a measurable value of your resource, and ultimately return an integer or float value for the metric. This function takes in two parameters. The $resource_textkey is a reference to the metric type which is being passed in from the agent to be collected. If your plugin supports multiple metrics (returned by the Discover function), you will need some branching logic here to execute different logic based on the resource_textkey. $option is a reference to the specific option value for that metric. This will influence the specific metric value you need to query/extract and return.

Plugin Configuration

If your plugin requires additional configuration to account for settings or environment-specific variables, you can leverage the Agent's configuration file. Plugin configuration is defined in your Agent's main XML configuration file, under its own section titled after the textkey of the plugin. To define your plugin's section, create a new XML block under config with the node matching the textkey from Plugin-Configuration. Underneath that new section, you can put different key/values that are better not hard-coded into your Collect-Metric method--things like login credentials and other adjustable parameters. An example would be:

Plugin Config

<config>
<systemp>
<add key="myparam" value="myvalue"/>
</systemp>
</config>

When your plugin's Discover and Collect-Metric methods are called, the Agent configuration file is parsed and searched for a plugin config section that matches the name of your plugin class. If any config is found, the variables and values are passed into the plugin functions.

Previous
Next