Hello World – Getting Started!

Get started with simple text logs and syslog events. Read and count events, change messages, and create new notification events. This is the first example you should try.

Download example - Already included in recent ORION packages

“Hello World” let’s you process your own events immediately while getting acquainted with basic tasks, such as saving ECAs (Event Correlation Applications), restarting the server, using the Event Viewer, and very common filters and parameters, such as the Edit Field Filter and the Count Unique Events Filter, and the frequently used Condition, Action List, Expression, and Time Interval parameters.

This example assumes that you have:

• Successfully downloaded and installed ORION on either your Windows or Linux System.

• Have at least skimmed the tutorial so you have an idea that ORION works on events which have fields, and that these events flow in streams through Filter Stacks where they are processed. Also, events come into ORION through Sources (inbound protocols) and leave ORION through Destinations (outbound protocols).

• Started the ORION Manager from a desktop icon, the Start Menu→All Programs→EventGnosis ORION, or you have entered http://localhost:9090 into your browser (IE6 or above) – The server may take a minute or two to come up after installation.

• Automatically received your trial license, because your ORION host is connected to the internet.

• Clicked on the Event Viewer and there are some (not necessarily meaningful) events displayed in your DefaultArchive.

You should see the Getting Started screen in front of you:

In this example, you will be using the following modules in the ORION Manager:

• ECA Editor: where applications are created and changed, and the ORION server is controlled.

• Event Viewer: where you can see the event streams written into standard ORION event archives.

In the “Getting Started” screen click the ECA Editor button. On the left-hand side you will see the Component Tree with your hostname on top followed by the ORION server name “ecs0”, and the initial application “EcaDefault”.

Right-click on “EcaDefault”, select “Delete” and confirm. Don’t worry – this just un-registers the application from the ORION server. You can get it back at any time.

Next select “HelloWorld.xml” in the “Insert ECA into ECS” pull down box and hit “OK” and confirm. You can get to this screen at any time clicking on “ecs0”.

Note: “ECS” stands for Event Correlation Server or ORION server, and ECA stands for Event Correlation Application or ORION application.

Next right-click on “Hello World” and select “Expand Tree”, and then click on “Sources” and you should see the list of input Sources currently configured for “Hello World”:

• Text Log Receiver that reads new lines appended to the “HelloWorld.txt” file which is in the EV_HOME directory. It creates a new event for each new line it reads from the text file, and sends the event into the “HelloWorld-Stack”. The bold blue words are parameters that can be clicked on and changed.
  
  Note: The FileName starts with EV_HOME which is a special token always referring to the installation directory. You can put any absolute file path in here, but don’t change it, yet.

• Syslog Receiver that receives all Syslog messages sent to the host (on the default UDP port 514) and it also forwards them to the “HelloWorld-Stack”.

Even though we have inserted the “Hello World” application into the ECA Editor, it is not yet running on the ORION Server. Before it becomes active, the ORION Server needs to be restarted by clicking on your hostname, hitting “OK” next to “ecs0”, and confirming. It will take a few seconds to restart the server, and its initialization status is shown in the lower left-hand status window. Make sure that the ORION server is fully up, before you start sending events to it.

Click on the Event Viewer button. It should open another window that looks like this:

As long as the pull down menu says: “Auto Show Latest – 5 secs”, the Event Viewer will automatically update and show any new events as they arrive.

Now it is time to process a live event. Open the file EV_HOME/HelloWorld.txt in a plain old text editor, such as Notepad (not Wordpad or Word). Go to the END of the file, enter or copy a line with “Hello World”, and save the file.

If everything was set-up correctly you should see the following event in your Event Viewer:

Congratulations! - You have just processed your first event!

The “Hello World” line you added to the “HelloWorld.txt” file was detected and read by the Text Log Receiver. The Text Log Receiver forwarded the event to the Filter Stack named “HelloWorld-Stack” for processing.

Filter Stacks are made up of individual Filters. An event “flows” in the order that it is received into the top of the Filter Stack. There it is processed by the first filter, then sent to the second filter, the third, and so on. After an event has been processed by the last filter in the stack, the event is sent to the next Filter Stack or the Destination specified as Standard Output for the Filter Stack.

What about Routing? Before you ask - Yes, events can take different paths through the system. You can have many different Filter Stacks be fed events by many different Sources and forwarding events to many different Destinations. You can conditionally route individual events to specific stacks for processing (Route Event Filter), or make a copy of an event for special processing in parallel (Copy Event Filter) by other stacks. You can even direct events to different applications (ECA Event Sender and ECA Event Receiver) or to entirely different ORION Servers (ECS TCP Event Sender and ECS TCP Event Receiver).

In our “HelloWorld-Stack”, our event is first processed by the Comment Filter, which does nothing to the event and passes it right on to the Edit Field Filter.

As you can see, all Filters are defined as “English Language Building Blocks” with configurable parameters shown in bold. You can click on the bold parameters to change them.

The Edit Field Filter only looks at events that meet the Condition where the message field contains the words “Hello World” somewhere regardless of upper or lower case spelling. If “Hello World” is not in the message, the event is passed through to the next filter without any further processing.

However, if “Hello World” is in the message field, then this filter will put a new value into the field “ev:msg” (which is just another way of saying the message field), and this value is the result of the Expression. In this case, the Expression simply adds the string “- It's good to be here!” to the end of the original “Hello World” line entered into the text file.

The Count Unique Events Filter only processes events that do NOT contain the “Hello World” string, such as “ERROR 1”. If it receives the same message (ev:msg) three times within one minute, it will generate a new notification event as configured in the Action List.

Try adding the message “ERROR 1” three times to the “HelloWorld.txt” file within 60 seconds, and see what you get.

As you can see, you have all three “ERROR 1” messages followed by a generated notification message saying “Received 3 messages in 1 minute with: ERROR 1”.

As the final step, all events are forwarded by the Filter Stack to the “Archive-Destination”, which writes them into the ORION archive named “defaultArchive”, where they can be read and displayed in the Event Viewer.

• Forward live syslog messages from your favorite firewall, router, or Linux host to your ORION server. Make sure that no other syslog server is running on our ORION host (on the normal UDP 514 port). If you are running multiple syslog servers, only one will be successful binding the port and the other one will not receive messages.

• Experiment with different Conditions, Expressions, and notifications in Action Lists and send different events by text log or syslog.

• Experiment with different Thresholds and Time Intervals.

• Add other Sources, Filters, and Destinations (system objects) by clicking the “New” button in their respective screens. You will be able to choose the type from a pull-down list, and you will see the description for that system object. Right-click on them in the tree to move them up or down, delete, or disable them.

• Try the Discard Event Filter to selectively remove events from the stream, or try the Discard Redundant Events Filter to remove all duplicate events from an event stream, by specifying the ev:msg field to indicate unique new events.

Reminder: Don’t forget to press “Save ECA” after each edit, and restart ORION to apply the changes.

Follow the standard installation procedure for examples.

• ECA Editor Operations: Edit, Save, Restart Server, and Adding, Deleting, Moving Filters
• Event Viewer: Displaying event streams
• Reading Textlogs and Syslog Events
• Changing certain events based on Conditions
• Creating new (notification) events in Actions Lists
• Editing Expressions to set new values in event fields
• Counting unique events with time windows

• EV_HOME/config/HelloWorld.xml - Reads text logs and syslog, processes events, and writes to the Event Viewer.
• EV_HOME/HelloWorld.txt - Input text file with sample lines.

TextLog Receiver, SysLog Receiver

Archive Writer

COMPLEXITY: BASIC

ORION VERSION: 6.0

KEY WORDS: SYSLOG, TEXTLOG, Expression, Condition, TimeInterval, Threshold, Comment Filter, ActionList, ev:msg, Event Viewer, Save ECA, Restart Server, SysLog Receiver, Text Log Receiver, Archive Writer.