BAM Service Data Agent is used to collect statistics related to service data from WSO2 service-hosting products (such as WSO2 Application Server (AS), WSO2 Data Services Server (DSS), WSO2 ESB, WSO2 Business Process Server (BPS), WSO2 Business Rules Server (BRS)) 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 the service-publishing products and BAM server. BAM Service Data Agent can be configured early so that the statistics to be extracted from service data of the service-publishing product 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 services. The user should define the Event Stream related parameters uniquely identified by a name and a version.

Icon

The following installation instructions specifically refer to the WSO2 Application Server version 5.x.x. Similar instructions apply to any other service-hosting WSO2 server based on Carbon 4.0.x.

Installing required features

The features we install in this section come with WSO2 AS by default. You have to manually install them only if required for other servers.

1. Download the WSO2 Application Server or any other server you wish to monitor. We will assume WSO2 AS is downloaded and refer to the same as AS for the rest of the document.

2. As we are running both AS and BAM server concurrently we should change the port number of AS by applying an offset. In order to apply an offset, in the AS product directory go to $as_home/repository/conf and open file, carbon.xml. Then change the value in xpath Server/Ports/Offset from 0 to some other integer. For example,

3. To start the server,

on Linux: sh wso2server.sh

on MS Windows: wso2server.bat

4. 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.

Icon

WSO2 features are available inEquinoxP2 repository at http://dist.wso2.org/p2/carbon/releases. Repositories are listed there by WSO2 Carbon platform versions. Check the WSO2 Release Matrix, identify the WSO2 Carbon version that your product is based on and get the repository that is based on that Carbon version.

For example,

5.Then click "Add".

6.Click Installed Features. You see the BAM Service Data Agent Aggregate feature installed by default from the added P2 repository as shown below.

7. Go to <WSO2 Application Server home>/repository/conf/etc and open bam.xml file and enable ServiceDataPublishing as follows:

This is disabled by default, and BAM publishing won't occur even if you proceed with the rest of the steps if not explicitly enabled.

8. Restart the WSO2 AS server. (Go to "Shutdown/restart" sub menu of the "Main" menu in the management console).

Configuring Service Data Agent

Follow the instructions below to setup service data publishing in a running WSO2 AS Carbon instance.

Using on-premise deployment of WSO2 AS

If you are using an on-premise deployment of WSO2 AS, follow the below steps to configure the service data publishing capability, which is provided in the WSO2 feature repository:

1. Log in to the Application Server management console and select "Service Data Publishing" from the "Configure" menu.

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 . If the service statistics toolbox is installed, the version should be different to 1.0.0 since the default toolbox uses version 1.0.0 for the stream definition to enable service statistics only.

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.

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.

Using Cloud deployment of WSO2 AS

In a cloud deployment of WSO2 AS, it is not required to enable data publishing to BAM using the 'BAM Service Data Agent Aggregate' feature as explained above. Instead, you can simply add the BAM url to the <AS_HOME>/repository/conf/carbon.xml file as shown below.

Note that cloud deployment is enabled by the following setting in the <AS_HOME>/repository/conf/carbon.xml file:

Monitoring a sample Web service

Log in to the Application Server management console and select "Services -> List" in the "Main" menu.

In the "Deployed Services" window that opens, click the "TryIt" option of the "HelloService".

In the Try It UI, add a sample string as "name" and click the "Send" button.

To view data in the Cassandra database using the Cassandra Explorer, in the management console click Tools, and thenclick Connect to Cluster in the Cassandra Explorermenu.

Enter the connection details as shown below, and click Connect.

Connection Url: connection url of the Cassandra cluster with ip and port. For example, localhost:9160 if you didn't set a port offset, and 10.8.99.101:9161 if you have set a port offset of one. This field is mandatory.

Username: username of the Cassandra cluster.

Password: password of the Cassandra cluster.

Maximum Result Count: maximum results retrieved from the Cassandra cluster. The default value is 1000.

BAM data agent sends the message from the service hosting product to the column family with the given stream name in the EVENT_KSkey-space of the Cassandra database as shown below.

Analyzing service statistics

BAM service statistics data agent extracts the statistics information about the request came for a Axis2 service in WSO2 server, and publishes the statistics information to BAM. In service statistics each request will publish the event to BAM along with it's statistical data. With default configuration of BAM service statistics data agent the following measures are published. As mentioned above, BAM service statistics agent will send event for every request. Therefore the the below event meta, payload data of service statistics belongs to per service request.

Event Property Name

Type

Description

meta_content_type

Meta Data

Content type of the incoming request for the axis2 service deployed in WSO2 server (Eg: WSO2 AS)

meta_host

Meta Data

Host name of the service hosting server (Eg: WSO2 AS)

meta_referer

Meta Data

It's the HTTP header field that indicates from which the request came to the axis2 service deployed in the WSO2 server (Eg: WSO2 AS)

meta_remote_address

Meta Data

The remote address of the axis2 service deployed WSO2 server (Eg: WSO2 AS)

meta_request_url

Meta Data

Service Endpoint of the axis2 service, for which the request came.

meta_user_agent

Meta Data

It is a HTTP header field which represents the software program used by the original client. (Eg: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:11.0) Gecko/20100101 Firefox/11.0)

payload_fault_count

Payload Data

If the message has been encountered any fault when serving the request, then this will be incremented as 1. If request successfully served, this count will be 0.

payload_operation_name

Payload Data

The operation name for which the request has been made to, in the axis2 service.

payload_request_count

Payload Data

The request count will be incremented to 1, if the request has been reached the WSO2 service hosting server. (Eg: WSO2 AS)

payload_response_count

Payload Data

The response count will be incremented by 1, if the refer axis2 service request is successfully served without any error and returned the response to the client. Else it will remain 0.

payload_response_time

Payload Data

The time taken for the axis2 service to serve the request and send back a response.

payload_service_name

Payload Data

The service name for which the request came in.

payload_timestamp

Payload Data

The time of when the request came into WSO2 service hosting server (WSO2 AS), not the time which the event was received by BAM server.