Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Instance Scope Plugins

 

Instance scope plugin is supported to extend the previous host scope plugin. It's purpose is to monitor user-defined metrics and associate them with instances that are defined by instance type aggregate. Currently, the plugin type REST is supported. REST plugins allow you to receive structured metrics data from one or multiple endpoints, then monitors and analyzes those metrics on the Dashboard.

Creating an Instance Scope Plugin

To create an instance scope plugin, provide an executable command that produces output in a valid Nagios-Style string format. The command takes two arguments: instance id and input parameters in a JSON string. The input parameters argument contains whatever information that is needed to get metrics data, such as one or multiple endpoints, authentication, and so on.

Endpoint is the source of metrics data. Data retrieved from endpoints for each instance is suggested to follow the following JSON format. For each instance, there is a roomKey field whose value is the instance_id, which is used for display in the Dashboard. If the data is not in this format, you can process the raw data in the get_plugin_metrics_data(argv) function in the demo_check_instance_plugin.py file.

Table 1 describes the metric fields.

Table 1: Explanation of Metrics Fields in Instance Plugin

Field

Description

metric.value

Must contain only digits and optional decimal point: [0-9]+.?[0-9].

metric.units

Must be a valid string that starts with a letter.

metric.name

Must be a valid string that starts with a letter.

metric.type

Must be a valid string that starts with a letter. Valid option: value.

For each instance in the aggregate, the command is executed to get corresponding metrics data from input parameters. In the Appformix download files, the sample script demo_check_instance_plugin.py is provided and produces the following output format through the REST GET endpoint URL. Customize this sample file according to your specific needs.

Example: Following is an example demo_check_instance_plugin.py script:

Example: Metrics data for instance.

The example uses:

  • instanceid—3a0b1cf8-037a-4005-88e6-929c9c0e44f4

  • parameters—'{"Endpoint": "http://172.24.82.192:5000/metrics_data"}'

After running the command, output is as follows:

Configuring an Instance Scope Plugin

To add the instance scope plugin, define a JSON configuration file which specifies how to execute the plugin and the metrics that are produced by the plugin. In the Appformix download files, the sample configuration file demo_instance_plugin.json is provided. You can customize this sample file according to your needs.

Example: Instance plugin configuration JSON file.

Table 2 describes the fields in the sample configuration.

Table 2: Explanation of Fields in Instance Plugin Configuration JSON File

Field

Description

AggregateId

Specifies an instance type aggregate. Plugin is installed and configured to run on instances in this aggregate.

Collection

A label applied to data produced by this plugin.

Config.CommandLine

The command to execute, For example, python demo_check_instance_plugin.py. Exclude the arguments list here.

MetricMap

A list of metrics produced by the plugin and the units of each metric (for display in the Dashboard).

PluginId

Plugin identifier in AppFormix. This must be unique among all configured plugins.

PluginName

Name of the plugin. Name is used as a prefix for the name of all metrics produced by the plugin.

PluginType

Type of plugin. Valid option: rest.

Scope

Scope of this plugin. Valid option: instance.

State

Specifies if plugin is active. Valid options: enabled, disabled.

MetaData

Specifies whatever information that is needed to get metrics data, such as endpoints, authentication, and so on. This will be passed as input parameters argument for the executable command.

Posting an Instance Scope Plugin to Appformix

After creating the configuration file for the instance scope plugin, the next step is to post your plugin to AppFormix, which is done by using the Ansible playbooks, as described in Command Plug-Ins. In the AppFormix installation directory, there is a directory named user_defined_plugins. Copy both the python and JSON files to this directory and include the plugin descriptor in the appformix_user_defined_plugins variable in group_vars/all. This variable must be initialized at the time of AppFormix Platform installation.

The user-defined instance plugin needs to be specified in the group_vars file as follows:

The AppFormix Ansible playbooks will copy these two types of files to all of the appropriate Agents and then configure the plugin in the AppFormix controller.