OnSight custom metrics

Getting Started

You can add your own custom plugins to the OnSight that 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.

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.

Automating deployment

If you have written your own custom plugins, you can host them centrally and have them installed automatically during OnSight installation, so that you do not have to manually manage them post-install. Also, the plugins will be automatically re-fetched once an hour.

You can define custom_plugin_url in the OnSight manifest file (/etc/panopta-onsight-manifest). The value of this variable can be a compressed archive (.zip, .tar or .tgz) or a single python file (with a .py extension).

You can download plugins manually through the OnSight CLI onsight download-custom-plugin. This command also provides option to set or change custom_plugin_url variable using --url option.

Usage: onsight download-custom-plugin [OPTIONS]

	Download custom plugins from custom_plugin_url specified in the manifest

	file. custom_plugin_url can be set or changed with --url option. The url can

	be a compressed archive (.zip, .tar or .tgz) or a single python file (with a

	.py extension).

Options:

	--url TEXT

	--help      Show this message and exit.