This documentation is for WSO2 API Manager 1.8.0 View documentation for the latest release.
Page Comparison - Publishing API Runtime Statistics (v.15 vs v.36) - API Manager 1.8.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

By default, org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataPublisher is configured to push data events to WSO2 BAM. If you use a system 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 you implement has a minimal impact to API invocation.

...

  1. Do the following changes in <APIM_HOME>/repository/conf/api-manager.xml file:

    • Enable API usage tracking by setting the <APIUsageTracking> element to true.
    • Because you will apply an offset to the default BAM port later in this guide, you need to apply the same offset to the default Thrift port. To do that, change the port value to 7614 in the <ThriftPort> element of this file. The API Manager will then push the data to BAM through port 7614, using the Thrift protocol.
    • Set Uncomment and set the data source used for getting BAM statistics in <DataSourceName> element.
    • Set <BAMServerURL> to tcp://<BAM host IP>:7614/ where <BAM host IP> is the machine IP address. Do not use localhost unless you're in a disconnected mode.

      Info

      <BAMServerURL> refers to the endpoint to which events will be published from the API Gateway. This endpoint is also known as the event receiver. You can define multiple event receiver groups, each with one or more receivers. A receiver group is defined within curly braces and receiver URLs are delimited by commas.

      For example, <BAMServerURL>{tcp://localhost:7612/,tcp://localhost:7613/},{tcp://localhost:7712/,tcp://localhost:7713/}</BAMServerURL>. This example has two receiver groups defined with two receivers in each group. When a request passes through the API Gateway, an event will be published to one selected receiver in each group.

    Code Block
    languagehtml/xml
    <APIUsageTracking>
        <!-- Enable/Disable the API usage tracker. -->
        <Enabled>true</Enabled>   
        <PublisherClass>org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher</PublisherClass>
        <ThriftPort>7614</ThriftPort> 
        <BAMServerURL>tcp://<BAM host IP>: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>
    Tip

    Tip: You can give a comma-separated list of URLs as the <BAMServerURL> to manage failover. If the BAM server in the first URL fails, the request will be routed to the second one.

    Tip

    Tip: Are you working with an API Manager cluster? If so, 

    • Configure the <APIUsageTracking> element as given above in all API Gateway nodes
    • Configure the following sub elements under the <APIUsageTracking> element in the API Publisher and Store nodes:

      <Enabled>true</Enabled>
      Code Block
      languagexml
      <DataSourceName>jdbc/WSO2AM_STATS_DB</DataSourceName>
    Anchorstep2step2
    • If you use destination-based usage tracking, enable the <APIUsageTracking> element in the Publisher node and connect to a running BAM instance. This is because the API Manager uses a separate BAM mediator to do destination based usage tracking. 

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

    Note

    The WSO2AM_STATS_DB database is not available in <BAM_HOME>/repository/database directory at this point. It is created only after BAM starts up.

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

    Tip: Do you want to connect to MySQL?

    The example above uses the H2 database that comes with the API Manager by default. If you want to connect to a separate database instance like MySQL, do the following:

  3. Save the database driver JAR inside both <AM_HOME>/repository/components/lib and <BAM_HOME>/repository/components/lib folders.
  4. Change the <datasource> configuration according to the database you want to connect to.

     file. The tables are created automatically when the Hive script runs. You just need to create the

    schema

    database. The example below connects to a MySQL instance:

    Code Block
    languagexml
    <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&amp;</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>
  5.  Save the database driver JAR inside both <AM_HOME>/repository/components/lib and <BAM_HOME>/repository/components/lib folders.

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

Configure WSO2 BAM

  1. Download WSO2 BAM 2.45.1 0 from location: http://wso2.com/products/business-activity-monitor.
  2. Copy the <APIM_HOME>/statistics/API_Manager_Analytics.tbox to <BAM_HOME>/repository/deployment/server/bam-toolbox folder. This enables the BAM server to create the required tables in the statistical database that you set up earlier. 

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

    Code Block
    languagehtml/xml
    <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 in same host.

  4. Anchor
    point3
    point3

    Do the following changes in

    In <BAM_HOME>/repository/conf/datasources/bam_datasources.xml file

    :Copy

    , copy/paste WSO2AM_STATS_DB definition from the API Manager's master-datasources.xml file. You edited it in step 2. WSO2AM_STATS_DB is used to fetch analytical data from the database

    .Uncomment the hostName element in <BAM_HOME>/repository/conf/data-bridge/data-bridge-config.xml file and give the IP address instead of localhost

    .

     You can get the IP from the <APIM_HOME>/repository/conf/api-manager.xml file's,

     

    <BAMServerURL><BAM host IP> element. Code Block
    languagexml
     <thriftDataReceiver> <hostName>localhost</hostName> <port>7611</port> <securePort>7711</securePort> </thriftDataReceiver>


    Tip

    Tip: If you are using

    the

    BAM 2.4.1

    or older, replace the port of WSO2BAM_CASSANDRA_DATASOURCE in URL (jdbc:cassandra://localhost:9163/EVENT_KS). Note that localhost is used here; not the machine IP. Cassandra is bound by default on localhost, unless you change the 

    , be sure to uncomment the <thriftDataReceiver><hostName> element in the <BAM_HOME>/repository/conf/data-bridge/data-bridge-config.xml file

    .Copy the file <APIM_HOME>/statistics/API_Manager_Analytics.tbox to directory <BAM_HOME>/repository/deployment/server/bam-toolbox.
    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.

    Open <BAM_HOME>/repository/conf/etc/hector-config.xml file and change the port to localhost:9163. You must add the other nodes too when configuring a clustered setup.

    Code Block
    languagexml
    <Nodes>localhost:9163</Nodes>
    Tip

    This step is not needed if you are using WSO2 BAM 2.5.0and give the BAM host IP there.

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

Troubleshoot common issues

...