Publishing App Manager Runtime Statistics

This guide explains how to set up WSO2 Business Activity Monitor (BAM) to collect and analyze runtime statistics from WSO2 APP Manager. Thrift protocol is used to publish data from App Manager to BAM. Information processed in BAM is stored in a database, from where the App Manager publisher retrieves information before displaying. By default, org.wso2.carbon.appmgt.usage.publisher.APIMgtUsageDataPublisher is configured to collect data events from WSO2 BAM.

Configuring WSO2 BAM

1. Download WSO2 BAM 2.5.0.

2. Apply an offset of 3 to the default BAM port by editing the  <BAM_HOME>/repository/conf/carbon.xml  file.

   <Offset>3</Offset>

   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.

3. Specify the datasource definition under the  <datasource>  element in the  <BAM_HOME>/repository/conf/datasources/master-datasources.xml  file. The tables are created automatically when the Hive script runs. You just need to create the schema. The example below connects to a MySQL instance:

    <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>
               <url>jdbc:mysql://localhost:3306/stats_db?autoReconnect=true;</url>
               <username>db_username</username>
               <password>db_password</password>
               <driverClassName>com.mysql.jdbc.Driver</driverClassName>
               <maxActive>50</maxActive>
               <maxWait>60000</maxWait>
               <testOnBorrow>true</testOnBorrow>
               <validationQuery>SELECT 1</validationQuery>
               <validationInterval>30000</validationInterval>
            </configuration>
       </definition>
    </datasource>

4. Save the database driver JAR inside both <APIM_HOME>/repository/components/lib and <BAM_HOME>/repository/components/lib folders.

5. Copy the file  <AppM_HOME>/statistics/APP_Manager_Analytics.tbox , to   <BAM_HOME>/repository/deployment/server/bam-toolbox/  directory. 

   If this folder is not in the BAM installation directory by default, create it. The toolbox describes the information collected, how to analyze the data, as well as the location of the database where the analyzed data is stored.

6. Restart BAM server by running the following command: <BAM_HOME>/bin/wso2server.[sh/bat]

Configuring WSO2 App Manager

1. Set the following configurations in <AppM_HOME>/repository/conf/app-manager.xml file as follows. Change the default values of the  <BAMServerURL>, <BAMUsername>, and <BAMPassword> properties accordingly.

   <APIUsageTracking>
    
       <!-- Enable/Disable the API usage tracker. -->
       <Enabled>true</Enabled>  
       <PublisherClass>org.wso2.carbon.appmgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher</PublisherClass>
       <ThriftPort>7614</ThriftPort>
       <BAMServerURL>tcp://<IP_ADDRESS>:7614</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>

   Replace <IP_ADDRESS> within the <BAMServerURL> element in the above configuration, with the IP address of your BAM server, and also change the values of the <BAMUsername> and <BAMPassword> accordingly if you have changed them

2. Specify the datasource definition in <APPM_HOME>/repository/conf/datasources/master-datasources.xml file as follows. 

   <datasource>
             <name>WSO2AM_STATS_DB</name>
             <description>The datasource used for getting statistics to APP Manager</description>
             <jndiConfig>
                <name>jdbc/WSO2AM_STATS_DB</name>
             </jndiConfig>
             <definition type="RDBMS">
                <configuration>
                    <!-- JDBC URL to query the database -->
                      <url>jdbc:mysql://localhost:3306/stats_db?autoReconnect=true;</url>
               	   <username>db_username</username>
               	   <password>db_password</password>
               	   <driverClassName>com.mysql.jdbc.Driver</driverClassName>
               	   <maxActive>50</maxActive>
               	   <maxWait>60000</maxWait>
               	   <testOnBorrow>true</testOnBorrow>
               	   <validationQuery>SELECT 1</validationQuery>
               	   <validationInterval>30000</validationInterval>
               </configuration>
            </definition>
     </datasource>

   • Replace the <BAM_HOME> in the above configuration with the absolute path of BAM installation directory.

   • The JNDI name should be matched with the one give in the BAM configuration.

3. Start the WSO2 AppM server.

Tracking Web app usage 

You can track the usage of the web application as follows.

Tracking ID

The tracking ID is a string (for example: AM-000000-01), which is  generated when you create the Web app in WSO2 AppM. Follow the steps below to view the tracking ID.

1. Log in to the App Publisher using the following URL: https://<AppM_HOST>:<AppM_PORT>/publisher/
2. Click Web Applications, and then click All Web Applications.
3. Click on the Web app of which you need to publish runtime statistics. The tracking ID is available in the Overview page of the Web app, once it is created as shown below.
   

Tracking code

Add the following configuration in the Web page, which you want to track the usage. It activates tracking by inserting  invokeStatistics.js  into the page. 

<script type="text/javascript" src="invokeStatistics.js" ></script>
<script type="text/javascript">
       invokeStatistics();
</script>

Include the following code snippet in the invokeStatistics.js file. Replace  AM-XXXXXX-X with the web app tracking ID and define t he URL with an endpoint.

function invokeStatistics(){
        var tracking_code = "AM-XXXXXX-X";
        var request = $.ajax({
        url: "http://localhost:8280/statistics/",
        type: "GET",
        headers: {
			"trackingCode":tracking_code,
		}
    
    });
}

Viewing runtime statistics

Follow the steps below to view the runtime statistics.

1. Log in to the App Publisher using the following URL: http://<AppM_HOST>:<AppM_PORT>/publisher

2. Click  Statistics  as shown below.
   

You can view the following runtime statistics on apps.

Usage by app

This displays the number of subscribers per each Web application as shown below.

Response time

This displays response time statistics per each Web application as shown below.

Usage by page

This displays the request count per each Web app as shown below.

Click on the bar of the corresponding Web app in the graph to view the breakdown of the number of hits per page of that Web app as shown below.

Change the statistics database

To use a different database than the default H2 for publishing statistics, 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. Follow the steps below to delete the metadata tables.

1. Log in to the BAM management console, and click Add in the Analytics menu.
2. Go to the Script Editor in the window that opens.

3. Execute the  following script.

   DROP TABLE APIRequestData;
   DROP TABLE APIRequestSummaryData;
   DROP TABLE CacheStatSummaryData;
   DROP TABLE CacheRequestSummaryData;
   DROP TABLE APIVersionUsageSummaryData;
   DROP TABLE APIResponseSummaryData;
   DROP TABLE APM_APP_HIT_TOTAL_TEMP;
   DROP TABLE APM_APP_HIT_TOTAL;