Poller Packages

You can group service configurations into polling packages to define more complex monitoring configurations. This allows you to assign different service configurations to nodes. To assign a polling package to nodes, use the filter syntax.

Each polling package can have its own Downtime Model configuration. You can configure multiple packages, and an interface can exist in more than one package. This provides great flexibility for determining service levels on a given device.

Polling package assigned to nodes with rules and filters

<package name="example1"> (1)
  <filter>IPADDR != '0.0.0.0'</filter> (2)
  <include-range begin="1.1.1.1" end="254.254.254.254" /> (3)
  <include-range begin="::1" end="ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" /> (3)

1	The polling package’s unique name.
2	Base filter on IP address, categories, or asset attributes of nodes based on filter rules. The filter is evaluated first and is required. This package is used for all IP interfaces that do not have `0.0.0.0` as an assigned IP address and is required.
3	Allows you to specify if the configuration of services is applied on a range of IP interfaces (IPv4 or IPv6).

Instead of using include-range, you can add one or more specific IP interfaces:

<specific>192.168.1.59</specific>

You can also exclude IP interfaces:

<exclude-range begin="192.168.0.100" end="192.168.0.104"/>

Response time configuration

The definition of polling packages lets you configure similar services with different polling intervals. All the response time measurements are persisted in RRD files and require a definition. Each polling package contains an RRD definition:

RRD configuration for polling package

<package name="example1">
  <filter>IPADDR != '0.0.0.0'</filter>
  <include-range begin="1.1.1.1" end="254.254.254.254" />
  <include-range begin="::1" end="ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" />
  <rrd step="300"> (1)
    <rra>RRA:AVERAGE:0.5:1:2016</rra> (2)
    <rra>RRA:AVERAGE:0.5:12:1488</rra> (3)
    <rra>RRA:AVERAGE:0.5:288:366</rra> (4)
    <rra>RRA:MAX:0.5:288:366</rra> (5)
    <rra>RRA:MIN:0.5:288:366</rra> (6)
</rrd>

1	Polling interval for all services in this polling package is reflected in the step size of 300 seconds. All services in this package must be polled on a 5-minute interval, otherwise response time measurements are not persisted correctly.
2	1 step size is persisted 2016 times: 1 * 5 min * 2016 = 7 d, 5 min accuracy for 7 d.
3	12 steps average persistence 1488 times: 12 * 5 min * 1488 = 62 d, aggregated to 60 min for 62 d.
4	288 steps average persistence 366 times: 288 * 5 min * 366 = 366 d, aggregated to 24 h for 366 d.
5	288 steps maximum from 24 h persisted for 366 d.
6	288 steps minimum from 24 h persisted for 366 d.

The RRD configuration and the service polling interval must be aligned. In other cases, the persisted response time data is not correctly displayed in the response time graph.

If you change the polling interval afterwards, you must recreate existing RRD files with the new definitions.

Service status persistence

You can configure each service monitor to store the current status of the service in RRD files. This lets you query the current status and the status history. This feature is disabled by default. You must enable it individually for each service. To do so, add a service parameter to the appropriate services in poller-configuration.xml:

<service name="EXAMPLE" ...>
  <parameter key="rrd-status" value="true"/>
</service>

Overlapping services

Because you can specify multiple polling packages, you can use the same service (like ICMP) multiple times. The order that polling packages are defined in poller-configuration.xml is important when IP interfaces match multiple polling packages with the same service configuration.

The following shows which configuration is applied for a specific service:

<package name="less-specific">
  <filter>IPADDR != '0.0.0.0'</filter>
  <include-range begin="1.1.1.1" end="254.254.254.254" />
  <include-range begin="::1" end="ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" />
  <rrd step="300"> (1)
    <rra>RRA:AVERAGE:0.5:1:2016</rra>
    <rra>RRA:AVERAGE:0.5:12:1488</rra>
    <rra>RRA:AVERAGE:0.5:288:366</rra>
    <rra>RRA:MAX:0.5:288:366</rra>
    <rra>RRA:MIN:0.5:288:366</rra>
  </rrd>
  <service name="ICMP" interval="300000" user-defined="false" status="on"> (2)
    <parameter key="retry" value="5" /> (3)
    <parameter key="timeout" value="10000" /> (4)
    <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response" />
    <parameter key="rrd-base-name" value="icmp" />
    <parameter key="ds-name" value="icmp" />
  </service>
  <downtime interval="30000" begin="0" end="300000" />
  <downtime interval="300000" begin="300000" end="43200000" />
  <downtime interval="600000" begin="43200000" end="432000000" />
</package>

<package name="more-specific">
  <filter>IPADDR != '0.0.0.0'</filter>
  <include-range begin="192.168.1.1" end="192.168.1.254" />
  <include-range begin="2600::1" end="2600:::ffff" />
  <rrd step="30"> (1)
    <rra>RRA:AVERAGE:0.5:1:20160</rra>
    <rra>RRA:AVERAGE:0.5:12:14880</rra>
    <rra>RRA:AVERAGE:0.5:288:3660</rra>
    <rra>RRA:MAX:0.5:288:3660</rra>
    <rra>RRA:MIN:0.5:288:3660</rra>
  </rrd>
  <service name="ICMP" interval="30000" user-defined="false" status="on"> (2)
    <parameter key="retry" value="2" /> (3)
    <parameter key="timeout" value="3000" /> (4)
    <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response" />
    <parameter key="rrd-base-name" value="icmp" />
    <parameter key="ds-name" value="icmp" />
  </service>
  <downtime interval="10000" begin="0" end="300000" />
  <downtime interval="300000" begin="300000" end="43200000" />
  <downtime interval="600000" begin="43200000" end="432000000" />
</package>

1	Polling interval for the packages is 300 seconds and 30 seconds.
2	Custom polling interval for the ICMP service.
3	Custom retry settings for the ICMP service.
4	Custom timeout settings for the ICMP service.

The last polling package on the service will be applied. You can use this to define a less specific catch-all filter as the default configuration. Use a more specific polling package to overwrite the default settings. In the previous example, all IP interfaces in 192.168.1/24 or 2600:/64 will be monitored with ICMP using custom polling, retry, and timeout settings.

The IP interface and service pages show which polling package and service configuration are applied for this specific service, and associated statistics.

Screen displaying interface and service configuration and statistics for a polling package

Figure 1. Polling package settings applied to IP interface and service

Service patterns

Usually, the poller that monitors a service is found by matching its name with the service name. There is an option for you to match a poller if you specify an additional pattern element. If so, the poller is used for all services matching the regex pattern.

The regex pattern lets you specify named capture groups. There can be multiple capture groups inside a pattern, but each must have a unique name. Note that the regex must be escaped or wrapped in a CDATA tag inside the configuration XML to make it a valid property.

If a poller is matched using its pattern, the parts of the service name that match the capture groups of the pattern are available as parameters to the Metadata DSL using the context pattern and the capture group name as key.

Examples

<pattern><![CDATA[^HTTP-(?<vhost>.*)$]]></pattern>: matches all services with names starting with HTTP- followed by a host name. If the service is called HTTP-www.example.com, the Metadata DSL expression ${pattern:vhost} will resolve to www.example.com.
<pattern><![CDATA[^HTTP-(?<vhost>.*?):(?<port>[0-9]+)$]]></pattern>: matches all services with names starting with HTTP- followed by a hostname and a port. There will be two variables (${pattern:vhost} and ${pattern:port}), which you can use in the poller parameters.

Use the service pattern mechanism whenever there are multiple instances of a service on the same interface. You can make services identifiable by specifying a distinct service name for each instance, but there is no need to add a poller definition for each service. Common use cases for such services are HTTP virtual hosts where multiple web applications run on the same web server, or BGP session monitoring where each router has multiple neighbors.

Manually test services

You can run a test via the Karaf shell to test the Horizon polling services:

ssh -p 8101 admin@localhost

In the shell, you can use opennms:poll --help to view the command’s help information.

The following example runs the ICMP monitor on a specific IP interface:

opennms> opennms:poll -S ICMP -P example1 10.23.42.1

The output is verbose, which lets you debug monitor configurations. Important output lines include the following:

Package: example1 (1)
Service: ICMP (2)
Monitor: org.opennms.netmgt.poller.monitors.IcmpMonitor (3)
Parameter ds-name: icmp (4)
Parameter retry: 2 (5)
Parameter rrd-base-name: icmp (4)
Parameter rrd-repository: /opt/opennms/share/rrd/response (4)
Parameter timeout: 3000 (5)

Service is Up on 192.168.31.100 using org.opennms.netmgt.poller.monitors.IcmpMonitor: (6)
	response-time: 407,0000 (7)

1	Service and package of this test.
2	Applied service configuration from polling package for this test.
3	Service monitor used for this test.
4	RRD configuration for response time measurement.
5	Retry and timeout settings for this test.
6	Polling result for the service polled against the IP address.
7	Response time.

Manually test filters

Filters are ubiquitous in the Horizon configurations that implement <filter> syntax. You can use the Karaf shell to verify filters. For more information, see Filters.

SSH to localhost

ssh -p 8101 admin@localhost

In the shell, you can use opennms:filter --help to view the command’s help information.

For example, you can run a filter rule that matches a location:

opennms:filter  "location='MINION'"

The output displays as follows:

nodeId=2 nodeLabel=00000000-0000-0000-0000-000000ddba11 location=MINION
	IpAddresses:
		127.0.0.1

You can also run a filter that matches a node location within a given IP address range:

opennms:filter "location='Default' & (IPADDR IPLIKE 172.*.*.*)"

The output displays as follows:

nodeId=3 nodeLabel=label1 location=Default
	IpAddresses:
		172.10.154.1
		172.20.12.12
		172.20.2.14
		172.01.134.1
		172.20.11.15
		172.40.12.18

nodeId=5 nodeLabel=label2 location=Default
	IpAddresses:
		172.17.0.111

nodeId=6 nodeLabel=label3 location=Default
	IpAddresses:
		172.20.12.22
		172.17.0.123

Displayed node information includes the nodeId, nodeLabel, location, and optional fields like foreignId, foreignSource, and categories (when they exist).

Monitor Microsoft AD services

To monitor Microsoft AD services, you must edit ${OPENNMS_HOME}/etc/poller-configuration.xml. See the Monitor Microsoft AD Services article on Discourse for more information.