ON THIS PAGE
Examples: Monitors
This section assumes that Test Agents (as many as are required by the monitors) have been created according to the section Creating and Deploying a New Test Agent.
YANG Model Paths for Monitors
| Item | YANG model path: /accounts/account/monitors ... |
|---|---|
| monitors | /. |
| monitor[name] | /monitor |
| name | /monitor/name |
| description | /monitor/description |
| started | /monitor/started |
| template | /monitor/template |
| alarm-configs | /monitor/alarm-configs |
| Item | YANG model path: /accounts/account/monitors/monitor/alarm-configs ... |
|---|---|
| alarm-config[identifier] | /alarm-config |
| identifier | /alarm-config/identifier |
| template | /alarm-config/template |
| /alarm-config/email | |
| snmp | /alarm-config/snmp |
| thr-es-critical | /alarm-config/thr-es-critical |
| thr-es-critical-clear | /alarm-config/thr-es-critical-clear |
| thr-es-major | /alarm-config/thr-es-major |
| thr-es-major-clear | /alarm-config/thr-es-major-clear |
| thr-es-minor | /alarm-config/thr-es-minor |
| thr-es-minor-clear | /alarm-config/thr-es-minor-clear |
| thr-es-warning | /alarm-config/thr-es-warning |
| thr-es-warning-clear | /alarm-config/thr-es-warning-clear |
| no-data-severity | /alarm-config/no-data-severity |
| no-data-timeout | /alarm-config/no-data-timeout |
| action | /alarm-config/action |
| window-size | /alarm-config/window-size |
| interval | /alarm-config/interval |
| send-only-once | /alarm-config/send-only-once |
| snmp-trap-per-stream | /alarm-config/snmp-trap-per-stream |
| Item | YANG model path: /accounts/account/monitors ... |
|---|---|
| parameters | /monitor/parameters |
| Item | YANG model path: /accounts/account/monitors/monitor/parameters ... |
|---|---|
| parameter[key] | /parameter |
| key | /parameter/key |
| (value-type) | /parameter |
| :(integer) | /parameter |
| integer | /parameter/integer |
| :(float) | /parameter |
| float | /parameter/float |
| :(string) | /parameter |
| string | /parameter/string |
| :(test-agent-interfaces) | /parameter |
| test-agent-interfaces | /parameter/test-agent-interfaces |
| test-agent-interface[1] | /parameter/test-agent-interfaces/ |
| account | /parameter/test-agent-interfaces/test-agent-interface/account |
| test-agent | /parameter/test-agent-interfaces/test-agent-interface/test-agent |
| interface | /parameter/test-agent-interfaces/test-agent-interface/interface |
| ip-version | /parameter/test-agent-interfaces/test-agent-interface/ip-version |
| :(twamp-reflectors) | /parameter |
| twamp-reflectors | /parameter/twamp-reflectors |
| twamp-reflector[name] | /parameter/twamp-reflectors/twamp-reflector |
| name | /parameter/twamp-reflectors/twamp-reflector/name |
| :(y1731-meps) | /parameter |
| y1731-meps | /parameter/y1731-meps |
| y1731-mep[name] | /parameter/y1731-meps/y1731-mep |
| name | /parameter/y1731-meps/y1731-mep/name |
| :(sip-accounts) | /parameter |
| sip-accounts | /parameter/sip-accounts |
| sip-account[2] | /parameter/sip-accounts/sip-account |
| account | /parameter/sip-accounts/sip-account/account |
| test-agent | /parameter/sip-accounts/sip-account/test-agent |
| interface | /parameter/sip-accounts/sip-account/interface |
| sip-address | /parameter/sip-accounts/sip-account/sip-address |
| :(iptv-channels) | /parameter |
| iptv-channels | /parameter/iptv-channels |
| iptv-channel[name] | /parameter/iptv-channels/iptv-channel |
| name | /parameter/iptv-channels/iptv-channel/name |
|
|
| Item | YANG model path: /accounts/account/monitors ... |
|---|---|
| status | /monitor/status |
| last-15-minutes | /monitor/status/last-15-minutes |
| status | /monitor/status/last-15-minutes/status |
| status-value | /monitor/status/last-15-minutes/status-value |
| last-hour | /monitor/status/last-hour |
| status | /monitor/status/last-hour/status |
| status-value | /monitor/status/last-hour/status-value |
| last-24-hours | /monitor/status/last-24-hours |
| status | /monitor/status/last-24-hours/status |
| status-value | /monitor/status/last-24-hours/status-value |
| templates | /templates |
| template[name] | /templates/template |
| name | /templates/template/name |
| description | /templates/template/description |
| parameters | /templates/template/parameters |
| parameter[key] | /templates/template/parameters/parameter |
| key | /templates/template/parameters/parameter/key |
| type | /templates/template/parameters/parameter/type |
Prerequisites for Monitor Orchestration
Before you can start a monitor through NETCONF using ncclient, you need to build a monitor template in the Control Center GUI as explained in the in-app help under "Tests and monitors" > "Creating templates". All fields specified as "Template input" in that template will be required as parameters in the XML when orchestrating the initiation of the template.
Getting Input Parameters from Monitor Templates
Below, two templates are shown. The first is for UDP monitoring between two Test Agent interfaces, and the second is for HTTP using a single Test Agent interface.
To find out the input parameters of a template, click the box representing the template. For the HTTP template, the parameters may look like this:
We need to define these parameters in the next step when starting a monitor.
Starting a Monitor
Using the Test Agents that we defined and deployed in the section Creating and Deploying a New Test Agent, we can start a monitor from the template "HTTP" as shown below.
For each parameter, the <key> attribute needs to be supplied.
The key is identical to the parameter's Variable name in Control
Center. You can inspect variable names as follows:
- Click Monitoring on the side bar and select New Monitor.
- Click My Templates.
- Click the Edit link below the template of interest.
- Click the Edit input button in the top right corner.
In our example, and by default, the variable names are simply lowercase versions of the display names seen in Control Center ("url" vs. "URL", etc.). However, in the Control Center GUI, you can rename the variables to whatever you like.
Besides the key, each parameter needs to have its type specified: for example,
<string> for the URL. Please note that full information
on the parameter type is found in the YANG model. For Test Agent interfaces the type
has a more complex structure, as evidenced in the code below.
In the example that follows, no alarm is associated with the monitor. For examples involving alarms, go to the section Starting a Monitor with an Alarm.
with manager.connect(host=args.host, port=args.port, username=args.username,
password=args.password, hostkey_verify=False) as m:
# Apply configuration for a monitor, creating a monitor in Control Center
xml = """<config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<accounts xmlns="http://ncc.netrounds.com">
<account>
<name>{account}</name>
<monitors>
<monitor>
<name>{name}</name>
<template>{template}</template>
<parameters>
<parameter>
<key>url</key>
<string>{url}</string>
</parameter>
<parameter>
<key>clients</key>
<test-agent-interfaces>
<test-agent-interface>
<account>{account}</account>
<test-agent>{testagent}</test-agent>
<interface>{interface}</interface>
<ip-version>ipv4</ip-version>
</test-agent-interface>
</test-agent-interfaces>
</parameter>
</parameters>
</monitor>
</monitors>
</account>
</accounts>
</config>""".format(account=args.netrounds_account,
name='Web sites monitor',
template='HTTP',
testagent='vta1',
interface='eth0',
url='http://example.com',server='vTA1',
)
monitor = m.edit_config(target='running', config=xml)Run this script using ncclient. Provided that all is correct, the monitor will be initiated and started:
Starting a Monitor with an Alarm
To associate an alarm with a monitor, you can either point to an alarm template that has been defined, or you can supply the entire alarm configuration when creating the monitor. We will give one example of each approach below.
- Setting Up a Monitor Alarm by Pointing to an Alarm Template
- Setting Up a Monitor Alarm by Configuring It Directly
Setting Up a Monitor Alarm by Pointing to an Alarm Template
In order to make use of an alarm template, you must know its ID. To this end, first retrieve all your alarm templates as described in the section Retrieving All Alarm Templates and note the name of the relevant template. You can then refer to that template as follows:
# Note: This example requires an existing SNMP manager, alarm email list and monitor template in order to work
with manager.connect(host=args.host, port=args.port, username=args.username, password=args.password, hostkey_verify=False) as m:
# Apply configuration for a monitor, creating a monitor in Control Center
xml = """<config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<accounts xmlns="http://ncc.netrounds.com">
<account>
<name>{account}</name>
<monitors>
<monitor>
<name>{name}</name>
<template>{template}</template>
<alarm-configs>
<alarm-config>
<identifier>{id}</identifier>
<template>{alarm_template}</template>
<thr-es-critical>{thr_es_critical}</thr-es-critical>
</alarm-config>
</alarm-configs>
</monitor>
</monitors>
</account>
</accounts>
</config>""".format(account=args.netrounds_account,
name='HTTP monitor',
template='name_of_monitor_template',
id='name_of_alarm_config', # Enter a name for the alarm configuration here
alarm_template='name_of_alarm_template',
thr_es_critical=20) # The template value will be overridden by this one
print m.edit_config(target='running', config=xml)Setting Up a Monitor Alarm by Configuring It Directly
Alternatively, you can set up an alarm for a monitor by supplying its entire configuration when creating the monitor, without referring to an alarm template. This is done as shown in the following example.
# Note: This example requires an existing SNMP manager, alarm email list and monitor template in order to work
with manager.connect(host=args.host, port=args.port, username=args.username, password=args.password, hostkey_verify=False) as m:
# Apply configuration for a monitor, creating a monitor in Control Center
xml = """<config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<accounts xmlns="http://ncc.netrounds.com">
<account>
<name>{account}</name>
<monitors>
<monitor>
<name>{name}</name>
<template>{template}</template>
<parameters>
<parameter>
<key>url</key>
<string>{url}</string>
</parameter>
<parameter>
<key>clients</key>
<test-agent-interfaces>
<test-agent-interface>
<account>{account}</account>
<test-agent>{testagent}</test-agent>
<interface>{interface}</interface>
<ip-version>ipv4</ip-version>
</test-agent-interface>
</test-agent-interfaces>
</parameter>
</parameters>
<alarm-configs>
<alarm-config>
<identifier>{id}</identifier>
<email>{email}</email>
<snmp>{snmp}</snmp>
<action>{action}</action>
<window-size>{window_size}</window-size>
<interval>{interval}</interval>
<send-only-once>{send_only_once}</send-only-once>
<snmp-trap-per-stream>{snmp_trap_per_stream}</snmp-trap-per-stream>
<thr-es-critical>{thr_es_critical}</thr-es-critical>
<thr-es-critical-clear>{thr_es_critical_clear}</thr-es-critical-clear>
<thr-es-major>{thr_es_major}</thr-es-major>
<thr-es-major-clear>{thr_es_major_clear}</thr-es-major-clear>
<thr-es-minor>{thr_es_minor}</thr-es-minor>
<thr-es-minor-clear>{thr_es_minor_clear}</thr-es-minor-clear>
<thr-es-warning>{thr_es_warning}</thr-es-warning>
<thr-es-warning-clear>{thr_es_warning_clear}</thr-es-warning-clear>
</alarm-config>
</alarm-configs>
</monitor>
</monitors>
</account>
</accounts>
</config>""".format(account=args.netrounds_account,
name='HTTP monitor',
template='name_of_monitor_template',
testagent='vta1',
interface='eth0',
url='http://example.com',
id='alarm_config',
email='email_list',
snmp='snmp_manager',
action='some_action_string',
window_size=60,
interval=300,
send_only_once='false',
snmp_trap_per_stream='false',
thr_es_critical=9,
thr_es_critical_clear=8,
thr_es_major=7,
thr_es_major_clear=6,
thr_es_minor=5,
thr_es_minor_clear=4,
thr_es_warning=3,
thr_es_warning_clear=2)
print m.edit_config(target='running', config=xml)Retrieving Running Monitors
To retrieve all monitors that are currently executing, run this script:
with manager.connect(host=args.host, port=args.port, username=args.username,
password=args.password, hostkey_verify=False) as m:
# Get configuration for running monitors in account
xml = """<accounts xmlns="http://ncc.netrounds.com">
<account>
<name>{account}</name>
<monitors>
<monitor>
</monitor>
</monitors>
</account>
</accounts>""".format(account=args.netrounds_account)
monitor = m.get_config(source='running', filter=('subtree', xml)).data_xml
# Convert to ElementTree object
ele = to_ele(monitor)
# Convert back to XML string and print
print to_xml(ele, encoding='UTF-8', pretty_print=True)The output is a list of all running monitors as shown below:
<?xml version="1.0" ?>
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<accounts xmlns="http://ncc.netrounds.com">
<account>
<name xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">demo</name>
<monitors>
<monitor>
<name>Network Quality</name>
<template>UDP</template>
<parameters>
<parameter>
<key>clients</key>
<test-agent-interfaces>
<test-agent-interface>
<account>demo</account>
<test-agent>vTA1</test-agent>
<interface>eth1</interface>
<ip-version>ipv4</ip-version>
</test-agent-interface>
</test-agent-interfaces>
</parameter>
<parameter>
<key>server</key>
<test-agent-interfaces>
<test-agent-interface>
<account>demo</account>
<test-agent>vTA2</test-agent>
<interface>eth1</interface>
<ip-version>ipv4</ip-version>
</test-agent-interface>
</test-agent-interfaces>
</parameter>
</parameters>
</monitor>
</monitors>
</account>
</accounts>
</data>Retrieving SLA Status for a Monitor
Here is how to retrieve the SLA status for a monitor. In this example, we are retrieving the SLA status for the monitor "Network Quality" for three intervals of time: the last 15 minutes, the last hour, and the last 24 hours.
with manager.connect(host=args.host, port=args.port, username=args.username,
password=args.password, hostkey_verify=False) as m:
# Get status of monitor named "Network Quality" in account
xml = """<accounts xmlns="http://ncc.netrounds.com">
<account>
<name>{account}</name>
<monitors>
<monitor>
<name>Network Quality</name>
<status></status>
</monitor>
</monitors>
</account>
</accounts>""".format(account=args.netrounds_account)
monitor = m.get(filter=('subtree', xml)).data_xml
# Convert to ElementTree object
ele = to_ele(monitor)
# Convert back to XML string and print
print to_xml(ele, encoding='UTF-8', pretty_print=True)The output will look something like this:
<?xml version="1.0" ?>
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<accounts xmlns="http://ncc.netrounds.com">
<account>
<name xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">demo</name>
<monitors>
<monitor>
<name xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">Network Quality</name>
<status>
<id>27</id>
<last-15-minutes>
<status>good</status>
<status-value>100.0</status-value>
</last-15-minutes>
<last-hour>
<status>good</status>
<status-value>100.0</status-value>
</last-hour>
<last-24-hours>
<status>good</status>
<status-value>100.0</status-value>
</last-24-hours>
</status>
</monitor>
</monitors>
</account>
</accounts>
</data>NETCONF Notifications
NETCONF notifications for monitors are triggered by SLA violations. These occur when the SLA for the monitor drops below an SLA threshold ("Good" or "Acceptable") within a given time window, by default the last 15 minutes. It should be noted that SLA violation notifications are quick to appear after a service is impacted by an issue, while the SLA status will revert to "Good" only after 15 minutes, and only if no further violations occur.
The time window can be changed by editing the setting
SLA_STATUS_WINDOW (value in seconds) in
/etc/netrounds/netrounds.conf.
Exporting and Importing Monitor Templates
This is done in exactly the same way as for test templates; compare the section Exporting and Importing Test Templates. The code snippets below illustrate how to export and import templates for monitors.
Exporting Monitor Templates
with manager.connect(host=args.host, port=args.port, username=args.username,
password=args.password, hostkey_verify=False) as m:
# Export selected templates from Control Center
# In order to export all templates, remove the <templates></templates> node
export_xml = """
<export-monitor-templates xmlns="http://ncc.netrounds.com">
<account>{account}</account>
<templates>
<template>
<name>template_a</name>
</template>
<template>
<name>template_b</name>
</template>
</templates>
</export-monitor-templates>""".format(account=args.netrounds_account)
elem = to_ele(export_xml)
response = m.dispatch(elem)
# Get json config from response
root = ET.fromstring(response._raw)
json_config = root[0].text
print json_configImporting Monitor Templates
with manager.connect(host=args.host, port=args.port, username=args.username,
password=args.password, hostkey_verify=False) as m:
json_string = """
{
"templates":[
{
"input":[
{
"require_bridge":false,
# ...
# Insert rest of JSON string here
# ...
}
],
"version":"2.29",
"export_date":"2019-05-29T12:34:47.834430Z"
}
"""
# Import templates back to Control Center
import_xml = """
<import-monitor-templates xmlns="http://ncc.netrounds.com">
<account>{account}</account>
<overwrite>false</overwrite>
<data>{data}</data>
</import-monitor-templates>""".format(account=args.netrounds_account,
data=json_string)
elem = to_ele(import_xml)
response = m.dispatch(elem)
print response