Creating a custom metric plugin

You can add your own custom metric plugins to the OnSight to allow you to collect metrics from remote devices. If you are just getting started, see Local development environment to develop plugins on your local machine.

1. Create a new python file in /usr/share/onsight/custom-metrics/ directory in host server.

2. You can start with the TemplatePlugin.py file, which defines the overall layout of the plugin class and the methods necessary to operate.
   Note that the class name needs to end in Plugin otherwise the plugin will not work, for example SNMPPlugin.

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.abc.myapplication.

4. Implement get_metadata(). This is the method that builds a list of information about the metrics that this plugin is able to collect. it should return a list of dictionaries, each with the following keys

   • metric_textkey: unique textkey that identifies this metric type within the plugin

   • name: human-friendly name for the metric, displayed in config UIs, graphs and alerts

   • description: human friendly description of the metric, displayed as supporting content when configuring the metric

   • unit: string which specifies the unit of the metric, or None if unit-less

   • resource_options: a list of options, for example port name, which uniquely identify a specific instance of the metric. Set to an empty list if there is only one instance of the metric.

5. implement get_data(). The purpose of this method is to actually measure the thing you want to monitor and return its value. It takes the following arguments

   • textkey: the specific metric type that should be gathered. one of metric_textkey returned from get_metadata().

   • option: the optional specifier for a specific instance of the metric, for example indicating what port on a switch to check. If not specified in resource_options returned from get_metadata(), it will have a value of None

   • instance_id: the global ID of the target instance that aligns with what is present in the control panel or FortiMonitor API

   • hostname: the IP or FQDN of the target instance

   • device_type, device_sub_type: strings which specify the type of the instance

   • tags: list of strings with each tag that's applied to the instance

   • attributes: dictionary of attribute keys and values that have been applied to the instance

6. If your plugin requires other python packages, you can install them under /usr/share/onsight/dependencies/ directory. For example, if your plugin requires pyyaml package, you can install it with this command. pip install -t /usr/share/onsight/dependencies pyyaml

7. You can copy or generate ssh keys under /usr/share/onsight/ssh-keys/ directory, which can be used with ssh helper functions to SSH to remote devices

8. You can create the config of secret repos under /usr/share/onsight/secrets/ directory. Currently, FortiMonitor supports Hashicorp Vault for secret repos.