BAM Mediation Data Agent is used to collect statistics related to mediation data from the WSO2 ESB and send to the WSO2 BAM server. BAM server receives data events via its Thrift API. This protocol uses a binary protocol and enables fast data transmission between ESB and BAM server. BAM Mediation Data Agent can be configured early so that the statistics to be extracted from mediation data of ESB can be pre-defined. In the configuration panel the user can specify the BAM server (Thrift server) related information and Properties to be extracted from the Configuration Context of ESB. The user should define the Event Stream related parameters uniquely identified by a name and a version.
The following sections are covered:
Installing BAM Mediation Data Agent Feature
The following installation instructions apply to WSO2 ESB version 4.5.x.
1. Download WSO2 ESB from url: http://wso2.com/products/enterprise-service-bus.
2. When running both ESB and BAM servers concurrently, change the port number of one server by applying an offset in file <esb_home>/repository/conf/carbon.xml. To apply an offset, change the value in xpath Server/Ports/Offset from 0 to some other integer. For example,
<!-- Ports offset. This entry will set the value of the ports defined below to the define value + Offset. e.g. Offset=2 and HTTPS port=9443 will set the effective HTTPS port to 9445 --> <Offset>2</Offset>
3. Start the ESB server by executing the following files in <esb_home>/bin.
- on Linux wso2server.sh
- on MS Windows wso2server.bat
4. After starting the server, go to ESB management console. Instructions are similar to those in section Running the Product.
5. In the management console, select "Configure -> Features" and click the "Repository Management" tab. Then select a P2 repository either from a URL or a file. For instructions, refer to section Managing the Feature Repository.
For example,
Then click Add.
6. Go to "Available Features" tab and select the repository added above. The, click on "Find Features" button. From the list of features that appears, select "BAM Service Data Agent Aggregate" feature and click "Install."
7. Click "Next" once done and accept the license agreement.
8. Restart the WSO2 ESB server.
Using Mediation Data Agent
Here describes with a sample how to use the Mediation Data Agent to log mediation statistics data into a Cassandra Database. There are four basic steps involved.
- Configuring Mediation Data Agent
- Set the Backend Server for ESB Endpoint
- Add a Proxy Service to WSO2 ESB
- Send Messages To the ESB
Configuring Mediation Data Agent
1. Navigate to the <ESB_Home>/repository/conf directory and edit carbon.xml to enable statistics.
<StatisticsReporterDisabled>false</StatisticsReporterDisabled>
2. Log in to the ESB management console and select "Mediation Data Publishing" in "Configure" menu.
3. The "Mediation Data Publisher Configuration" window opens. Fill in the field accordingly. For example,
Enable Mediation Stats: Select this option to enable the agent.
Enable Activity Service: This enables message tracing with BAM. Typically, a request is sent to an endpoint after being passed through some intermediate stages. Messaging tracing enables to track each messages and visualize the message body in each of these intermediate stages.
Note
Enable Activity Service feature will be implemented from the next release of BAM.
Stream Definition Configuration:
- Stream Name : Stream Name can be any string with alpha-numeric characters
- Version : Stream Version distinguishes different streams with the same Stream Name. Default version should be 1.0.0 .
- Nick Name : This is a user preferred nick name to the Stream Name in alpha-numeric characters
- Description : A description describing about the particular stream defined by Stream Name, Stream Version pair. Description should also consists of alpha-numeric characters.
BAM Credentials:
- BAM URL : Enter the IP address of the BAM server. And the port should be the thrift port ( ex: tcp://127.0.0.1:7611 ). You can add a comma-separated list of server URLs to ensure that load is distributed among many servers and to minimize effects of a failure of one server node. This load balancing feature is an enhancement of the BAM 2.0.1 release onwards.
- Username: Put the BAM Thrift log-in user name. Default value is admin.
- Password: Put the BAM Thrift log-in password. Default value is admin.
Properties: A BAM deployment can receive events from different data agents. In order to uniquely identify events triggering from one agent, a property can be associated it. This feature is particularly useful in clustered environment.
Click the "Update" button once done .
Setting the Backend Server for ESB Endpoint
In order to test the functionality of the BAM Mediation Data Agent, user can define a sample WSDL Proxy Service. Before creating that service, the user needs to create an Endpoint service as the WSDL Proxy Service. Steps to create an Endpoint service are as follows:
1. Navigate to <esb_home>/samples/axis2Server/src/SimpleStockQuoteService and build the backend service with Apache Ant. (Apache Ant should be installed. For instruction to install Ant, refer to Installation Prerequisites).
2. Go to <esb_home/samples/axis2Server and run the Axis2 server.
- In Linux, axis2server.sh
- In Windows, axis2server.bat
3. Test whether the proxy service WSDL exists in http://localhost:9000/services/SimpleStockQuoteService?wsdl
Adding a proxy service to WSO2 ESB
These are the steps to create a sample WSDL Proxy Service to test the BAM Mediation Data Agent.
1. Log in to ESB management console and select "Add -> Proxy Service" from the "Main" menu.
2. The "Create Proxy Service from Template" window opens. Click on "WSDL Based Proxy" link to create a new WSDL-based proxy.
3. The "WSDL Based Proxy" window opens. Fill the form with correct information. For example,
Fields marked with * are mandatory.
- Proxy Service Name: Mandatory field. eg: Simple_Stock_Quote_Service_Proxy.
- WSDL URI: http://localhost:9000/services/SimpleStockQuoteService?wsdl
- WSDL Service: SimpleStockQuoteService
- WSDL Port: SimpleStockQuoteServiceHttpSoap11Endpoint
4. Click "Create" button once the details are entered.
5. The "Deployed Services" window opens. Select the newly-created proxy (Simple_Stock_Quote_Service_Proxy in this example) to access its service dashboard.
6. Click the link "Enable Statistics" link in category, "Specific Configuration".
Send Messages to the ESB
At this stage, all steps mentioned above should be completed in order to test the BAM Mediation Data Agent. In this last step, the user can send custom messages through the previously-created WSDL Proxy Service and test whether they are correctly stored in the Cassandra database. This is only an example, but the steps to use the BAM Mediation Data Agent in a production environment are similar.
1. Downloaded and start WSO2 BAM. Before starting the server, change its port offset to a different value in <BAM_home>\repository\conf\Carbon.xml file. For example,
<!-- Ports offset. This entry will set the value of the ports defined below to the define value + Offset. e.g. Offset=2 and HTTPS port=9443 will set the effective HTTPS port to 9445--> <Offset>2</Offset>
This is required to start two Carbon instances concurrently.
2. Navigate to <ESB_home>/samples/axis2Client.
3. Build the backend service with Apache Ant (You need to install Apache Ant before that.) with the following code.
ant stockquote -Daddurl=https://localhost:8244/services/Simple_Stock_Quote_Service_Proxy -Dmode=fullquote -Dsymbol=testString
addurl value should be given from the https endpoint located in Simple_Stock_Quote_Service_Proxy's service dashboard. To access its dashboard, log in to ESB's management console and access menu "Main -> Services -> List". Then, click on the "Simple_Stock_Quote_Service_Proxy" service listed on the "Deployed Services" page. Any preferred string can be used instead of the testString for symbol )
Once done, the BAM Mediation Data Agent in the Simple_Stock_Quote_Service_Proxy service should have dumped statistics from the ESB to the column family with the given "Stream Name" in key-space, "EVENT_KS" in the Cassandra database. Data in the Cassandra database can be seen from the Cassandra Explorer in the BAM server as follow:
What does Mediation Statistics Tell?
BAM mediation statistics metrics are same as the metrics used by General ESB mediation statistics component. Mediation statistics are widely-used monitoring features. From functional components of the ESB, sequences, proxy services and endpoints directly get involved in processing messages. The BAM Mediation Statistics feature enables a server administrator/Tenant administrator to collect runtime statistical information on these three types of functional components and view them through via interactive BAM Dashboard. This feature provides a simple but effective way of determining the runtime performance of the ESB. The collected statistical data can be used to analyze network traffic patterns and draw rough estimates on how the service bus will be used in the future. Perhaps the most enticing attribute of the mediation statistics feature is that it can be configured in a fine grained manner. In other words, it allows a user to collect data on only a specified set of sequences, proxy services and endpoints.
All statistics information collected by the mediation component is aggregated for time duration and published to BAM as an event. That means, mediation statistics events are not sent for every request, rather it aggregates request measures for some time and sends a event for BAM. You can find more detailed information form about the measures of mediation statistics in this OT article.