
= Configure Collector Packages
:description: Configure collector packages in {page-component-title} to provide information collectd needs to activate data collection: attributes and guidelines.

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:

* <<deep-dive/performance-data-collection/collectd/collection-packages.adoc#ga-coll-pack-attribute, Collector package attributes>>
* <<deep-dive/performance-data-collection/collectd/collection-packages.adoc#ga-collectd-packages-services, Collector package services>>

[[ga-coll-pack-attribute]]
== 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:

[source, xml]
----
<package name="cassandra-via-jmx" remote="false">
      <filter>IPADDR != '0.0.0.0'</filter>
----

NOTE: `remote="false"` means that the services in this package are tested only from the {page-component-title} 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:

[cols="1,3,3"]
|===
| Tag
| Description
| Example

| specific
| Specify an actual IP address to include in the package.
| <specific>192.168.1.59</specific>

| 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:

[source, xml]
----
<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.

[[ga-rrd-retention]]
== Default metric retention

include::../../retention.adoc[]

[[ga-collectd-packages-services]]
== 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:

[source, xml]
----
<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` (defined in the corresponding configuration for the type of collection--in this case the SNMP data collection config managed via *Admin -> Manage SNMP Data Collection Config*).
<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 xref:reference:performance-data-collection/introduction.adoc[] section.

[caption=]
.Common service attributes
[cols="1,3"]
[options="autowidth"]
|===
| 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.
|===

.Data collection with collectd
image::performance-management/02_collectd-configuration-xml.png["Network architecture diagram displaying configuration for data collection with collectd", 800]

== 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.

OR

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

[[ga-collectd-packages-services-meta-data]]
=== Metadata DSL

You can use the <<deep-dive/meta-data.adoc#ga-meta-data-dsl, 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
