Page Comparison

This chapter 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 BAM to be used with the WSO2 API Manager.

Throughout this chapter, <AM_HOME> refers to the API Manager installation directory whereas,

Info

titleicon	Note

false

<BAM_HOME> refers to the Business Activity Monitor installation directory.
The data sources source and databases database names used in this guide are just examples. They may vary depending on your configurations.

1. Download WSO2 BAM 2.0 from location: http://wso2.com/products/business-activity-monitor.

Image Removed

...

The recommended version of BAM is 2.3.0 or later.
Ensure that you have JDK 1.6.* or 1.7 installed in your environment.

Follow the instructions below to set up BAM to be used with the WSO2 API Manager.

Table of Contents

maxLevel	3
minLevel	3

Configuring 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

...

,

Code Block

language	html/xml

<APIUsageTracking>

    <!-- Enable/Disable the API usage tracker. -->
    <Enabled>true</Enabled>   
    <PublisherClass>org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher</PublisherClass>
    <ThriftPort>7612</ThriftPort> 
    <BAMServerURL>tcp://localhost:7612/</BAMServerURL>
    <BAMUsername>admin</BAMUsername>
    <BAMPassword>admin</BAMPassword>
    <!-- JNDI name of the data source to be used for getting BAM statistics. This data source should
        be defined in the master-datasources.xml file in conf/datasources directory. -->
    <DataSourceName>jdbc/WSO2AM_STATS_DB</DataSourceName>

</APIUsageTracking>

Note

3. Restart the API Manager.

4. Next, 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. Thrift protocol is used to publish data from the API Manager to BAM.

...

In the above configuration, the default Thrift port is increased by 1 because we apply an offset of 1 to default BAM port later in this guide.
Specify the data source definition

...

in

...

<APIM_HOME>

...

/repository

...

/conf

...

/datasources

...

/master-datasources.xml file as

...

follows. WSO2AM_STATS_

...

DB is the datasource used to fetch analytical data

...

.

Code Block

language	html/xml

  <datasource>
          <name>WSO2AM_STATS_DB</name>
          <description>The datasource used for getting statistics to API Manager</description>

...

<jndiConfig>

...

 <name>jdbc/WSO2AM_STATS_DB</name>

...

</jndiConfig>

...

      <definition type="RDBMS">
          <configuration>

...

                 <!-- JDBC URL to query the database -->
                 <url>jdbc:h2:<BAM_HOME>/repository/database/APIMGTSTATS_DB;AUTO_SERVER=TRUE</url>
                 <username>wso2carbon</username>
                 <password>wso2carbon</password>
                 <driverClassName>org.h2.Driver</driverClassName>
                 <maxActive>50</maxActive>
                 <maxWait>60000</maxWait>
                 <testOnBorrow>true</testOnBorrow>
                 <validationQuery>SELECT 1</validationQuery>
                 <validationInterval>30000</validationInterval>
            </configuration>
         </definition>
  </datasource>

...

Note
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 BAM

Download WSO2 BAM 2.0 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.xml file (search for the offset node).
```
<Offset>1</Offset>
```
This increments all ports used by the server by 1, which means the BAM server will now run on port 9444. Port offset avoids possible port conflicts when multiple WSO2 products are run in same host.
Copy the file <APIM_HOME>/statistics/API_Manager_Analytics.tbox to directory, <BAM_HOME>/repository/deployment/server/bam-toolbox. If you use Oracle DB to store statistical data, copy API_Manager_Analytics_Oracle.tbox instead.

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.

...

Note

The sample API_Manager_Analytics toolbox works fine when the BAM port offset is set to 1 as we did in the previous step. But, if you set a different offset to BAM, you must change the am_stats_analyzer script of the toolbox as follows:

Go to BAM Management Console
Select Analytics > List menu
Click Edit on am_stats_analyzer_330
Change the cassandra.port value to 9161+ <BAM offset>

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.xml file as follows.

WSO2AM_STATS_DB is 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.
Note: T he JNDI config names here must match the ones defined earlier in APIM.

Code Block
language html/xml

...

<!-- 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>1</Offset>

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 Carbon-based products are run in same host.

8. Add the following to <BAM_HOME>/conf/datasources/master-datasources.xml file.

...

language	html/xml

...

  <datasource>
          <name>WSO2AM_STATS_DB</name>
          <description>The datasource used for getting statistics to API Manager</description>
        <jndiConfig>

...

<name>jdbc/WSO2AM_STATS_DB</name>

...

</jndiConfig>

...

        <definition type="RDBMS">
          <configuration>
                 <!-- JDBC URL to query the database -->
                 <url>jdbc:h2:<BAM_HOME>/repository/database/APIMGTSTATS_DB;AUTO_SERVER=TRUE</url>
                 <username>wso2carbon</username>
                 <password>wso2carbon</password>
                 <driverClassName>org.h2.Driver</driverClassName>
                 <maxActive>50</maxActive>
                 <maxWait>60000</maxWait>
                 <testOnBorrow>true</testOnBorrow>
                 <validationQuery>SELECT 1</validationQuery>
                 <validationInterval>30000</validationInterval>
            </configuration>
         </definition>
  </datasource>

...

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.

For a list of default ports used by WSO2 products, see Default Ports of WSO2 Products .

Code Block

language	html/xml

<datasource>
           <name>WSO2BAM_CASSANDRA_DATASOURCE</name>
           <description>The datasource used for Cassandra data</description>
           <definition type="RDBMS">
               <configuration>
                   <url>jdbc:cassandra://localhost:9161/EVENT_KS</url>
                   <username>admin</username>
                   <password>admin</password>
               </configuration>
           </definition>
</datasource>

Note
If you run the Hive scripts before changing the default Cassandra port according to the BAM port offset, you keep getting an exception. To overcome this, add the following line at the beginning of the Hive script and rerun. drop table <hive_cassandra_table_name>;

Restart BAM server by running <BAM_HOME>/bin/wso2server.[sh/bat].

...

If you want to host the BAM server on a different machine or change the running port, you must edit the <APIUsageTracking> node in

...

<APIM_HOME>/repository/conf/api-manager.xml file as follows:

Code Block

language	html/xml

<!--API usage tracker configuration used by the BAM data publisher in API gateway.-->
    <APIUsageTracking>
        <!-- Enable/Disable the API usage tracker.-->
        <Enabled>true</Enabled>

        <!-- API Usage Data Publisher.-->
        <PublisherClass>org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher</PublisherClass>

        <!--Thrift port of the remote BAM server.-->
        <ThriftPort>7612</ThriftPort>

        <!-- Server URL of the remote BAM server used to collect statistics. Must be specified in protocol://hostname:port/ format.-->
        <BAMServerURL>tcp://localhost:7612</BAMServerURL>

        <!--Administrator username to login to the remote BAM server.-->
        <BAMUsername>admin</BAMUsername>

        <!--Administrator password to login to the remote BAM server.-->
        <BAMPassword>admin</BAMPassword>

        <!--JNDI name of the data source to be used for getting BAM statistics.This data source should be defined in the master    
            datasources.xml file in conf/datasources directory.-->
        <DataSourceName>jdbc/WSO2AM_STATS_DB</DataSourceName>
    </APIUsageTracking>

...

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.

Code Block

drop table APIRequestData;
drop table APIRequestSummaryData;
drop table APIVersionUsageSummaryData;
drop table APIVersionUsageSummaryData;
drop table APIResponseData;
drop table APIResponseSummaryData;
drop table APIRequestData;
drop table APIRequestSummaryData;
drop table APIVersionUsageSummaryData;
drop table APIResponseData;
drop table APIResponseSummaryData;

...

After configuring WSO2 BAM to render and produce statistics of APIs hosted and managed in the API Manager, you can view them through various statistical dashboards in the API Publisher, depending on the your permission levels of the login. For information, refer to section Viewing API Statistics.

...

hidden	true

.

...

Versions Compared

Old Version 2

New Version 3

Key

Configuring API Manager

Configuring BAM

The API Manager Analytic Toolbox

Changing the statistics database