Integrate API Manager Analytics

The API Manager Analytics provides reports, statistics and graphs on the APIs deployed in WSO2 Open Banking API Manager. You can then configure alerts to monitor these APIs and detect unusual activity, manage locations via geo-location statistics and carry out a detailed analysis of the logs. 

This section explains how to integrate API Manager Analytics with the WSO2 Open Banking solution.

Configuring databases

You can configure databases to persist, process and analyze API-related data. Follow the steps below to configure the databases.

1. Create the ANALYTICS_DB database in your database server.

2. Configure the worker profile.   

   Open the <WSO2_OB_API-M_ANALYTICS_HOME>/conf/worker/deployment.yaml file. Update the APIM_ANALYTICS_DB datasource with your database configurations.

   deployment.yaml

   - name: APIM_ANALYTICS_DB
   description: The Datasource used for APIM Analytics
   jndiConfig:
     name: jdbc/APIM_ANALYTICS_DB
   definition:
     type: RDBMS
     configuration:
       jdbcUrl: 'jdbc:<DB_TYPE>://<DB_HOST>:<DB_PORT>/ANALYTICS_DB?autoReconnect=true&useSSL=false'
       username: <DB_USERNAME>
       password: <DB_PASSWORD>
       driverClassName: <DB_DRIVER>
       maxPoolSize: 50
       idleTimeout: 60000
       connectionTestQuery: SELECT 1
       validationTimeout: 30000
       isAutoCommit: false

3. Configure the dashboard profile.   

   Open the <WSO2_OB_API-M_ANALYTICS_HOME>/conf/dashboard/deployment.yaml file. Update the APIM_ANALYTICS_DB datasource with your database configurations.

   deployment.yaml

   - name: APIM_ANALYTICS_DB
   description: The Datasource used for APIM Analytics
   jndiConfig:
     name: jdbc/APIM_ANALYTICS_DB
   definition:
     type: RDBMS
     configuration:
       jdbcUrl: 'jdbc:<DB_TYPE>://<DB_HOST>:<DB_PORT>/ANALYTICS_DB?autoReconnect=true&useSSL=false'
       username: <DB_USERNAME>
       password: <DB_PASSWORD>
       driverClassName: <DB_DRIVER>
       maxPoolSize: 50
       idleTimeout: 60000
       connectionTestQuery: SELECT 1
       validationTimeout: 30000
       isAutoCommit: false

   By default, the following datasource entries are configured to H2 databases. If required, you can create external databases and point these entries to them.

   Datasource Name	File
   BUSINESS_RULES_DB	<WSO2_OB_API-M_ANALYTICS_HOME>/conf/dashboard/deployment.yaml
   WSO2_PERMISSIONS_DB	<WSO2_OB_API-M_ANALYTICS_HOME>/conf/worker/deployment.yaml <WSO2_OB_API-M_ANALYTICS_HOME>/conf/dashboard/deployment.yaml

   The GEO_LOCATION_DATA datasource should be configured when you are using Geo-location based statistics

4. Integrate third-party products when configuring databases.

   WSO2 SP is a OSGi-based product. Therefore, when you integrate third party products such as Oracle and MS SQL with WSO2 API-M Analytics, you need to check whether the libraries you need to add are OSGi based. If they are not, you need to convert them to OSGi bundles before adding them to the <WSO2_OB_API-M_ANALYTICS_HOME>/lib directory. 

   To convert the jar files to OSGi bundles, follow the steps below.

   1. Download the non-OSGi jar for the required third party product, and save it in a preferred directory in your machine.

   2. Go to the <API-M_ANALYTICS_HOME>/bin directory. Run the command given below, to generate the converted file in the <API-M_ANALYTICS_HOME>/lib directory.

   ./jartobundle.sh <PATH_TO_NON-OSGi_JAR> ../lib

Configuring keystores

In the SSL handshake between the API Management profile and the Analytics profile, the client/API Management profile needs to verify the certificate presented by the server/Analytics profile. For this purpose, the client stores the trusted certificate of the server in the client-truststore.jks keystore.

If you use a custom keystore, import the public key certificate of the Analytics profile into the client-truststore.jks file of the API Management profile. To export the public key from the server, and import it into the client's truststore, follow the steps below:

Step 1: Generating a CA-signed certificate

First, you need to generate a Certificate Signing Request (CSR) for your keystore (.jks file). This CSR file can then be certified by a certification authority (CA), which is an entity that issues digital certificates. These certificates certify the ownership of a public key.

1. Execute the following command to generate the CSR:

   keytool -certreq -alias certalias -file newcertreq.csr -keystore newkeystore.jks

   You are asked to give the keystore password. Once the password is given, the command outputs the new certreq.csr file to the wso2am-analytics-2.6.0/resources/security directory. This is the CSR that you must submit to a CA.

2. You must provide this CSR file to the CA.
3. After accepting the request, a signed certificate is provided along with a root certificate and several intermediate certificates (depending on the CA) as a bundle (.zip file).

Step 2: Importing certificates to the keystore

Follow the steps given below to import the CA-signed certificate to your keystore.

1. Before importing the CA-signed certificate to the keystore, you must add the root CA certificate and the two (related) intermediate certificates by executing the commands given below. Note that the sample certificates given above are used as examples:

   keytool -import -v -trustcacerts -alias ExternalCARoot -file AddTrustExternalCARoot.crt -keystore newkeystore.jks -storepass mypassword
   
   keytool -import -v -trustcacerts -alias TrustCA -file COMODORSAAddTrustCA.crt -keystore newkeystore.jks -storepass mypassword
   
   keytool -import -v -trustcacerts -alias SecureServerCA -file COMODORSADomainValidationSecureServerCA.crt -keystore newkeystore.jks -storepass mypassword 

2. After you add the root certificate and all other intermediate certificates, add the CA-signed SSL certificate to the keystore by executing the following command:

   keytool -import -v -alias newcert -file <test_sampleapp_org.crt> -keystore newkeystore.jks -keypass mypassword -storepass mypassword

   In this command, use the same alias (i.e., newcert) that you used while creating the keystore.

   
   

   Now you have a Java keystore, which includes a CA-signed public key certificate that can be used for SSL in a production environment. 

   Next, you may need to add the same CA-signed public key certificate to the client-truststore.jks file. This provides security, and trust for backend communication/inter-system communication of WSO2 products via SSL.

Step 3: Importing certificates to the truststore

In SSL handshake, the client needs to verify the certificate presented by the server. For this purpose, the client usually stores the certificates it trusts, in a truststore. To enable secure and trusted backend communication, all WSO2 products are shipped with a truststore named client-truststore.jks, which resides in the same directory as the default keystore (wso2am-analytics-2.6.0/resources/security).

Follow the steps given below to import the same CA-signed public key certificate (which you obtained in the previous step) into your WSO2 product's default truststore (client-truststore.jks).

1. Get a copy of the client-truststore.jks file from the wso2am-analytics-2.6.0/resources/security directory.

2. Export the public key from your .jks file using the following command.

   keytool -export -alias certalias -keystore newkeystore.jks -file <public key name>.pem

3. Import the public key you extracted in the previous step to the client-truststore.jks file using the following command.

   keytool -import -alias certalias -file <public key name>.pem -keystore client-truststore.jks -storepass wso2carbon

   Note that wso2carbon is the keystore password of the default client-truststore.jks file.

   Now, you have an SSL certificate stored in a Java keystore and a public key added to the client-truststore.jks file. Note that both these files should be in the wso2am-analytics-2.6.0/resources/security directory. You can now replace the default wso2carbon.jks keystore in your product with the newly created keystore by updating the relevant configuration files in your product.

Enabling performance tuning and starting the servers

1. You can enable performance tuning by adding configurations, as described in Performance Tuning in the WSO2 DAS documentation.
2. Set the path and hostname to API-M Analytics in the wso2-obam1.3.0/repository/resources/finance/script/startup.properties file.
3. Navigate to the wso2-obam-1.3.0/repository/resources/finance/scripts/wso2am-analytics folder, give execution permissions to the configure-am-analytics.sh file, and run it.
4. Navigate to the wso2am-analytics-2.6.0/bin directory, and give execution permissions to the worker.sh file.

5. Run the API-M Analytics worker.sh as follows:

   ./bin/worker.sh -Dsetup

6. Navigate to the wso2am-analytics-2.6.0/bin directory, and give execution permissions to the dashboard.sh file.

7. Run the API-M Analytics dashboard.sh as follows:

   ./bin/dashboard.sh -Dsetup

8. Open the wso2-obam-1.3.0/repository/conf/api-manager.xml file to enable analytics:

   <Analytics>
        <Enabled>true</Enabled>
   <Analytics>

9. Save your changes and restart the API-M server from the wso2-obam-1.3.0/bin directory.
10. You can view analytics data as described below:
    1. Log in to the API Store using the credentials provided during signup.
    2. Click the Analytics tab.
    3. You can view API Usage, Top Users and Faulty Invocations details through the subtopics.
11. To observe data analysis based on geographical locations, see Configuring Geolocation Based Statistics.