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