# XmlCollector

The XmlCollector collects and extracts metrics from XML and JSON documents.

## Configuration and use

 Class Name `org.opennms.protocols.xml.collector.XmlCollector` Package core Supported on Minion Yes (see limitations) Configuration Files $OPENNMS_HOME/etc/xml-datacollection-config.xml$OPENNMS_HOME/etc/xml-datacollection.d/*.xml

### Limitations on Minion

The following handlers are not currently supported on Minion:

• DefaultJsonCollectionHandler

• Sftp3gppXmlCollectionHandler

• Sftp3gppVTDXmlCollectionHandler

## Configuration and use

Table 1. Collector-specific parameters for the XmlCollector
Parameter Description Default

Required

collection

The name of the XML Collection to use.

n/a

Optional

handler-class

Class that performs the collection.

org.opennms.protocols.xml.collector.DefaultXmlCollectionHandler

The available handlers include:

• org.opennms.protocols.xml.collector.DefaultXmlCollectionHandler

• org.opennms.protocols.xml.collector.Sftp3gppXmlCollectionHandler

• org.opennms.protocols.xml.vtdxml.DefaultVTDXmlCollectionHandler

• org.opennms.protocols.xml.vtdxml.Sftp3gppVTDXmlCollectionHandler

• org.opennms.protocols.json.collector.DefaultJsonCollectionHandler

• org.opennms.protocols.http.collector.HttpCollectionHandler

### Caveats

The `org.opennms.protocols.json.collector.DefaultJsonCollectionHandler` requires the fetched document to be a single element of type `object` to make xpath query work. If the root element is an array, it will be wrapped in an object accessible as `/elements`.

## XML collection configuration

Understanding resource types helps when editing collector-specific configuration files.

XML Collections are defined in `etc/xml-datacollection-config.xml` and `etc/xml-datacollection/`.

This snippet provides a collection definition named `xml-opennms-nodes`:

``````<xml-collection name="xml-opennms-nodes">
<rrd step="300">
<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>
<request method="GET">
<parameter name="use-system-proxy" value="true"/>
</request>
<import-groups>xml-datacollection/opennms-nodes.xml</import-groups>
</xml-source>
</xml-collection>``````

The request element can have the following optional child elements:

Parameter Description Default

timeout

The connection and socket timeout in milliseconds.

n/a

retries

How often to repeat the request in case of an error.

0

disable-ssl-verification

Do not attempt to verify the name on the SSL certificate against the `xml-source` URL attribute.

false

use-system-proxy

Should the system-wide proxy settings be used? Configure the system proxy settings via system properties.

false

The referenced `opennms-nodes.xml` file contains:

``````<xml-groups>
<xml-group name="nodes" resource-type="node" resource-xpath="/nodes">
<xml-object name="totalCount" type="GAUGE" xpath="@totalCount"/>
</xml-group>
</xml-groups>``````

If the endpoint being collected requires additional headers, you can add them as part of the `<request>` object.

``````  <xml-source url="https://{nodelabel}/api/path/to/endpoint">
<request method="GET">
</request>
<import-groups>xml-datacollection/file.xml</import-groups>
</xml-source>``````

## Test XML collection via Karaf

With the configuration in place, you can test it using the `collect` command available in the Karaf Shell:

``opennms:collect -n 1 org.opennms.protocols.xml.collector.XmlCollector 127.0.0.1 collection=xml-opennms-nodes``

## Mapping values

Sometimes data is represented as string values. These values are normally not persisted as time-series data; this means changes are not visible over time. To circumvent this, we allow mappings defined between input values and values to be persisted.

Let’s assume we have the following data input:

``````<records>
<record>
<input>aaa</input>
</record>
<record>
<input>bbb</input>
</record>
<record>
<input>ccc</input>
</record>
</records>``````

The following group configuration allows you to persist the `input` values as integer values over time:

``````<xml-group name="xml-mapping" resource-type="input" resource-xpath="/records/record" key-xpath="input">
<xml-object name="input" type="GAUGE" xpath="input"> (1)
<xml-mapping from="aaa" to="10" /> (2)
<xml-mapping from="bbb" to="20" />
<xml-mapping to="1000" /> (3)
</xml-object>
 1 The data-type is altered in the `xml-object` element from `STRING` to `GAUGE`. 2 In this example we associate `aaa` to `10` and `bbb` to `20`. 3 Define a default value by omitting the `from` attribute in a `xml-mapping` definition. In this example `ccc` will be associated with the default value of `1000`.