Trapd

Handles processing of SNMP traps into events. Based around traditional UDP-based SNMP traps, it receives traps that remote devices create. It enables OpenNMS to receive SNMP traps and convert them into events and, if configured accordingly, convert those events into alarms and notifications. Its functionality is similar to how syslogd handles syslog entries.

Trapd supports V1 traps, V2 traps and notifications, and V3 traps and notifications. It also accepts traps with any community name (V1, V2c). You can use that community name in event definitions as part of a mask.

How it works

When an SNMP trap arrives, trapd parses the message, comparing the sender to known nodes. If the sender is not a monitored node and the new-suspect-on-trap parameter is set to true, Meridian sends an event to discover the node. Otherwise, Meridian tags the trap to the monitored node, broadcasts it to eventd, and the trap becomes a Meridian event.

Table 1. Trapd configuration file overview
File Description Reload Event Restart Required

trapd-configuration.xml

Configure generic behavior of trapd (for example, port numbers with IP addresses to listen for traps).

yes

no

events/*.xml

Defines mapping between OIDs and UEIs. Files in this folder must be specified as an include directive in eventconf.xml.

yes

no
Table 2. Trapd log file overview
File Description

trapd.log

Logs relating to trapd server events.

Additional information

For information on how to automate alarms and reduce the number of messages, see Syslogd Automations on Discourse.

You can configure the eventd subsystem to discard unwanted SNMP traps. To do so, use the discardtraps logmsg. See Anatomy of an event in the Event Daemon Configuration section for more information.

Note that for V3, you must specify the SNMPv3 credentials used to authenticate and decode V3 traps in trapd-configuration.xml, as in the following example:

<trapd-configuration snmp-trap-port="162" new-suspect-on-trap="true">
  <snmpv3-user security-name="opennms" auth-passphrase="0p3nNMSv3" auth-protocol="MD5"
      privacy-passphrase="0p3nNMSv3" privacy-protocol="DES"/>
  <snmpv3-user security-name="sample-name" auth-passphrase="secret" auth-protocol="MD5"
      privacy-passphrase="super-secret" privacy-protocol="DES"/>
</trapd-configuration>

For privacy-protocol, the available options are DES, AES, AES192, and AES256 For auth-protocol, the available options are MD5, SHA, SHA-224, SHA-256, and SHA-512

Metadata expressions can also be used in attributes of the trapd-configuration.xml configuration file. This lets the user to also reference credentials stored in the secure credentials.

Trap metrics

Trapd exposes metrics via JMX for monitoring trap processing performance. Metrics are available at two levels: global metrics that are always enabled, and per-device metrics that can be optionally enabled.

Global metrics

Global trap metrics are always available and provide an overview of trap processing across all devices.

Core (OpenNMS:Name=Trapd)

Metric Type Description

RawTrapsReceived

Counter

Total raw SNMP traps received at the listener before any processing

TrapsReceived

Counter

Total traps received at the consumer after dispatch

V1TrapsReceived

Counter

SNMPv1 traps received

V2cTrapsReceived

Counter

SNMPv2c traps received

V3TrapsReceived

Counter

SNMPv3 traps received

VUnknownTrapsReceived

Counter

Traps with unknown SNMP version received

TrapsDiscarded

Counter

Traps discarded by user configuration

TrapsErrored

Counter

Traps that encountered processing errors

CurrentQueueSize

Gauge

Current number of messages in the dispatch queue

MaxQueueSize

Gauge

Configured maximum queue size

BatchSize

Gauge

Configured batch size for trap aggregation

Minion (org.opennms.netmgt.trapd)

On Minion, global metrics are exposed as Dropwizard metrics under the org.opennms.netmgt.trapd JMX domain.

Metric Type Description

rawTrapsReceived

Counter

Total raw SNMP traps received at the listener

trapsErrored

Counter

Traps that failed during dispatch

currentQueueSize

Gauge

Current number of messages in the dispatch queue

maxQueueSize

Gauge

Configured maximum queue size

batchSize

Gauge

Configured batch size for trap aggregation

Per-device metrics

Per-device metrics allow tracking trap activity for individual devices, identified by IP address and location. This feature is disabled by default and must be explicitly enabled.

Enabling device metrics

For Core, add the following system property to ${OPENNMS_HOME}/etc/opennms.properties.d/trapd.properties:

org.opennms.netmgt.trapd.enableDeviceMetrics=true

For Minion, add the following to ${MINION_HOME}/etc/org.opennms.netmgt.trapd.cfg:

trapd.enableDeviceMetrics=true

Listener-side metrics (Minion)

Each device that sends traps gets a JMX MBean registered under org.opennms.netmgt.trapd.device with type=listener.

Metric Type Description

RawTrapsReceived

Counter

Raw SNMP traps received from this device

TrapsErrored

Counter

Traps from this device that failed during dispatch

Consumer-side metrics (Core)

Each device that sends traps gets a JMX MBean registered under org.opennms.netmgt.trapd.device with type=consumer.

Metric Type Description

TrapsReceived

Counter

Traps received from this device at the consumer

TrapsDiscarded

Counter

Traps from this device discarded by user configuration

TrapsErrored

Counter

Traps from this device that encountered processing errors

Prometheus integration

When using the JMX Prometheus Exporter, device metrics can be scraped with the following rule:

- pattern: 'org\.opennms\.netmgt\.trapd\.device<location=(.+),ip=(.+),type=(.+)><>(\w+)'
  name: trapd_device_$4
  type: COUNTER
  labels:
    location: "$1"
    ip: "$2"
    type: "$3"

This produces Prometheus metrics such as:

trapd_device_rawtrapsreceived{location="Default",ip="10.0.0.1",type="listener"} 1024
trapd_device_trapserrored{location="Default",ip="10.0.0.1",type="consumer"} 3
This rule is included by default in the container-based JMX Prometheus Exporter configuration for both Core and Minion.