You can add your own custom 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. For example, if you have created a custom application for your server and would like to check its performance then you can write a custom plugin for that application.

1. Create a new python file in /usr/share/fm-agent/ directory named after the applications you're monitoring, such as my_application.py.

2. Start with a copy of the template.py file, which defines the overall layout of the plugin class and the methods necessary to operate. Each of the comments in this file marked with TODO: is an item that needs to be provided for your plugin to work.

3. Define a class attribute textkey for your plugin. This is a unique dotted string defining the very general service or resource that your plugin is monitoring. The textkey should be prefixed with an identifier for your organization. For example, com.acme.myapplication.

4. Implement get_metadata(). This is the method that determines what aspects of the thing you're checking are able to be monitored. For example, the standard Apache plugin has checks in it to determine if ExtendedStatus is available in /etc/httpd.conf, which allows the plugin to monitor things like connections per second. Without this enabled, get_metadata, can only say that it can monitor a few basic aspects of Apache. It takes 1 argument ""config"" which is your plugin's specific configuration. More on configuration later. The return value from this method is a dictionary whose keys are unique, monitorable aspects of the service (resource textkeys) which are different from the plugin textkey), and whose values are dictionaries with the following keys:

   • 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 None.

   • status: One of agent_util.SUPPORTED, agent_util.UNSUPPORTED or agent_util.MISCONFIGURED, to indicate that the metric can be collected, is unavailable, or available but missing some configuration that is preventing the plugin from measuring the metric value.

   • error_message: For misconfigured metrics, this message will be shown in the control panel to provide users additional information needed to properly fix the configuration issues.

   • 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.
     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, get_metadata is where you'd exercise it.

   • option_string: This will allow the check to be created with an open value field in the Control Panel that will be passed down to the agent on execution. This option can be any value you want, from a file name to a port number.

5. Implement the check() method. The purpose of this method is to actually measure the thing you want to monitor and return its value. It takes 3 arguments: textkey, data, and config. Textkey is one of the resource textkeys in the dictionary's keys you returned from get_metadata. It defines the specific aspect of the service you wish to monitor. Data is one of the items from the options list you returned in the get_metadata() (or None if no option is selected). Config is your plugin's specific configuration, the exact same object passed into get_metadata, explained more in the "Agent plugin configuration" section.

   Check() 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.
   If you included option_string, the value you defined on the check will be passed on to the agent as the data parameter. You can then proceed to use this value as your custom plugin needs.

Advanced Techniques

Using result data between multiple calls of check() (for example, for creating amount-per-second averages) can be accomplished by using the cache_result and get_cache_results methods from within check(). cache_result takes 3 arguments: the resource textkey and the data being passed in to check() (for example, the net interface to monitor) and a result that you want to store. get_cache_results takes 2 required arguments: the resource textkey, the data, and 1 optional argument: the number of results to return. It returns a list of cached results (default: 1) of the format:

(delta, result)

Where delta is how many seconds ago the result was retrieved, and the result is the result stored when cache_result was called. Take a look at the bandwidth plugin to see how these method calls can be used to create and return kilobytes/second transfer rates.

Automating Deployment

If you have a large infrastructure footprint and want to automate the deployment and handling of custom plugins across different servers, you can set your custom plugins to be automatically fetched during installation. This saves you from having to manage this separately. More information on this can be found in Use the FortiMonitor Agent manifest file.