Spectrum trap mapping

Document created by MichielHelder Champion on Sep 19, 2014Last modified by SamCreek on Dec 17, 2016
Version 2Show Document
  • View in full screen mode

Back to:

CA Spectrum

IM Community WIKI Front Page

 

 

Introduction

Spectrum uses a set of configuration files to determine what happens after a trap is received. This document describes what each of these files does in the chain from trap to Spectrum alarm.

 

Spectrum has an Event Configuration utility which can be used to maintain these files. This document will help to better understand the internal working of Spectrum, what the Event Configuration utility does and what the limitations of the system are. For example the Event Configuration utility will not work in an environment with a large number of custom event files. You will also need knowledge about these configuration files if you want to automate event configuration using scripts.

 

If you plan to do a lot of custom configurations, it could be useful to request a Spectrum developer ID to have your own range of event IDs. This is not required to be able to do custom configurations, but is recommended if you want to use your configurations in other environments to prevent overlap of event IDs.

 

The steps from an SNMP trap until a Spectrum alarm are:

SNMP trap --(AlertMap)--> Event --(EventDisp)--> Alarm

                      (Event Format          (Probable Cause

                          File)                  File)

      

 

Documentation

More details can be found in the Spectrum Event Configuration User Guide, available on your oneclick server here: https://<oneclick_hostname>/spectrum/docs/Spectrum_Event_Configuration_User_ENU.pdf

 

AlertMap

The AlertMap file describes the events that will follow after a trap is received and what should be done with the additional information in the trap. The AlertMap files can be found in the $SPECROOT/SS/CsVendor subdirectories on the Spectrum server. The location of the file determines for which model types the AlertMap will be used. The trap mappings which are generated using the MIB Tools utility in OneClick will be placed in $SPECROOT/custom/Events/AlertMap and will go before all the other defined trap mappings. This file is also where you should add your own custom trap mappings.

 

A trap mapping in the AlertMap file will look like this:

1.3.6.1.4.1.99.12.40.2.6.3 0x4a40036  1.3.6.1.4.1.99.12.40.1.3.1.3(1,0) \

                                      1.3.6.1.4.1.99.12.40.1.3.1.12(2,0) \

                                      1.3.6.1.6.3.18.1.3(3,0)

-------------------------- ---------  ------------------------------------

Trap OID                  Event Code OID map (additional information in the trap)

   

 

The first line starts with the Trap OID that Spectrum receives. This will be defined in the MIB for the devices that sends the trap.

 

The Event Code is the code for the event that Spectrum will generate when this trap is received. If the event code is 0, no event will be generated and the trap will be ignored. In general the first 4 number after the 0x will be the developer ID followed by a 4 digit hex event ID number. If you don't have a developer ID, the developer ID will be 0xffff for events created using the Spectrum tools. It is safe to choose something like 0xfffa for manually configured events so you have more control over the numbering sequence. Event codes do not have to be created in sequence, so you can use any non existing hexadecimal 8 number event code which is not yet in use.

 

The OID map part describes what should be done with any additional information that is sent with the trap. Each piece of information is linked to a variable in this section. Which information is sent with a trap, is defined in the MIB. Each line in the OID map consists of 3 parts: the OID, the variable ID and the instance ID. The variable ID and instance ID must be unique and spaces are not allowed in this section. If the variable ID is 0, the information will be ignored. The # and // can be used for comments on a line and the \ is used to indicate a mapping will continue on the following line.

 

EventDisp

The EventDisp file defines what Spectrum should do with the event that was generated from the trap. If Spectrum encounters an event without an entry in the EventDisp file, the event will be logged and then ignored. In the EventDisp file you can configure several aspects of an event, for example:

  • Should the event be logged
  • The event severity
  • Should the event create an alarm
  • Should the event clear an alarm
  • If an alarm is created, should it be clearable by a user
  • The severity for the created alarm
  • The description, or Probable Cause, for the created alarm
  • The event or combination of events which should generate a new event

The EventDisp files can be found in the $SPECROOT/SS/CsVendor subdirectories on the Spectrum server. The location of the file determines for which model types the EventDisp will be used. The event configurations which are generated using the MIB Tools utility in OneClick will be placed in $SPECROOT/custom/Events/EventDisp and will go before all the other defined event configurations. This file is also where you should add your own custom event configurations.

 

Each line in the EventDisp file is called an event map. Each event map can contain one or more of the actions listed before. A standard event map will look like this:

<eventcode> E <eventseverity> <actions>

   

The eventcode will be the same as defined in the AlertMap. The E is optional and determines if the event should be logged. The eventseverity is a number from 0 to 100 to indicate the severity of the event. As far as I know, this value is currently not used by Spectrum. In the actions section you define any actions that should be taken when this event is encountered. An example for event which will generate an alarm looks like this:

0xfffa0003 E 50 A 1,0xfffa0003,N

   

This event will be logged and the A indicates that an alarm will be generated. After the A you will have the alarm severity (1=minor, 2=major, 3=critical) followed by the probable cause code en the N to indicate the alarm should not be user clearable. By using event rules, it is possible to create very complex and powerful event maps. Often the same ID is used for the alarm and the event. This is only done to make it easier to link alarms to the events that generated them during trouble shooting or configuration. It is not required by the system and in some cases not even possible with more complex event and alarm configurations.

 

Below are a few examples for event maps. For a full descriptions of all possibilities in event maps, refer to the Spectrum Event Configuration User Guide.

 

Different alarms from one event code

It is possible to use a Event Discriminator to generate different alarms from one event code. This can be used for example to create unique alarms for each interface on a device. The Event Discriminator contains one or more variable IDs which can be used to uniquely identify the alarm. In the example below, a unique alarm will be created for each event with event code 0x3b10011 if the event has different values for variables 1 and 3.

0x3b1011 E 70 A 1,0x3b10011,1,3

   

 

Create an alarm that is not user clearable

By default Spectrum will create alarms which can be cleared by the user. By adding the N flag this can be prevented and the alarm can only be cleared by an event:

<eventcode> E <eventseverity> A <alarmseverity>,<alarmcause>,N

   

 

Create a new alarm each time an event is triggered

By default Spectrum will not create a new alarm if the same alarm with the same alarmcause already exists on a model. If you want to get a new alarm for each event, you can use the U flag:

<eventcode> E <eventseverity> A <alarmseverity>,<alarmcause>,U

  

 

Clearing an alarm

To clear an alarm, you can replace the A in the event map by a C:

<eventcode> C <alarmcause>,<eventdiscriminators>

  

It is also possible to clear multiple alarms with one event:

<eventcode> C <alarmcause>,<eventdiscriminators> C <alarmcause>,<eventdiscriminators> ...

  

If clearing the alarm should be logged, you should add E and an eventseverity:

<eventcode> E <eventseverity> C <alarmcause>,<eventdiscriminators>

  

In every case it is also possible to use event discriminators.

 

Using an expression to generate a new event

If an event can be generated from different causes, for example when its a generic trap, you can use an EventCondition rule with an expression to separate these causes and generate a new event for them. The event map will look like this:

<eventcode R Aprisma.EventCondition, "<expression 1>", <event if expression is 1 TRUE>, "<expression n>", <event if expression n is TRUE>, "default", <default event>

  

The syntax for the expressions can be found in the Spectrum Event Configuration User Guide. The example below will generate a new specific event depending on the value (1, 2 or something else) of variable 1 from the original event.

0xfffa0000 R Aprisma.EventCondition, "{v 1} == {I 1}", "0xfffa0001 -:-", \

                                    "{v 1} == {I 2}", "0xfffa0002 -:-", \

                                    "default", "0xfffa000a -:-"

 

The -:- indicates that all linked variables should be copied to the new event.

 

Event Format files

The Event Format files are used to specify the text that should be used when an event is displayed in Spectrum, for example in the Event Log and Alarm details. Each event has its own Event Format file. The contents of the Event Format file will determine which information is available for the user. The Event Format files can be found in $SPECROOT/SG-Support/CsEvFormat. Custom Event Format files should be placed in $SPECROOT/custom/CsEvFormat. The variables that can be used in the Event Format file can be found in the Spectrum Event Configuration User Guide. A simple example Event Format file can look like this:

{d "%w- %d %m-, %Y - %T"} - A new event (event code {e}) has been recieved for model {m} of type {t}.

 

 

The following variable data was sent with this event:

uniqueId1:            {S 1}

 

Probable Cause files

The final step in the chain is the Probable Cause file. Similar to Event Format files for events, the Probable Cause files contain the information for the alarm. Each alarm has its own Probable Cause file. The Probable Cause files can be found in $SPECROOT/SG-Support/CsPCause and the custom files should be places in $SPECROOT/custom/CsPCause.

 

A Probable Cause file only contains plain text with a fixed layout. The first line contains the alarm title/cause, usually in capitals. This is followed by three sections, each with a predefined title: SYMPTOMS:, PROBABLE CAUSES: and RECOMMENDED ACTIONS:. Each section contains the text for that title. If there are multiple symptoms, causes or actions, these are usually displayed in a numbered list. This is an example for a Probable Cause file:

TEST ALARM FOR TESTING

SYMPTOMS:

This alarm is generated to test the alarm

PROBABLE CAUSES:

1) A test event has been processed.

2) The test alarm has been created by a watch.

RECOMMENDED ACTIONS:

This alarm is for testing purposes only and should be manually cleared when it is no longer needed.

 

Activate changes

After any changes have been made to the EventDisp and/or Probable Cause files, these files should be reloaded on both the SpectroServer(s) and the OneClick server(s). Be aware that you have to take care of distributing the files to all the servers yourself, this is not part of the default setup. The SpectroServer can be updated in OneClick by selecting the VNM model, opening the SpectroSERVER Control section and clicking on Update Event Configuration.  The OneClick server can be updated by logging on to the OneClick webpage, selecting the Administration tab and opening the EvFormat/PCause Configuration section and clicking Reload.

5 people found this helpful

Attachments

    Outcomes