Ebam/Getting Started

Introduction

The eBAM (extended Business Activity Monitoring) project aims to realize an advanced platform for the monitoring of the heterogeneous services and applications (infrastructures, processes, components) and the historical analysis of data. eBAM allows users to set the governance rules of their own monitoring systems, by defining the events and services threshold included in the BAM systems, so that users can view the most relevant events on their own system at runtime.

Components

The distribution of eBAM is composed by a runtime and a designer component, the runtime is composed by OSGI plugins that implement the specific runtime features of the platform, for example:

1. Adapter Management
2. Rules and Events engines Management
3. Alarm Management

So, the componets of the runtime are responsible of the management of the eBAM information flow. The runtime is released as a server built over Equinox, that can be automatically started by the runtime.bat file. The eBAM designer is composed by eclipse plugins that run inside eclipse and activate a new Menu Item to use the wizards to configure eBAM. An Eclipse Helios distribution with eBAM designer is released. Both the runtime and the design interact with the metamodel which contains all the informations managed by ebam. In the release, the DBMS H2 is used to interact with the metamodel, through eclipse link, however is easy to modify the DBMS, as explained in the related chapter

Installation

To install Ebam you have few step to follow:

1. create the metamodel
2. install the runtime
3. install the designer

Metamodel Creation

To create the metamodel you can use several different DBMS. eBAM provides scripts for the creation and filling tables in different SQL dialect, you can find in eBAM database scripts for MySQL, Oracle and H2. All the eBAM environment is built usign H2, so if you use this DBMS you don't have to worry to change the configuration access in eBAM.

First of All

Before executing whatever script for metamodel creation, it's important to create a database called "ebam" and assign as owner a user called ebam which password is ebam

If you don't use the default DBMS (H2),you can find the database scripts that build the database for H2 and MySQL unzipping the eBAM-DataBase Scripts. Moreover you have to change the persistence file of eBAM Runtime and Designer, following the instructions exposed in the specific chapter.

If you use the default DBMS H2 you have to create the DB using as JDBC url jdbc:h2:tcp://localhost/~/ebam and username and password ebam/ebam. Using the Database script you can create and fill the database.Then shut down the DB and install the runtime. eBAM runtime will automatically open the DB and link on it.

A faster way to use eBAM with the default DBMS is to unzip the H2 DataBase Files in the home folder of your computer.In this way you the database is created, and you can proceed to the installation of the runtime.

Runtime Installation

After configuring the database, unzip the eBAM-Runtime[1] and then click on the runtime.bat file. Two command windows will open and the second you can find the log of the eclipse runtime running. The runtime will start opening automatically the H2 DataBase and parsing the log files, if present, configured in the adapter manager configuration file.

Designer Installation

Unzip the eBAM-xxx-Designer[2], then click on \eBAM-xxx-designer\eclipse\eclipse.exe. The eclipse IDE will start with the eBAM Designer in the Eclipse Menu, and if is used the default configuration of the DBMS (H2) the designer can automatically link to the database.

How eBAM works

After installed eBAM you have to configure it, as Business Activity monitor in ebam you have to define the messages type of input and how to manipulate these messages to send in output some events that are configurable too. So the step a user have to follow to configura eBAM are the following ones:

1. configuration of adapters.This operation allow eBAM to receive messages from sources
2. definition of the services and processes to monitor (using designer)
3. definition of the messages of services and process to monitor (using designer). These definition will contain the informations to save in the metamodel that will be used by eBAM engines.
4. definition of relevant data in messages (using designer), these data can be extract from Message automatically by eBAM and can be managed separately

Now eBAM is configured to receive the messages from sources, so we can define some rules for their analysis and the event generated by the rules.

Ebam can manage many types of engines (CEP Engine, Base Engine etc...).To do this, first we have to associate the message to the engine that can process it, and then we can define rules for each engine.

The way to define the rule depends on the engine you want to use, for more information you can refer to the chapter related. For each rule you can define the event to be generated. The definition of this event is stored in the metamodel and allow the system to aggregate information or generate an allarm. For each rule you can define a set of event that the rule can generate to manage the output data.

Source Adapters

eBAM is composed by a series of adapters that can retrieve messages from different sources and pass them to the Adapter Manager.

Log File Adapter

The log file Adapter is provived inside ebam and can parse a file, retrieving messages from it, and send them to the Adapter Manager. The log adapter optionally is able to restart reading the log from the message in which it previously stopped to read. To configured this adapter, take the eBAM runtime and go to subfolder plugins. With a tool that manage .jar archive, open the plugin org.eclipse.ebam.adapter_x.x.x.jar. Open the file /conf/configuration.xml. In this file you can configure the behaviour of the Log Adapter. Here there is a part of the text of the configuration.xml which shows the configuration of the log Adapter:

<adapter id="TEST_SERVICE">

<property name="factory" value="org.eclipse.ebam.adapters.log.LogAdapter"/>
<property name="source" value="C:/temp/logAllarme.log"/>
<property name="key" value="FALSE"/>
<property name="append" value="FALSE"/>
<property name="modality" value="RECOVERY"/>

</adapter>

• The property "factory" has the name of the class that implement the Adapter.
• The property "source" has the path in which the adapter searchs for lof files. In this example, the adapter will search in C:/temp/ all the .log files that begin with logAllarme.
• The property "key" if set to true, make the log adapter serach for a standard key value, that is a sequence of numbers in this way: KEY=XXXXXXXX; and memorize it. It is useful in tha case that the adapter has to be stopped withouth reading all the messages that are on the log files, in fact it makes the adapter start for the messages it didn't read yet before it stopped.
• The property append if set to true, makes the adapter ignore messages already present in logs when it starts, and parses the first message that arrives after its starting.
• The property modality if present, makes the adapter able to restart reading the log from the message in which it previously stopped to read. The RECOVERY modality allow to catch up all the messages not read yet because of a unplanned stop of the server. To enable this property is necessary that the property key is set true, because Ebam can retrieve information about the messages read through the key field. If the recovery is enabled, at the startup, eBAM retrieve the last key ofmessage read and search this key in the input source of messages. After found it, it start to read from the next message and forward. If the key isn't found in the source, eBAM read all the messages that are on the source

Engines

Ebam has designed to have different engines that analyse messages to extract complex events. At this moment Ebam provide one base engine that can execute two main rules

• count of messages that has a defined pattern, and when the number of these events reaches a predefined threshold, if configured, an alarm will be generated.
• identification of a pattern in a message, and possibility of associate an event and an alarm

For the Base Engine, the rule of behaviour has to be defined through some informations defined in xml language, and in the metamodel it has stored in the field EXPRESSION inside the tasble EBAM_RUE (see the chapter about [ Adding a new rule]) using designer tool. Here is an example of an xml expression for the rule of the Base Engine

<ebam_rule> <class>org.eclipse.ebam.customengine.rules.genericRules.CounterRule</class> <FILTER>//*/DTL/ERRORE</FILTER> </ebam_rule>

The CLASS tag identify the java class in which the rule is implemented and it can be:

• org.eclipse.ebam.customengine.rules.genericRules.CounterRule
• org.eclipse.ebam.customengine.rules.genericRules.FilterRule

The first class implement the rule of counting the messages that have a specific pattern, defined in the FILTER tag. The second class implement the rule of identifying a message recognizing the pattern defined in the FILTER tag.</p>

For the CEP Engine (soon released),it will be an osgi bundle and we have to put the bundle inside the runtime, so to use in the eBAM runtime you have to put the plugin of the engine inside the subfolder /plugins and insert the name of the jar containing the cep engine in the file eBAM-0.7RC-runtime\configuration\org.eclipse.equinox.simpleconfigurator\bundles.info in this way <p>NAME_OF_ENGINE,1.0.0,plugins/NAME_OF_ENGINE_1.0.0.jar,4,true