How to Monitor Websites Using Metadata

OpenNMS’ Metadata DSL (domain specific language) allows you to use dynamic configuration in parameter values to interpolate metadata into a parameter. The syntax allows for the use of patterns in an expression, whereby the metadata is replaced with a corresponding value during the collection process.

This use case describes how to use metadata to monitor websites.

Sample Scenario

One webserver hosts three websites:

We have the service installed on a webserver that has a public IP address 32.2.42.23. Each domain has a virtual host entry with corresponding DNS entries. The website serves the content on the default HTTPS port 443.

:information_source: We used a sample IP address that does not work in the real world.

We want to run a blackbox test using OpenNMS to ensure:

  • Websites are available with the virtual hostnames
  • opennms.org responds correctly with a 301 return code
  • Wiki entrypoint responds with a HTTP 200 OK return code
  • Planet news aggregator responds with a HTTP 200 OK return code with the root path “/”

Provision a Node in OpenNMS

Create a node for our webserver with the same name web01-srv.
Add IP interface with and assign three service tests for each website.

  • All tests use port 443 and we provision a metadata key port with value 443.

  • Create an IP interface

  • Assign service tests with metadata for each website provided on that interface

    • Web:wiki -> with metadata key vhost with value wiki.opennms.org and a key path with value /wiki/Main_page
    • Web:opennms -> with metadata key vhost with value www.opennms.org and a key with response with value 301
    • Web:planet -> with metadata key vhost with value planet.opennms.org and a key path with value /

:information_source: Metadata on the node level can be used on IP interfaces and services. IP interfaces can overwrite metadata from the node level and service metadata is the most specific and can overwrite from the IP interface.

Synchronize the requisition in the Web UI and import the defined node.

If you want to use the REST API, the equivalent XML requisition file looks like the following:

<?xml version="1.0" encoding="UTF-8"?>
<model-import xmlns="http://xmlns.opennms.org/xsd/config/model-import"
              date-stamp="2020-05-11T13:08:46.702+02:00"
              foreign-source="Websites"
              last-import="2020-05-11T13:08:51.738+02:00">
   <node foreign-id="web01-srv" node-label="web01-srv">
      <interface ip-addr="32.2.42.23" status="1" snmp-primary="N">
         <monitored-service service-name="Web:wiki">
            <meta-data context="requisition" key="vhost" value="wiki.opennms.org" />
            <meta-data context="requisition" key="path" value="/wik/Main_Page" />
         </monitored-service>
         <monitored-service service-name="Web:opennms">
            <meta-data context="requisition" key="vhost" value="www.opennms.com" />
            <meta-data context="requisition" key="path" value="/" />
            <meta-data context="requisition" key="response" value="301" />
         </monitored-service>
         <monitored-service service-name="Web:planet">
            <meta-data context="requisition" key="vhost" value="planet.opennms.org" />
            <meta-data context="requisition" key="path" value="/" />
         </monitored-service>
      </interface>
      <meta-data context="requisition" key="port" value="443" />
   </node>
</model-import>

Create the test for the services

Tests run with Pollerd and we have to define the test behavior in poller-configuration.xml.
For SSL websites we use our HttpsMonitor which comes with OpenNMS.

<service name="Web-Site-Monitor" interval="300000" user-defined="true" status="on"> (1)
   <pattern><![CDATA[^Web:.*$]]></pattern> (2)
   <parameter key="retry" value="1" />
   <parameter key="timeout" value="3000" />
   <parameter key="port" value="${requisition:port}" /> (3)
   <parameter key="host-name" value="${requisition:vhost}" /> (4)
   <parameter key="url" value="${requisition:path}" /> (5)
   <parameter key="response" value="${requisition:response|200}" /> (6)
   <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
   <parameter key="rrd-base-name" value="http-${requisition:vhost}" /> (7)
   <parameter key="ds-name" value="${service:name}" /> (8)
</service>

<monitor service="Web-Site-Monitor" class-name="org.opennms.netmgt.poller.monitors.HttpsMonitor"/>(9)

(1) We call the test Web-Site-Monitor and it runs every 5 minutes (300000 ms)
(2) The test is applied on all service tests that match the regexp pattern ^Web:.*$, e.g., our provisoned services Web:opennms, Web:wiki, Web:planet)
(3) We replace the value here with the key port from requisition context
(4) Replacement for the value vhost from the requisition context
(5) Replacement for the value path from the requisition context
(6) Replacement for the value response from the requisition context and use 200 as default in case no response key is set
(7)(8) Replacement for the value vhost and service name to have unique response times for each web test
(9) Associate our HttpsMonitor with our Web-Site-Monitor

Reload configuration

Connect to the Karaf Shell with SSH using the Web UI admin password:

ssh admin@opennms-ip:8101
reload-daemon Pollerd

The services are now monitored.
You can add new websites following the naming pattern Web:.* and set service-specific parameters as you like.