CJ Goldsmith
May 28 2010, 12:56 PM
Introduction:
Having received a request recently to have Traverse generate a "Device Down" event within the event console. I recognized that this may serve as a good, brief example of how to setup event processing rules within Traverse.
A more in depth explanation of all elements can be found in our developer's guide under section 4.5 "Extending the Message Handler".
In this particular example we are going to invoke the log file monitoring capability of Traverse. We are going to point the log file monitor back at the log files generated by the Traverse application itself to look for entries of a specific type. Transform those entries into a human readable message and then post that message within the Traverse application.
Message processing rules are xml configuration files which can be housed in 1 of 2 locations within a Traverse install. Rules which are provided as part of a standard Traverse install are located in:
[Traverse Home]/etc/messages/
while custom rules are housed in:
[Traverse Home]/plugin/messages/
I am going to be displaying what a monitor configuration would look like which reads the Traverse log file for new entries showing the status change of a packet loss test showing a result value of 100%. Searching for the monitor file for
There are 2 parts to message configuring message processing within Traverse. A source definition and a rule definition.
An example of a complete source configuration file:
<message-handler>
<source type="file" name="traverselog">
<enabled>true</enabled>
<duplicateEventInterval>1800</duplicateEventInterval>
<logunmatched>true</logunmatched>
<input>/usr/local/traverse/logs/monitor.log</input>
</source>
</message-handler>
An example of a complete rule configuration file:
<NetVigil>
<message-handler>
<ruleset type="file" name="traverselog">
<rule>
<description>Traverse Log Monitor, Device Down</description>
<pattern>deviceName=([^;]+).+testName=Packet Loss;.+testResult=100</pattern>
<action>accept</action>
<mapping>
<field name="device_name" match="1"/>
</mapping>
<severity>critical</severity>
<show-message>true</show-message>
<auto-clear>1800</auto-clear>
<transform>${device_name} Device In Down State</transform>
</rule>
<rule>
<description>Traverse Log Monitor, Device Down</description>
<pattern>deviceName=([^;]+).+testName=Packet Loss;.+testResult=0</pattern>
<action>accept</action>
<mapping>
<field name="device_name" match="1"/>
</mapping>
<severity>ok</severity>
<show-message>true</show-message>
<auto-clear>600</auto-clear>
<transform>${device_name} Device Returned From Down State</transform>
</rule>
</ruleset>
</message-handler>
</NetVigil>
Explanation of the source configuration file:
Every event type must have a source definition which defines where these events will be originating from. To get off of the ground you will need to inspect 2 of these elements:
<source />- You will need to define the type attribute as type 'file'. This tells Traverse that it is looking at a log file monitor source definition. The name attribute will need to be given a unique identifying name of your choice.
<input />- You will need to define the location of the log file to be monitor. Keep in mind that I am showing an example from a Linux installation. Windows file names will need to be defined with a drive letter (ie C:\Program Files\Traverse\logs\monitor.log).
* It is important to remember that all source files must be written to the file system with a name starting with 00_src_file, any naming convention outside of this may not be interpreted correctly by Traverse.
Explanation of the rule configuration file:
When monitoring the contents of a log file, it is often unwanted to receive notification for every log entry made. Defining rules allows you to specify which lines Traverse should process as well as how that information should be presented within the application.
Again, it should be noted that a more in depth explanation of extending message handling can be found in our developer's guide. Elements that I would like to draw your attention to:
<ruleset />- a ruleset element is used to bundle related rules. In this case we are defining OK and Critical level rules within the same ruleset. This allows Traverse to match these rules so that if a device goes down an event will be generated with a status of Critical. If the OK status rule is matched at a later point the event console will be able to match these 2 rules as related and collapse them into the OK status event (here with the message that the device has returned from the 'down' state). The ruleset element requires a type and name attribute be defined which should match those defined in your source definition. If you would like to create a generic ruleset which applies to all source configurations of type 'file' you can set the name attribute to a value of '*'.
<rule />- defines a unique rule as part of a ruleset.
<pattern />- this is the meat and potatoes of the configuration file. You are using a perl regular expression to match new entries found within the target log file. If the log entry matches this pattern it will be further processed by this rule. If not it will be further processed, if no rules match it will be discarded.
<action />- if the pattern element has been matched do we process within this rule or explicitly discard the message?
<mapping />- this element contains a number of field definitions. Pay attention here to how the pattern element and the mapping element are working together. If you look at the regular expression provided in the pattern element you can see a grouping "([^;]+)". Note that this is the position 1 grouping within the pattern (not position zero for you developers, sorry). Note that I have defined a field element which is using match=1, this is essentially placing the text matching this grouping within a variable named "device_name" ( * device_name is also a special variable which is used by Traverse to identify which configured device is affected by the incoming event ).
<transform />- this is where you are creating the message which will show up in the event console. Note here that we are accessing the device_name variable which was defined in our field element to create the end message presented on the event console.
Wrap Up:
Looking at the information being processed you can see that Traverse will now generate a new event within the event console with the following text once log message has been written to the monitor.log file indicating that a packet loss test has returned a value of 100 ( 100% packet loss ), reading "Test Device Device In Down State". This event will be a Critical level event. Once a log message is written indicating that the same device has a packet loss test with a value of 0 ( 0% packet loss ) Traverse will then generate an event with text reading "Test Device Device Returned From Down State". This event will be an OK level event.
(Attaching both configuration files used, archived to be inflated from the Traverse install directory).
Having received a request recently to have Traverse generate a "Device Down" event within the event console. I recognized that this may serve as a good, brief example of how to setup event processing rules within Traverse.
A more in depth explanation of all elements can be found in our developer's guide under section 4.5 "Extending the Message Handler".
In this particular example we are going to invoke the log file monitoring capability of Traverse. We are going to point the log file monitor back at the log files generated by the Traverse application itself to look for entries of a specific type. Transform those entries into a human readable message and then post that message within the Traverse application.
Message processing rules are xml configuration files which can be housed in 1 of 2 locations within a Traverse install. Rules which are provided as part of a standard Traverse install are located in:
[Traverse Home]/etc/messages/
while custom rules are housed in:
[Traverse Home]/plugin/messages/
I am going to be displaying what a monitor configuration would look like which reads the Traverse log file for new entries showing the status change of a packet loss test showing a result value of 100%. Searching for the monitor file for
There are 2 parts to message configuring message processing within Traverse. A source definition and a rule definition.
An example of a complete source configuration file:
<message-handler>
<source type="file" name="traverselog">
<enabled>true</enabled>
<duplicateEventInterval>1800</duplicateEventInterval>
<logunmatched>true</logunmatched>
<input>/usr/local/traverse/logs/monitor.log</input>
</source>
</message-handler>
An example of a complete rule configuration file:
<NetVigil>
<message-handler>
<ruleset type="file" name="traverselog">
<rule>
<description>Traverse Log Monitor, Device Down</description>
<pattern>deviceName=([^;]+).+testName=Packet Loss;.+testResult=100</pattern>
<action>accept</action>
<mapping>
<field name="device_name" match="1"/>
</mapping>
<severity>critical</severity>
<show-message>true</show-message>
<auto-clear>1800</auto-clear>
<transform>${device_name} Device In Down State</transform>
</rule>
<rule>
<description>Traverse Log Monitor, Device Down</description>
<pattern>deviceName=([^;]+).+testName=Packet Loss;.+testResult=0</pattern>
<action>accept</action>
<mapping>
<field name="device_name" match="1"/>
</mapping>
<severity>ok</severity>
<show-message>true</show-message>
<auto-clear>600</auto-clear>
<transform>${device_name} Device Returned From Down State</transform>
</rule>
</ruleset>
</message-handler>
</NetVigil>
Explanation of the source configuration file:
Every event type must have a source definition which defines where these events will be originating from. To get off of the ground you will need to inspect 2 of these elements:
<source />- You will need to define the type attribute as type 'file'. This tells Traverse that it is looking at a log file monitor source definition. The name attribute will need to be given a unique identifying name of your choice.
<input />- You will need to define the location of the log file to be monitor. Keep in mind that I am showing an example from a Linux installation. Windows file names will need to be defined with a drive letter (ie C:\Program Files\Traverse\logs\monitor.log).
* It is important to remember that all source files must be written to the file system with a name starting with 00_src_file, any naming convention outside of this may not be interpreted correctly by Traverse.
Explanation of the rule configuration file:
When monitoring the contents of a log file, it is often unwanted to receive notification for every log entry made. Defining rules allows you to specify which lines Traverse should process as well as how that information should be presented within the application.
Again, it should be noted that a more in depth explanation of extending message handling can be found in our developer's guide. Elements that I would like to draw your attention to:
<ruleset />- a ruleset element is used to bundle related rules. In this case we are defining OK and Critical level rules within the same ruleset. This allows Traverse to match these rules so that if a device goes down an event will be generated with a status of Critical. If the OK status rule is matched at a later point the event console will be able to match these 2 rules as related and collapse them into the OK status event (here with the message that the device has returned from the 'down' state). The ruleset element requires a type and name attribute be defined which should match those defined in your source definition. If you would like to create a generic ruleset which applies to all source configurations of type 'file' you can set the name attribute to a value of '*'.
<rule />- defines a unique rule as part of a ruleset.
<pattern />- this is the meat and potatoes of the configuration file. You are using a perl regular expression to match new entries found within the target log file. If the log entry matches this pattern it will be further processed by this rule. If not it will be further processed, if no rules match it will be discarded.
<action />- if the pattern element has been matched do we process within this rule or explicitly discard the message?
<mapping />- this element contains a number of field definitions. Pay attention here to how the pattern element and the mapping element are working together. If you look at the regular expression provided in the pattern element you can see a grouping "([^;]+)". Note that this is the position 1 grouping within the pattern (not position zero for you developers, sorry). Note that I have defined a field element which is using match=1, this is essentially placing the text matching this grouping within a variable named "device_name" ( * device_name is also a special variable which is used by Traverse to identify which configured device is affected by the incoming event ).
<transform />- this is where you are creating the message which will show up in the event console. Note here that we are accessing the device_name variable which was defined in our field element to create the end message presented on the event console.
Wrap Up:
Looking at the information being processed you can see that Traverse will now generate a new event within the event console with the following text once log message has been written to the monitor.log file indicating that a packet loss test has returned a value of 100 ( 100% packet loss ), reading "Test Device Device In Down State". This event will be a Critical level event. Once a log message is written indicating that the same device has a packet loss test with a value of 0 ( 0% packet loss ) Traverse will then generate an event with text reading "Test Device Device Returned From Down State". This event will be an OK level event.
(Attaching both configuration files used, archived to be inflated from the Traverse install directory).