Monitoring and Statistics

This chapter 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.

Note

Throughout this chapter, <AM_HOME> refers to the API Manager installation directory whereas, <BAM_HOME> refers to the Business Activity Monitor installation directory.
The data sources and databases 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.

2. Enable API tracking option by setting the "APIUsageTracking" element to true in <AM_HOME>/repository/conf/api-manager.xml and specify the data source name to be used for getting BAM statistics. For example:

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

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.

5. Specify the data source definition used in the above configuration in <AM_HOME>\repository\conf\datasourcesmaster-datasources.xml file as shown below. The <Name>WSO2AM_STATS_DB</Name> XML node defines the datasource used to fetch analytical data. An H2 database is used in this example.

<datasource>
     <name>WSO2AM_STATS_DB</name>
     <description>The datasource used for getting statistics to API Manager</description>
     <jndiConfig>
          <!-- This jndi name should be same as the DataSourceName defined in api-manager.xml -->
          <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 should be the same as <APIUsageTracking> element in api-manager.xml defined in step 2.

Next, prepare BAM to collect and analyze statistics from API manager.

6. Copy the file <AM_HOME>/statistics/API_Manager_Analytics.tbox to directory, <BAM_HOME>/repository/deployment/server/bam-toolbox. If this folder is not in the BAM installation folder by default, create it before copying 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.

7. Change port offset for the BAM product to 1 by editing the file <BAM_HOME>/repository/conf/carbon.xml file (search for the offset node).

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

<datasource>
       <name>WSO2AM_STATS_DB</name>
       <description>The datasource used for getting statistics to API Manager</description>
       <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>

9. Start WSO2 BAM server by running <BAM_HOME>/bin/wso2server.[sh/bat].

10. If you want to host the BAM server on a different machine or change the running port, you must edit the <APIUsageTracking> node in <AM_HOME>/repository/conf/api-manager.xml file as follows:

<!--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>

Once the WSO2 BAM is configured 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 permission levels of the login. For information, refer to section Viewing API Statistics .