Event Translator
Subscribe

From OpenNMS

Jump to: navigation, search

The Event Translator (ET) is an enterprise integration feature. The feature provides the network management professional with the ability to transform and enhance the data contained within OpenNMS events that are being generated by the other Daemons (monitoring processes). When an event is published on the event bus for which ET has configuration, it clones the event and changes the event's attributes (fields and parameters) as defined by the administrator in the translator configuration. These transformations can come from the result of SQL queries, regular expression matches, and string literals that are then assigned to attributes of the new event. It is an enterprise grade feature in that it allows for better integration with external systems based on data from sources internal and external to OpenNMS.

The Event Translator Service

As with most OpenNMS daemons, the EventTranslator has a companion configuration "factory" class that marshals its configuration from an XML formated file. The file, translator-configuration.xml file contains elements and attributes that create/change the fields or parameters of one event and publishes a new event with these changes. This feature has been used extensively for the following two reasons:

  1. To create passive status events (PSE) (see Passive Status Keeper)
  2. To associate an event with a different node.

Example 1

Here is an example for associating an event with a different node. The typical case for this would be an SNMP manager that proxies informational messages from non-SNMP entities to OpenNMS via an SNMP Trap. This allows the user to associate the Traps with a node other than the SNMP manager (typically a passive node) making correlation much easier.

<?xml version="1.0" encoding="UTF-8"?>
<event-translator-configuration
xmlns="http://xmlns.opennms.org/xsd/translator-configuration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
  <translation>
    <event-translation-spec uei="uei.opennms.org/mib2opennms/tspEventPCRRepetitionError">
      <!-- Each event can have 1 or more mappings. -->
      <mappings>
        <mapping>
          <!-- This mapping uses the SQL value type to query the DB and change the nodeid of the new event -->
          <assignment type="field" name="nodeid">
            <value type="sql" result="select node.nodeid from node, ipInterface where node.nodeLabel=? and ipinterface.ipaddr=? and node.nodeId=ipinterface.nodeid and ipInterface.isManaged != 'D' and node.nodeType != 'D'" >
              <!-- These are sub value types that are used as parameters to the above sql as in JDBC speak -->
              <value type="parameter" name=".1.3.6.1.4.1.6768.6.2.2.5.0" matches="^([A-z]+) ([0-9]+).*" result="${1}-${2}" />
              <value type="constant" result="169.254.1.1" />
            </value>
          </assignment>
        </mapping>
      </mappings>
    </event-translation-spec>
  </translation>
</event-translator-configuration>

In this example, the nodeid will be replaced with the resulting nodeid from the SQL query when an event with the uei "uei.opennms.org/mib2opennms/tspEventPCRRepetitionError" is received. The ?'s in the SQL query are populated with the values obtained from the nested value elements. The first of the nested value elements creates a result string from a regular expression match of the event parameter named ".1.3.6.1.4.1.6768.6.2.2.5.0". For this example, we will use the string "DEMO 10 example server" to represent the value of the parameter. The resulting match would produce "DEMO-10". The second nested value is a constant and simply returns the value "169.254.1.1". These are assembled into the SQL query.

SELECT node.nodeid
FROM node, ipInterface
WHERE node.nodeLabel='DEMO-10'
    AND ipinterface.ipaddr='169.254.1.1'
    AND node.nodeId=ipinterface.nodeid
    AND ipInterface.isManaged != 'D'
    AND node.nodeType != 'D'

The query is then executed. The value returned is then subsitituted for the existing nodeid into a new event cloned from the original event.

Example 2

Here is an example for an Adtran TA4303. I had a bunch of varbinds that I needed to lookup so I made a SQL table 'etlookup'. In that table I would lookup the variable name and the input value and an output value. The specific value that this node uses is different for each of the different problem's that each interface can have (AIS, Yellow alarm, LOS, etc). All of the problems that have a state that I can track are created as services (the T1's tend to flap). Since each of the 80 T1 ports on this box do not have IP addresses I ended up making a new node. When I tried to add those to the existing node it kept disabling all of the services that I added (anywho). To get the IP address I made another SQL table 'ta4303' and to do query with the port & slot to get the description. I store that text value in a new variable 'portdesc'. I use that variable in the event and later the notification '%parm[portdesc]%'.

<event-translation-spec uei="uei.opennms.org/vendor/adtran/traps/adta4303">
<mappings>
	<mapping>
	        <assignment type="field" name="passiveNodeLabel">
			<value type="constant" result="Switch - TA4303" />
		</assignment>
	        <assignment type="field" name="nodeid">
			<value type="constant" result="307" />
		</assignment>
		<assignment type="parameter" name="passiveIpAddr">
			<value type="sql" result="select ta4303.ip from ta4303 where ta4303.slot=? and ta4303.port=? " >
				<value type="parameter" name=".1.3.6.1.4.1.664.5.13.2.3.1.1" matches="^([0-9]+)" result="${1}" />
				<value type="parameter" name=".1.3.6.1.4.1.664.5.13.3.3.1.1" matches="^([0-9]+)" result="${1}" />
			</value>
		</assignment>
		<assignment type="parameter" name="portdesc">
			<value type="sql" result="select ta4303.description from ta4303 where ta4303.slot=? and ta4303.port=? " >
				<value type="parameter" name=".1.3.6.1.4.1.664.5.13.2.3.1.1" matches="^([0-9]+)" result="${1}" />
				<value type="parameter" name=".1.3.6.1.4.1.664.5.13.3.3.1.1" matches="^([0-9]+)" result="${1}" />
			</value>
		</assignment>
		<assignment type="parameter" name="passiveServiceName">
			<value type="sql" result="select etlookup.output from etlookup where etlookup.variable='ta4303service' and etlookup.input=? " >
				<value type="parameter" name="specifc" matches="^([0-9]+)" result="${1}" />
			</value>
		</assignment>
        	<assignment type="parameter" name="passiveStatus" >
			<value type="sql" result="select etlookup.output from etlookup where etlookup.variable='ta4303status' and etlookup.input=? " >
				<value type="parameter" name="specifc" matches="^([0-9]+)" result="${1}" />
			</value>
		</assignment>
		<assignment type="field" name="uei">
            		<value type="constant" result="uei.opennms.org/services/passiveServiceStatus" />
		</assignment>
	</mapping>
</mappings>
</event-translation-spec>

Example 3

Say the SQL statement you want to read data with returns multiple rows. The Event translator will only give you one result row a the new parameter. A workaround is to create an aggregate function in psql that accumulates the output to one single row. A use-case was to include (probably multiple) categories' names into a nodeCategoryMembershipChanged event.

create SQL aggregate
CREATE AGGREGATE array_accum (anyelement)
(
    sfunc = array_append,
    stype = anyarray,
    initcond = '{}'
);
translator config
<event-translation-spec uei="uei.opennms.org/nodes/nodeCategoryMembershipChanged">
	<mappings>
		<mapping>
			<assignment name="uei" type="field" >
				<value type="constant" result="uei.opennms.org/test/nodeCategoryMembershipChanged" />
			</assignment>
			<assignment name="categories" type="parameter">
				<value type="sql" result="select array_accum(categoryname) from categories,category_node,node where node.nodeid=?::integer and node.nodeid=category_node.nodeid and category_node.categoryid=categories.categoryid;" >
					<value type="field" name="nodeid" matches=".*" result="${0}" />
				</value>
			</assignment>
		</mapping>
	</mappings>
</event-translation-spec>