This documentation is for WSO2 API Manager 1.5.0 View documentation for the latest release.
Page Comparison - Generating Billing Data (v.9 vs v.10) - API Manager 1.5.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Table of Contents
maxLevel3
minLevel3

Introduction

This sample demonstrates how to setup WSO2 Business Activity Monitor (BAM) to collect and summarize runtime statistics from the WSO2 API Manager and generate bills for API consumers on usage.

Prerequisites

Building and running the sample

Configuring BAM

  1. Open <BAM_HOME>/repository/conf/carbon.xml file where <BAM_HOME> is the BAM binary distribution folder that was downloaded as a prerequisite above. Change the carbon.xml file's port offset to 1. This is done to avoid any port conflicts of running two WSO2 Carbon instances in the same machine.

    <Offset>1</Offset>
  2. Copy the API_Manager_Analytics.tbox in <APIM_HOME/samples/Billing folder to <BAM_HOME>/repository/deployment/server/bam-toolbox folder. Create the bam-toolbox directory if it already doesn't exist.

    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.
  3. Configure a database to which BAM can write analyzed information to.
  4. Add the following code segment to <BAM_HOME>/repository/conf/datasources/master-datasources.xml file. 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.

    Code Block
    languagehtml/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: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>
  5. 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
    languagehtml/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>;
  6. Start WSO2 BAM server by running wso2server.bat (on Windows) and wso2server.sh (on Linux).

Configuring API Manager

  1. To enable API statistics collection, configure the following properties in <APIM_HOME>/repository/conf/api-manager.xml file. Ensure that <DataSourceName> name is the same as JNDI config name in master-datasources.xml file in BAM.

    Code Block
    languagehtml/xml
    <!-- Enable/Disable the API usage tracker. -->
    <Enabled>true</Enabled>
    
    <!-- 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>
    
    <!-- Enable/Disable Usage metering and billing for api usage -->
    <EnableBillingAndUsage>true</EnableBillingAndUsage>
  2. Configure the data source definition in <APIM_HOME>/repository/conf/datasources/master-datasources.xml file.

    Note: Replace <BAM_HOME> in the configuration below with the path to the actual BAM distribution location and the JNDI names must match the ones defined earlier in API Manager.

    Code Block
    languagehtml/xml
    <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>
  3. Copy <APIM_HOME>/samples/Billing/billing-conf.xml file into <APIM_HOME>/repository/conf folder.

Viewing billing information

Once the above configurations are done, log in to API Store Web application (https://<YourHostName>:9443/store). You will see the menu items required for API Monetization in the menu bar at the top of the page.

Info
If you are a new user, there will not be any billing information at the beginning.