Scripting Adapter

Although the primary purpose of NetFlow and IPFIX is to analyze network flows, there are also cases where the collected data is to be analyzed in other ways. One example would be the use of manufacturer-specific metrics with the help of IPFIX that are not flow-related. These metrics can be evaluated using the telemetry scripting adapters and, if necessary, persisted as metrics. To enable this, the Horizon Telemetryd parsers must be configured to parse and handle all flow data beside the flow-related values.

Enabling Raw Messages

The includeRawMessage parameter configures a parser to send the unprocessed flow values to the corresponding adapters. The following example shows a snippet of the telemetryd-configuration.xml file where includeRawMessage is enabled for the IPFIX parser.

...
    <!-- Multi-port listener for Netflow v5, Netflow v9, IPFIX and SFlow -->
    <listener name="Multi-UDP-9999" class-name="org.opennms.netmgt.telemetry.listeners.UdpListener" enabled="true">
        <parameter key="port" value="9999"/>

        <parser name="Netflow-5-Parser" class-name="org.opennms.netmgt.telemetry.protocols.netflow.parser.Netflow5UdpParser" queue="Netflow-5">
            <parameter key="includeRawMessage" value="false"/>
        </parser>
        <parser name="Netflow-9-Parser" class-name="org.opennms.netmgt.telemetry.protocols.netflow.parser.Netflow9UdpParser" queue="Netflow-9">
            <parameter key="includeRawMessage" value="false"/>
        </parser>
        <parser name="IPFIX-TCP-Parser" class-name="org.opennms.netmgt.telemetry.protocols.netflow.parser.IpfixUdpParser" queue="IPFIX">
            <parameter key="includeRawMessage" value="true"/>
        </parser>

        <parser name="SFlow-Parser" class-name="org.opennms.netmgt.telemetry.protocols.sflow.parser.SFlowUdpParser" queue="SFlow" />
    </listener>
...

Enabling Telemetry Scripting Adapter

To process the additional data, an additional Telemetryd adapter must be configured and enabled. This adapter specifies the processing script to use for processing the data. To do so, enable a Telemetry Adapter of type org.opennms.netmgt.telemetry.protocols.netflow.adapter.ipfix.IpfixTelemetryAdapter and specifying a Groovy file by using the script parameter. The following example shows a snippet of the telemetryd-configuration.xml file in which the IPFIX-Telemetry adapter is enabled and is using the script /opt/opennms/etc/telemetryd-adapters/netflow-telemetry.groovy.

...
    <queue name="IPFIX">
        <adapter name="IPFIX-Adapter" class-name="org.opennms.netmgt.telemetry.protocols.netflow.adapter.ipfix.IpfixAdapter" enabled="true">
            <parameter key="applicationDataCollection" value="false"/>
            <parameter key="applicationThresholding" value="false"/>
            <package name="IPFIX-Default">
                <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>
            </package>
        </adapter>

        <adapter name="IPFIX-Telemetry" class-name="org.opennms.netmgt.telemetry.protocols.netflow.adapter.ipfix.IpfixTelemetryAdapter" enabled="true">
            <parameter key="script" value="/opt/opennms/etc/telemetryd-adapters/netflow-telemetry.groovy"/>
            <package name="IPFIX-Default">
                <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>
            </package>
        </adapter>
    </queue>
...

Example script

The following example shows how to add a custom metric to the node-level resource. The raw message is passed as a key-value-map to the script. If unsure, which fields have been retrieved, just add a System.out.println(msg.keySet()); to the script and gather the logs for the output of available fields.

import org.opennms.netmgt.collection.support.builder.NodeLevelResource

NodeLevelResource nodeLevelResource = new NodeLevelResource(agent.getNodeId())

builder.withGauge(nodeLevelResource, "myMetricA", "myMetricA", (Long) msg.get("myMetricA"))
builder.withGauge(nodeLevelResource, "myMetricB", "myMetricB", (Long) msg.get("myMetricB"))