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

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




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


Must be a valid string that starts with a letter.

Must be a valid string that starts with a letter.


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

The sample script produces output in the following format:

Example: Metrics data for instance.

The example uses:

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

  • parameters—'{"Endpoint": ""}'

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




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


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


The command to execute, For example, Python Exclude the arguments list here.


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


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


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


Type of plug-in. Valid option: rest.


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


Specifies if plug-in is active. Valid options: enabled, disabled.


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.