In this section, we explain how to set up WSO2 Business Activity Monitor (version 2.5.0 is used here) to collect and analyze runtime statistics from the 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 it in the corresponding UI screens.
org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataPublisher is configured to push data events to WSO2 BAM. If you use a product other than WSO2 BAM to collect and analyze runtime statistics, you write a new data publishing agent by extending
APIMgtUsageDataPublisher. Find the API templates inside
<APIM_HOME>/repository/resources/api_templates. When writing a new data publishing agent, make sure the data publishing logic has a minimal impact to API invocation.
Tip: The datasource and database names used here are just examples. They may vary depending on your configurations.
JDK 1.6.* or 1.7
If you install JDK in the
Filesfolder in Windows, avoid the space by using PROGRA~1 in the
PATHenvironment variables. Else, the server throws an exception.
- net (OpenSSH,tcp_wrapper packages) and security related Cygwin packages. After Cygwin installation, update the PATH variable with
C:/cygwin/binand restart BAM.BAM analytics framework depends on Apache Hadoop, which requires Cygwin in order to run on Windows. Install at least the basic
Next prepare BAM to collect and analyze statistics from the API Manager.
Configure WSO2 BAM
- Download WSO2 BAM 2.5.0 from location: http://wso2.com/products/business-activity-monitor.
Apply an offset of 3 to the default BAM port by editing the
This increments all ports used by the server by 3, which means the BAM server will run on port 9446. Port offset is used to increment the default port by a given value. It avoids possible port conflicts when multiple WSO2 products run on same host.
Install MySQL server and a suitable client like the MySQL Workbench. You can get the instructions manual from http://dev.mysql.com/doc/.
Go to the command-line and issue the following commands to connect to the MySQL server and create a database (e.g.,
TestStatsDB). This database is used to save the statistical data collected by the BAM. You do not need to create any tables in it.
Save the MySQL connector JAR inside both
Give the datasource definition under the
<datasource>element in the
<BAM_HOME>/repository/conf/datasources/master-datasources.xmlfile. The tables are created automatically when the Hive script runs. You just need to create the schema.
WSO2AM_STATS_DBis used to fetch analytical data from the database. The example below connects to a MySQL instance:
Tip: If you are using BAM 2.4.1, be sure to uncomment the
<thriftDataReceiver><hostName>element in the
<BAM_HOME>/repository/conf/data-bridge/data-bridge-config.xmlfile and give the BAM host IP there.
Restart BAM server by running
Configure WSO2 API Manager
- Start the API Manager and log in to its Admin Dashboard Web application (
Click the Configure Analytics menu.
Select the check-box to enable statistical data publishing and do the rest of the configurations using the information given below:
Event Receiver Configurations
Set the URL_to
<BAM_HOST_IP>is the machine's IP address. Do not use localhost unless you're in a disconnected mode.
You can define multiple event receiver groups, each with one or more receivers separated by commas. For an example
tcp://localhost:7612/, tcp://localhost:7613/. This helps you manage failover. If the BAM server in the first URL fails, the request will be routed to the second one.
Event receivers refer to the endpoint to which events are published from the API Gateway. Because you apply an offset to the default BAM port later in this guide, you need to apply the same offset to the default Thrift port. The API Manager then pushes the data to BAM through port 7614, using the Thrift protocol.
Data Analyser Configurations URL and the credentials of the event analyzer node. As this URL is used to deploy the toolbox, make sure that the BAM server is up and running in the given URL. Statistic Summary Datasource
Give the datasource definition that is used to store summarized statistical data. The tables are created automatically when the Hive script runs. You just need to create the schema. The same configurations will be done in the BAM server.
- URL: The connection URL for the RDBMS datasource
- JDBC Driver Class: The fully qualified Java class name of the JDBC driver
- Username/Password: Credentials to be passed to the JDBC driver to establish a connection
Tip: To edit the datasource connection pool parameters, click the Show More Options link.
Click Save when you are done. It deploys the Analytics toolbox, which describes the information collected, how to analyze the data, and the location of the database where the analyzed data is stored.
Tip: Are you working with an API Manager cluster or a distributed setup? If so,
If your registry is shared, do the above configurations in one node (e.g., the API Publisher) and restart the other nodes.
If your registry is not shared, do the same configuration in all API Gateway nodes, API Publisher node and API Store nodes by logging in to the admin-dashboard.
Change the API Publisher node to get response-based statistics such as destination-based usage tracking.
You change the stream names, versions, publisher class by editing the
<APIM_HOME>/repository/conf/api-manager.xmlfile as given in the example below:
Tip: Please read the code comments for details. If you change the default values under streams, the
<APIM_HOME>/statistics/API_Manager_Analytics.tboxmust also be changed accordingly.
After configuring WSO2 BAM to collect and analyze statistics of APIs hosted and managed by the API Manager, you can view them through various statistical dashboards in the API Publisher and Store, depending on your permission levels. For information, see .
Change the statistics database
To use a different database than the default H2 for statistical publishing, you 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.
If there are previous executions of the Hive scripts, manually execute them again by going to Main > Analytics > List in the management console of BAM. Alternatively, you can wait until the periodical execution time occurs.
RDBMS summarized tables
The following are the summarized tables that exist in API Manager.
Note that the MySQL database has been used here as an example.
This table contains the summarized data of the API destinations and is derived from the destination event stream.
This table contains the summarized data of faulty API invocations and is derived from the fault event stream.
This table contains the summary data of the request event stream.
This table contains the summarized data for API Manager usage by resources and is derived from the request event table.
This table contains the summarized data from API responses. It is derived from the response event table.
This table contains the summary data for API Manager usage. It is also derived from the request event table.
This table contains the summary of the throttle out API invocation data. It is derived from the throttle out event table and request table.
Troubleshoot common issues
Given below is how to do troubleshoot some common issues users come across:
- Do you get an out of memory issue?
See the performance tuning guide for recommendations to tune the server for optimal performance.
- Do you get an exception as unable to connect to server Cassandra?
Check if you changed the Cassandra port according to the port offset applied to the default BAM port. See Step 3 under configuring BAM section.
Do you get a connection refused exception on the BAM console?
This happens when you execute Hive scripts prior to changing the default port. Add the following line at the beginning of the Hive scripts and rerun:
drop table <hive_cassandra_table_name>;You can find the Hive scripts deployed with the toolbox file, which is inside
<BAM_HOME>/repository/deployment/server/bam-toolboxfolder. For information, see Editing an Analytic Script in WSO2 BAM documentation.