Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Instance Scope Plug-Ins

 

Instance scope plug-in is provided as an extension to host scope plug-in. Its purpose is to monitor user-defined metrics and associate them with instances. The instances being monitored are expected to be members of an instance aggregate. Currently, the plug-in type REST is supported. REST plug-ins allow you to receive structured metrics data from one or multiple endpoints. This data can then be monitored and analyzed on the Dashboard.

Create Instance Scope Plug-In

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

The following is an example plug-in script called demo_check_instance_plugin.py:

This script expects the data received for each instance to have the following JSON format.

For each instance, there is a roomKey field whose value is the instance ID. This ID is used by the Dashboard to associate an instance with its data.

Table 1 describes the metric fields.

Table 1: Explanation of Metrics Fields in Instance Plug-In

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.

The sample script demo_check_instance_plugin.py produces output in the following format:

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:

Configure Instance Scope Plug-In

To add the instance scope plug-in, define a JSON configuration file which specifies how to execute the plug-in and the metrics that are produced by the plug-in. The following is a sample configuration file demo_instance_plugin.json. You can customize this sample file according to your needs.

Example: Instance plug-in configuration JSON file.

Table 2 describes the fields in the sample configuration.

Table 2: Explanation of Fields in Instance Plug-In Configuration JSON File

Field

Description

AggregateId

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

Collection

A label applied to data produced by this plug-in.

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 plug-in and the units of each metric (for display in the Dashboard).

PluginId

Plug-in identifier in Contrail Insights. This must be unique among all configured plug-ins.

PluginName

Name of the plug-in. Name is used as a prefix for the name of all metrics produced by the plug-in.

PluginType

Type of plug-in. Valid option: rest.

Scope

Scope of this plug-in. Valid option: instance.

State

Specifies if plug-in 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.

Post Instance Scope Plug-In to Contrail Insights

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

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

The Contrail Insights Ansible playbooks will copy these two types of files to all of the appropriate Agents and then configure the plug-in in the appFormix_controller.