Configure Collector Packages

Collector packages in collectd-configuration.xml contain the information (IP addresses, interfaces, services, and connection parameters) that collectd needs to activate data collection.

Collectd activates data collection for each node that contains an IP interface in the configured range and also contains any of the services listed in the package associated with the selected IP interface. You can edit existing collector packages or create new ones to customize data collection for your needs. If you create a new collector package, we recommend copying an existing package from collectd-configuration.xml to use as a template.

A collector package has two categories of information to edit or specify:

Collector package attributes
Collector package services

Collector package attributes

At a minimum, collector package attributes include a package name and a filter that specifies the interfaces to include in the collector package:

<package name="cassandra-via-jmx" remote="false">
      <filter>IPADDR != '0.0.0.0'</filter>

remote="false" means that the services in this package are tested only from the Meridian system itself, and not from a different remote location.

Each package must have a filter tag that performs the initial test to see if an interface is eligible to be included in a package. Filters operate on interfaces (not nodes). Each package can have only one filter tag.

The following tags are also available for an interface filter:

Tag

Description

Example

specific

Specify an actual IP address to include in the package.

include-range

Specify a range of IP addresses to include in a package.

<include-range begin="192.168.0.1" end="192.168.0.254"/>

exclude-range

Specify a range of IP addresses to exclude in a package. This overrides include-range.

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

include-url

Specify a file that contains a list of IP addresses to include.

<include-url>file:${OPENNMS_HOME}/etc/include</include-url>

The following example illustrates collector package attributes that use some of these additional tags:

<package name="example1" remote="false"> (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"/> (4)
  ...
</package>

1	Unique name of the collection package.
2	Apply this package to all IP interfaces with a configured IPv4 address (not equal to `0.0.0.0`).
3	Evaluate IPv4 rule to collect for all IPv4 interfaces in the given range.
4	Evaluate IPv6 rule to collect for all IPv6 interfaces in the given range.

Default metric retention

When using RRD/JRB storage, data is stored in the file system using a RRD-type strategy. With this "round robin" storage, data is kept in aggregated time buckets, with the latest bucket overwriting the oldest bucket. Multiple collections within the time period for a bucket will cause the data to be consolidated based on the type of bucket.

The aggregation buckets are defined in various config files based on a <RRD>…</RRD> block.

Default RRD config

<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	Step of 300 seconds (5 minutes) per bucket. This value should match the interval of the services in the package.
2	Store the average of 1 bucket for 2016 buckets. 5-minute averages kept for 7 days.
3	Store the average of 12 buckets for 1488 buckets. 1-hour average kept for 62 days.
4	Store the average of 288 buckets for 366 buckets. 1-day average kept for 366 days.
5	Store the maximum of 288 buckets for 366 buckets. 1-day max kept for 366 days.
6	Store the minimum of 288 buckets for 366 buckets. 1-day min kept for 366 days.

If the RRD definition is modified after data has been collected, you must manually delete the existing RRD/JRB files on disk so they can be recreated with the updated definition.

When using another storage strategy, such as Newts, Cortex, or other integration, all collected data points are persisted without aggregation. These points will be kept until the configured TTL expires. These storage strategies will ignore any defined <RRA> definitions in favor of the TTL value.

Service configuration attributes

Service configuration attributes define the collector to use and the performance metrics to collect. Each service is associated with a specific collector. The collector and its related Java class must appear at the bottom of the collectd-configuration.xml file:

<service name="SNMP" (1)
         interval="300000" (2)
         user-defined="false" (3)
         status="on"> (4)
  <parameter key="collection" value="default"/> (5)
  <parameter key="thresholding-enabled" value="true"/> (6)
</service>
...
<collector service="SNMP" class-name="org.opennms.netmgt.collectd.SnmpCollector"/> (7)

1	Service configuration name, which is mapped to a specific collector.
2	The interval at which the service is collected (in milliseconds).
3	Marker to say if service is user-defined (used for UI purposes).
4	Service is collected only if "on".
5	Assign the performance data collection schema named `default` (found in the corresponding configuration file for the type of collection—in this case `datacollection-config.xml`).
6	Enable threshold evaluation for metrics provided by this service.
7	Run the SnmpCollector implementation for the service named `SNMP`.

The following table lists service attributes common to all services. For a list of collector-specific parameters and their default values, refer to the specific collector listed in the Collectors section.

Common service attributes
Attribute	Description
name	Service name
interval	Collection interval, in milliseconds (5 minutes by default).
user-defined	If a user defined the collection source in the web UI, this is set to `true`.
status	Indicates that data collection for the service is on or off.

Network architecture diagram displaying configuration for data collection with collectd

Figure 1. Data collection with collectd

Guidelines for collector packages

You can configure multiple collector packages, and individual interfaces can exist in multiple packages. This allows for great flexibility in determining service levels for a given device.

When IP interfaces match multiple collector packages with the same service configuration, collectd applies the last collector package on the service:

Use this "final" collector package as a less-specific, catch-all filter for a default configuration.

Use it as a more specific collector package to overwrite the default setting.

Metadata DSL

You can use the metadata DSL to dynamically interpolate metadata into parameter values during the collection process.

During evaluation of an expression, the following scopes are available:

Node metadata
Interface metadata
Service metadata