SNMP Trap Performance Data

The opennms-events-collector feature lets you persist performance data from SNMP traps as time-series data. Unlike SNMP collection where you can define data types, SNMP traps always embed values as strings. The events collector can take the string values from event parameters and convert them into numeric values to persist over time.

How it works

The feature uses matching within the event definition to check that the collection information exists.
It tries to look up parameters stated in the config against the event’s parameters.
If paramValue exists in the event definition, Meridian converts the matching key into numeric values.
Based on the collection setting, it will persist data into the designated resource type.

Configuration and use

Configure event definition for collection

This is an example of event collection config. Put the file in the ${OPENNMS_HOME}/etc/events directory and make sure it is registered in eventconf.xml. If your event will keep firing a lot and you only want the performance data without overwhelming the event table, consider setting <logmsg dest="donotpersist"></logmsg>.

<events xmlns="http://xmlns.opennms.org/xsd/eventconf">
    <event>
        <mask>
            <maskelement>
                <mename>id</mename>
                <mevalue>.1.3.6.1.4.1.22222.2.4.3.12.2.2</mevalue>
            </maskelement>
            <maskelement>
                <mename>generic</mename>
                <mevalue>6</mevalue>
            </maskelement>
            <maskelement>
                <mename>specific</mename>
                <mevalue>4</mevalue>
            </maskelement>
            <varbind>
                <vbnumber>1</vbnumber>
                <vbvalue>
                    <![CDATA[~.*Time=(?<TIME>[\d]*).*Value=(?<VALUE>[\d]+).*Status=(?<STATUS>[\w]+).*Tag=(?<TAG>[\w.]+).*]]></vbvalue>
            </varbind>
        </mask>
        <uei>uei.opennms.org/traps/test/regex</uei>
        <event-label>test: varbind with regex</event-label>
        <descr>Testing varbind with regex</descr>
        <logmsg dest="donotpersist"></logmsg>
        <collectionGroup name="nodeGroup" resourceType="nodeSnmp">
            <rrd step="60" heartBeat="120">
                <rra>RRA:AVERAGE:0.5:1:8928</rra>
            </rrd>
            <collection name="TIME" type="counter"/>
            <collection name="STATUS" type="gauge">
                <paramValue key="primary" value="1"/>
                <paramValue key="secondary" value="2"/>
            </collection>
        </collectionGroup>
        <collectionGroup name="eventTypeGroup" resourceType="eventType" instance="STATUS">
            <rrd step="60" heartBeat="120">
                <rra>RRA:AVERAGE:0.5:1:8928</rra>
            </rrd>
            <collection name="VALUE" type="gauge"/>
        </collectionGroup>
        <severity>Normal</severity>
    </event>
    <event>
        <mask>
            <maskelement>
                <mename>id</mename>
                <mevalue>.1.3.6.1.4.1.22222.2.4.3.12.2.2</mevalue>
            </maskelement>
            <maskelement>
                <mename>generic</mename>
                <mevalue>6</mevalue>
            </maskelement>
            <maskelement>
                <mename>specific</mename>
                <mevalue>5</mevalue>
            </maskelement>
        </mask>
        <uei>uei.opennms.org/traps/test/varbind</uei>
        <event-label>test: full varbind</event-label>
        <descr>Testing full varbind.</descr>
        <logmsg dest="donotpersist"></logmsg>
        <collectionGroup name="interfaceGroup" resourceType="interfaceSnmp">
            <rrd step="60" heartBeat="120">
                <rra>RRA:AVERAGE:0.5:1:8928</rra>
            </rrd>
            <collection name=".1.3.6.1.4.1.22222.2.4.3.12.2.21" rename="fulltext" type="gauge"/>
        </collectionGroup>
        <severity>Normal</severity>
    </event>
</events>

The example trap for the first event will look like the following:

snmptrap -v1 -c public 127.0.0.1:10162 .1.3.6.1.4.1.22222.2.4.3.12.2.2 '127.0.0.1' 6 4 100 .1.3.6.1.4.1.22222.2.4.3.12.2.21 s "Time=200 Value=300 Status=secondary Tag=Text"

Make sure the name used in varbind (for example, "regex") matches the event’s parameter name. The Value parameter must be numeric. If the value is a string, use a paramValue tag to create a key-value mapping to translate the string into a numeric value. When you are using generic-type time series, you will also want to register the instance parameter. It will become part of the name of the time series. (Just like system mount point, it is dynamically created based on input.)

Make sure to quote the regex in CDATA.

Create snmp-graph.properties

You need to create separate snmp-graph settings file in the ${OPENNMS_HOME}/etc/snmp-graph.properties.d directory.

reports=TIME, VALUE, STATUS, uei.opennms.org_traps_test_varbind

report.TIME.name=TIME
report.TIME.columns=TIME
report.TIME.type=nodeSnmp
report.TIME.command=--title="TIME" \
 --vertical-label="Time in seconds" \
 DEF:octIn=\{rrd1}:TIME:AVERAGE \
 AREA:octIn#73d216: \
 LINE1:octIn#4e9a06:"In " \
 GPRINT:octIn:AVERAGE:"Avg  \\: %8.2lf %s" \
 GPRINT:octIn:MIN:"Min  \\: %8.2lf %s" \
 GPRINT:octIn:MAX:"Max  \\: %8.2lf %s\\n"

report.STATUS.name=STATUS
report.STATUS.columns=STATUS
report.STATUS.type=nodeSnmp
report.STATUS.command=--title="STATUS" \
 --vertical-label="Numeric status value" \
 DEF:octIn=\{rrd1}:STATUS:AVERAGE \
 AREA:octIn#73d216: \
 LINE1:octIn#4e9a06:"In " \
 GPRINT:octIn:AVERAGE:"Avg  \\: %8.2lf %s" \
 GPRINT:octIn:MIN:"Min  \\: %8.2lf %s" \
 GPRINT:octIn:MAX:"Max  \\: %8.2lf %s\\n"

report.VALUE.name=VALUE
report.VALUE.columns=VALUE
report.VALUE.type=eventType
report.VALUE.command=--title="VALUE" \
 --vertical-label="Some units" \
 DEF:octOut=\{rrd1}:VALUE:AVERAGE \
 AREA:octOut#73d216: \
 LINE1:octOut#4e9a06:"Out " \
 GPRINT:octOut:AVERAGE:"Avg  \\: %8.2lf %s"

report.uei.opennms.org_traps_test_varbind.name=uei.opennms.org_traps_test_varbind
report.uei.opennms.org_traps_test_varbind.columns=uei.opennms.org_traps_test_varbind
report.uei.opennms.org_traps_test_varbind.type=interfaceSnmp
report.uei.opennms.org_traps_test_varbind.command=--title="uei.opennms.org_traps_test_varbind" \
 --vertical-label="Bytes per second" \
 DEF:octIn=\{rrd1}:uei.opennms.org_traps_test_varbind:AVERAGE \
 AREA:octIn#73d216: \
 LINE1:octIn#4e9a06:"In " \
 GPRINT:octIn:AVERAGE:"Avg  \\: %8.2lf %s"

Note that the value {NAME} in the attribute columns (report.{REPORT}.columns={NAME}) should match the collection name from an event configuration (<collection name=“{NAME}” type="{TYPE}"/>) and the expression in DEF (DEF:octIn={rrd1}:{NAME}:AVERAGE).

You can view the resulting performance graphs in Reports Resource Graphs.

Create resource-types (optional)

If your time series data type is not nodeSnmp or interfaceSnmp, you need to create a resource-type file in ${OPENNMS_HOME}/etc/resource-types.d. Make sure you match the name with the event definition’s resourceType. There is also ${instance} variable available that you can use to enrich the resource type’s label.

<resource-types>
    <resourceType name="eventType" label="Event Application" resourceLabel="Instance ${instance}">
        <persistenceSelectorStrategy class="org.opennms.netmgt.collection.support.PersistAllSelectorStrategy"/>
        <storageStrategy class="org.opennms.netmgt.collection.support.IndexStorageStrategy"/>
    </resourceType>
</resource-types>

Enable opennms-events-collector in Karaf

To load the events collector into your currently running Meridian instance, run the following Karaf command.

feature:install opennms-events-collector

To ensure that the feature continues to be installed on subsequent restarts, create or edit the ${OPENNMS_HOME}/etc/featuresBoot.d/events.boot file to include opennms-events-collector.