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:
$ cat /Appformix/controller/tools/sdk/samples/demo_check_instance_plugin.py
import json
import sys
import traceback
import requests
import argparse
# Step 1 - Get metrics data from input parameters.
# The suggested output format for each instance is as follows.
# If the output is not in this format, please process your data
# in this function to follow this format.
# {
# <metric.name>: {
# "type": <metric.type>,
# "unit": <metric.units>,
# "value": <metric.value>
# },
# <metric.name>: {
# "type": <metric.type>,
# "unit": <metric.units>,
# "value": <metric.value>
# },
# "roomKey": {
# "type": "value",
# "unit": "roomKey",
# "value": <instance_id>
# }
# }
# The parameters argument is a JSON string which is entirely user defined.
# Thus please modify the code to get specific parameter,
# construct and rest get endpoint url according to your parameters format.
# And also add and process auth info as needed.
def get_plugin_metrics_data(argv):
instance_id = argv.instanceId
parameters = argv.parameters
endpoint = parameters.get('Endpoint', '')
parameters.pop('Endpoint')
url = endpoint + '/' + instance_id
try:
resp = requests.get(url=url, params=parameters)
output = json.loads(resp.text)
except Exception as e:
output = {}
return output
# Step 2 - Output metrics data as a Nagios-Style string.
# The output format is:
# OK - <plugin_name_suffix>: {"roomKey": {"type":
# "value", "value": <instance_id>, "unit": "roomKey"},
# "metric1": {"type": <metric1.type>, "value": <metric1.value>,
# "unit": <metric1.units>}, "metric2": {"type": <metric2.type>,
# "value": <metric2.value>, "unit": <metric2.units>}}
def main(argv):
result = get_plugin_metrics_data(argv)
try:
result = json.dumps(result)
msg = u"instance_plugin: {}".format(result)
except Exception as e:
traceback.print_exc()
msg = u'instance_plugin: {}'
print "OK - " + msg
sys.exit(0)
# Step 3 - Two arguments are taken for the command:
# instance id and input parameters in a JSON string.
# The JSON string contains whatever information
# that is needed to get metrics data,
# such as one or multiple endpoints, authentication, etc.
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument(
'-i', '--instanceId', help='Add an instanceId',
required=True, default='', type=unicode)
parser.add_argument(
'-p', '--parameters', help='Add input parameters',
required=True, default='{}', type=json.loads)
args = parser.parse_args()
sys.exit(main(args))
This script expects the data received for each instance to have the following JSON format.
{
<metric.name>: {
"type": <metric.type>,
"unit": <metric.units>,
"value": <metric.value>
},
<metric.name>: {
"type": <metric.type>,
"unit": <metric.units>,
"value": <metric.value>
},
"roomKey": {
"type": "value",
"unit": "roomKey",
"value": <instance_id>
}
}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.
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:
OK - <instance_plugin>: {"roomKey": {"type": "value", "value": <instance_id>, "unit":
"roomKey"}, "metric1": {"type": <metric1.type>, "value": <metric1.value>, "unit":
404
<metric1.units>}, "metric2": {"type": <metric2.type>, "value": <metric2.value>,
"unit": <metric2.units>}}Example: Metrics data for instance.
The example uses:
instanceid—3a0b1cf8-037a-4005-88e6-929c9c0e44f4parameters—'{"Endpoint": "http://172.24.82.192:5000/metrics_data"}'
{
"metric1": {
"type": "value",
"unit": "Count",
"value": 700
},
"metric2": {
"type": "value",
"unit": "Count",
"value": 700
},
"roomKey": {
"type": "value",
"unit": "roomKey",
"value": "3a0b1cf8-037a-4005-88e6-929c9c0e44f4"
}
}
After running the command, output is as follows:
$ python demo_check_instance_plugin.py -i 3a0b1cf8-037a-4005-88e6-929c9c0e44f4 -p '{"Endpoint": "http://172.24.82.192:5000/metrics_data"}'
OK - instance_plugin: {"roomKey": {"type": "value", "value": "3a0b1cf8-037a-4005-88e6-929c9c0e44f4", "unit": "roomKey"}, "metric1": {"type": "value", "value": 700, "unit": "Count"}, "metric2": {"type": "value", "value": 700, "unit": "Count"}}
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.
$ cat /Appformix/controller/tools/sdk/samples/demo_instance_plugin.json
{
"AggregateId": "instance_plugin_rest",
"Collection": "instance_plugin_collection",
"Config": {
"CommandLine": "python demo_check_instance_plugin.py"
},
"MetricMap": [
{
"Name": "metric1",
"Units": "Count"
},
{
"Name": "metric2",
"Units": "Count"
}
],
"PluginId": "instance_plugin_id",
"PluginName": "instance_plugin_name",
"PluginType": "rest",
"Scope": "instance",
"State": "enabled",
"MetaData": {
"Endpoint": "http://172.24.82.192:5000/metrics_data",
"Username": "username",
"Password": "password"
},
}
Table 2 describes the fields in the sample configuration.
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 |
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:
appformix_user_defined_plugins:
- { plugin_info: 'user_defined_plugins/demo_instance_plugin.json',
plugin_file: 'user_defined_plugins/demo_check_instance_plugin.py'}
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.