IBM Tivoli Monitoring, Version 6.3

EIF event mapping XML specification

The EIF event map is an XML file that specifies how the events for one or more private situations are to be translated. Create a custom event mapping file to modify the data being sent to the EIF receiver.

Event mapping file format

<itmEventMapping:agent>
  <id>xx</id>
  <version>n.n</version>
  <event_mapping>
    <situation>
      <slot>
        <mappedAttribute/>
          or
        <mappedAttributeEnum/>
          or
        <literalString/>
      </slot>
      : 			one or more slot tags
    </situation>

or

    <attributeTable>
      <slot>
        <mappedAttribute/>
          or
        <mappedAttributeEnum/>
          or
        <literalString/>
      </slot>
      : 			one or more slot tags
    </attributeTable>
  </event_mapping>
</itmEventMapping:agent>

Elements

XML tags are case-insensitive. All other parameters are case-sensitive.

<itmEventMapping:agent>
itmEventMapping:agent is the root element identifying this as an event mapping definition for the monitoring agent.
<id>
Syntax:
<id>pc</id>
ID is the two character product code, such as "UX" for the UNIX OS agent. For user defined event maps, it is recommended to use "99" as the ID.
<version>
Syntax:
<version>nnnn</version>
Optional. Use this element to specify the version of the event mapping file.
<valueList>
Syntax:
<valueList name="valueListName">
Optional. Use the valueList element to define a value list of one or more value items where valueListName is the name of the list.
<valueItem>
Syntax:
<valueItem name="item_value">
This element is required when a valueList is being defined. ValueItem specifies a valid item value for the named valueList.
<event_mapping>
Syntax:
<event_mapping>
The event_mapping element encloses a group of mapping entries.
<situation>
Syntax:
<situation name="situation_name" [mapAllAttributes="Y"]
The situation element specifies a DM mapping entry whose key is situation_name. The situation_name string can contain wildcard characters (* asterisk and ? question mark) except for in the first character position.
  • mapAllAttributes="Y" instructs the EIF event forwarder to construct the EIF event slots like the generic mapping except the slots explicitly specified via the <slot> tag within this mapping entry. This attribute is useful for cases where only a few of the slots in the event must be customized (such as the msg slot). This alleviates the need to explicitly specify every slot to be included in the EIF event.
<attributeTable>
Syntax:
<attributeTable name="attribute_table_name"
 [truncated="Y"] [freeSpace="nnnn"]
  • truncated="Y" causes "ITM_Agent: Private Situation: Truncated" to be assigned to the "source" slot of the EIF event instead of "ITM Agent: Private Situation". This is an indicator that not all the attributes in the event data can fit in the EIF event due to size limitations, as defined by the event mapping generator.
  • freeSpace="nnnn" is a value determined by the event map generator as the maximum size available in the EIF event buffer after all the slots defined in this event map are built. Its value is used by the EIF event emitter to determine how much raw event data to include in the situation_eventdata slot.
<class>
Syntax:
<class name="eif_class_name" [valueList="valueList_name"]
 [defaultClass="default_eif_class_name"]>
  • name= specifies the EIF class name to be used for the generated EIF event. The eif_class_name string can contain a substitution variable (attribute name) to generate EIF class names that are dynamic depending on the value of the named attribute during run time. See Dynamic EIF classname.
  • valueList= specifies a valueList to be searched for dynamic EIF class name generation.
  • defaultClass= specifies the default EIF class name to be used for the EIF event if the eif_class_name string contains a substitution variable but the value of the attribute has no match in the specified valueList.
<slot>
Syntax:
<slot name="slot_name">
Optional. Define a slot in the EIF event. The name of the slot is the slot_name.
<mappedAttribute>
Syntax:
<mappedAttribute name="attribute_name" [multiplier="nnn"]>
Optional. Specify the value source for the slot being defined. This is the value of the attribute with the name attribute_name in the event data, if available. Otherwise, a null value is used. If the multiplier= attribute is specified and the value of the attribute is numeric, the value assigned for the slot is the attribute value multiplied by the number specified.
<mappedAttributeEnum>
Syntax:
<mappedAttributeEnum name="attribute_name">
Optional. MappedAttributeEnum is similar to the mappedAttribute tag except that if the attribute is defined as an enumeration in the attribute file, the enumerated display text is used as the slot value instead of the raw attribute value. If no enumerated display text is defined that matches the attribute value, the raw attribute value is used.
<literalString>
Syntax:
<literalString value="text">
Optional. Use the text as the value for the slot being defined. When defining a "msg" slot, you can specify variable substitution within the text (described next).

Custom msg slot

If the value of the msg slot is defined as a literal string (<literalString> element), it can include substitution variables. Substitution variables are designated by the $variable$ syntax. When formatting the msg slot, the EIF event forwarder replaces the $variable$ symbol with its replacement value.
Valid variables:
$AttrGroup.Attribute$
Attribute substitution requires a fully qualified name (i.e. both attribute group and attribute name separated by a period). The variable token will be replaced by the value of the named attribute in the event data. If the named attribute cannot be found in the event data, a null string will be used.
$AttrGroup.Attribute.TIMESTAMP$
This is the same as the $AttrGroup.Attribute$ syntax but with a .TIMESTAMP suffix qualifier. This is an indication to the EIF event forwarder that the attribute value is a time stamp (defined as a timestamp type in the attribute file) and should be formatted as a displayable timestamp format: MM/DD/YYYY HH:MM:SS. If the attribute value is not a valid timestamp, the raw attribute value will be used.
$slotname$
Event slot substitution replaces the variable token with the value of the named slot after event mapping has been performed.
The following is an example taken from a predefined event mapping file where the msg slot is customized for DM parity. 
<slot slotName="msg">
  <literalString value="Distributed Monitoring $sub_source$/$monitor$ 
  on host $hostname$ $NT_LogicalDisk.Timestamp$"/> 
</slot>
If the value for the sub_source and monitor slots have values "tmpdisk" and "Disk Read Bytes/sec", the msg slot text is similar to this example:
Distributed Monitoring tmpdisk/Disk Read Bytes/sec on host
 elaix04 08/14/2009 10:23:11

Dynamic EIF classname

The EIF event class name is defined by the name= attribute of the <class> element. The EIF class name string can contain a substitution variable for dynamic generation of the EIF class name. The substitution variable can appear anywhere within the EIF class name string, except at the beginning. The substitution variable has a syntax of $attributeGroup.attribute$. At run time, the EIF event forwarder searches the designated valueList, if one exists, for the value of the attribute specified in the substitution variable. If the attribute value is found in the valueList, the variable (and delimiting $ dollar sign) is replaced by the attribute value (after being normalized) in the EIF class name string. If no match is found in the valueList or the designated valueList is not defined, the EIF class name defined in the defaultClass= attribute is used as the EIF class name for the event. If no defaultClass= is specified, the variable in the EIF class name is replaced with a null string.

If the variable references a numeric attribute, no scaling or precision operation is performed. The string representation for the numeric field in the situation event record will be used without any adjustment. If the variable references an enumerated attribute, any text representation of the enumeration, is used as the value for the variable.

When the situation is not true (status is not "Y"), the situation status record does not contain any event attribute data. Consequently, there is no way to determine the value of any substitution variablea in the class name. The EIF event forwarder uses the defaultClass= attribute if one is specified. Otherwise, it uses the EIF event class of the EIF event last sent for the same situation name.

This is the relevant part of a sample event mapping definition uses to map a situation event "Test_Syslog" to a set of EIF events based on the value of the "Message_Number" attribute. 
<situation name="Test_Syslog">
  <class name="SAP_Syslog_$R/3_System_Log.Message_Number$"
  valueList="SyslogIDList" defaultClass="SAP_Syslog_Default" />
  :
  :
</situation>
This example has a "SyslogIDList" value list with valueItems AB0, AB1, A08, BV7, EAS, and R45 and a "Test_Syslog" situation that monitors for message IDs AB0, AB1, AB2, BV7, and BV8, The "Test_Syslog" situation evaluates to true for each of these message ids. The generated EIF events are of the following classes:
  1. AB0: SAP_Syslog_AB0 x
  2. AB1: SAP_Syslog_AB1
  3. AB2: SAP_Syslog_Default
  4. BV7: SAP_Syslog_BV7
  5. BV8: SAP_Syslog_Default
Normalizing the attribute value
A variable within the EIF event class name can reference any valid attribute in the event whose value might contain characters that are not valid for use in an EIF event class name. Before performing variable substitution in the event class name, the EIF event forwarder replaces any UTF-8 multi-byte characters and invalid characters with a single _ underscore. For example the white space characters, < > ( ) & /, are replaced by the _ underscore character.

Example

<itmEventMapping:agent
  xmlns:itmEventMapping="http://www.ibm.com/tivoli/itm/agentEventMapping"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.ibm.com/tivoli/itm/agentEventMapping 
  agentEventMap.xsd">

  <id>NT</id>
  <version>6.2.0</version>
  <event_mapping>
    <situation name="NT_LDDBPS*">
      <class name="w2k_LogDskDskBytesPerSec"/>
      <slot slotName="source">
        <literalString value="SENTRY"/>
      </slot>
      <slot slotName="probe">
        <literalString value="DskBytesPerSec"/>
      </slot>
      <slot slotName="probe_arg">
        <mappedAttribute name="NT_Logical_Disk.Disk_Name"/>
      </slot>
      <slot slotName="collection">
        <literalString value="w2k_LogicalDisk"/>
      </slot>
      <slot slotName="monitor">
        <literalString value="Disk Bytes/sec"/>
      </slot>
      <slot slotName="units">
        <literalString value="(per second)"/>
      </slot>
      <slot slotName="value">
        <mappedAttribute name="NT_Logical_Disk.Disk_Bytes/Sec"/>
      </slot>
      <slot slotName="effective_value">
        <mappedAttribute name="NT_Logical_Disk.Disk_Bytes/Sec"/>
      </slot>
      <slot slotName="msg">
        <literalString value="Distributed Monitoring $sub_source$/Disk 
        Bytes/sec on host $hostname$ $NT_Logical_Disk.Timestamp.TIMESTAMP$"/>
      </slot>
    </situation>
  </event_mapping>
</itmEventMapping:agent>
Sample EIF files are provided on the Tivoli® Monitoring Agent installation media in the PrivateConfigSamples/EIF directory.
Parent topic: EIF events
Related reference:
UTF-8 encoded XML files

Feedback