This section explains how to set up WSO2 Business Activity Monitor (BAM) to collect and analyze runtime statistics from the WSO2 API Manager. To publish data from the API Manager to BAM, the Thrift protocol is used. Information processed in BAM is stored in a database from which the API Publisher retrieves information before displaying in the corresponding UI screens.
Follow the instructions below to set up WSO2 BAM and the API Manager.
Ensure that you have the following in your environment,
- JDK 1.6.* or 1.7
- Cygwin ( http://www.cygwin.com ) : Required only if you use Windows. WSO2 BAM analytics framework depends on Apache Hadoop, which requires Cygwin in order to run on Windows. Install at least the basic net (OpenSSH,tcp_wrapper packages) and security related Cygwin packages. After Cygwin installation, update the PATH variable with
C:/cygwin/binand restart BAM.
Configuring WSO2 API Manager
Enable API tracking option by setting the <
APIUsageTracking>element to true in
<APIM_HOME>/repository/conf/api-manager.xml.Also specify the data source used for getting BAM statistics in
<DataSourceName>element. For example,
Specify the data source definition in
<APIM_HOME>/repository/conf/datasources/master-datasources.xmlfile as follows.
WSO2AM_STATS_DBis the datasource used to fetch analytical data. Note that the JNDI config names must match the ones defined earlier in BAM.
In the above configuration,
- Replace <BAM_HOME> with the absolute path of BAM installation directory.
- The JNDI config name must match with configurations of api-manager.xml file defined later in this guide.
Next, prepare BAM to collect and analyze statistics from API manager.
Configuring WSO2 BAM
- Download WSO2 BAM 2.3.0 or later from location: http://wso2.com/products/business-activity-monitor.
Change port offset of BAM to 1 by editing the file
<BAM_HOME>/repository/conf/carbon.xmlfile (search for the offset node).
This increments all ports used by the server by 1, which means the BAM server will run on port 9444. Port offset is used to increment the default port by a given value. It avoids possible port conflicts when multiple WSO2 products are run in same host.
- Copy the file
<BAM_HOME>/repository/deployment/server/bam-toolbox. If you use Oracle DB to store statistical data, copy
If this folder is not in the BAM installation home by default, create it and copy the file.
The API Manager analytic toolbox
A toolbox is an installable archive, with a .tbox extension. It contains necessary artifacts that models a complete usecase, from collecting data, analyzing through defined Hive scripts to summarizing data through gadgets, Jaggery scripts and other dashboard components.
- Configure a database to which BAM can write analyzed information to. This information is retrieved by the API Publisher before displaying on the corresponding statistical dashboards.
Specify the data source definition in
<BAM_HOME>/repository/conf/datasources/master-datasources.xmlfile as follows.
WSO2AM_STATS_DBis the datasource used to fetch analytical data. This example uses an H2 database. If you want to use a different database, see Changing the statistics database.
Because you changed the default BAM port in step 2 above, you must change the Cassandra port given in JDBC connection url in the following datasource configuration found in master-datasources.xml file. Since the port offset is 1, the Cassandra port must be 9161.
If you change the default BAM port (with a port offset), you must change the Cassandra port accordingly, before running the Hive scripts. If not, you get an unable to connect to server Cassandra exception. To overcome this, change the default Cassandra port with the offset value (default port+offset) in
<BAM_HOME>/repository/conf/datasources/master- datasources.xmlfile, add the following line at the beginning of the Hive script and rerun.
drop table <hive_cassandra_table_name>;
Restart BAM server by running
If you want to host the BAM server on a different machine or change the running port, you must edit the
<APIM_HOME>/repository/conf/api-manager.xmlfile as follows:
Changing the statistics database
To use a different database than the default H2 for statistical publishing, you must change the properties of the datasource element, and additionally delete some metadata tables created by previous executions of the Hive script, if there are any.
To delete the metadata tables,
- Log in to BAM management console and select Add in Analytics menu.
- Go to the Script Editor in the window that opens.
Execute the following script.