Page History

This mode of setup is only recommended for non-critical demos and quick try-out scenarios. Once you run the servers you will notice that there are database files being created in a folder called tmpStatDB in the directory where you installed the two servers. These are H2 databases that hold the summarized data of your API Analytics. In a more standard deployment, this data is recorded in database servers such as MySQL, Oracle, etc. Therefore, this mode of operation is not recommended for production grade or other critical deployments.

If API-M Analytics is properly configured in WSO2 API Manager, when you start up the API Manager server, which is after the WSO2 API-M Analytics server, you will see the following log message in the terminal that is running the API-M Analytics server.

INFO {org.wso2.carbon.databridge.core.DataBridge} -  user admin connected

If you are configuring API-M Analytics with MSSQL  and you get an error when you start the API-M Analytics server stating that a table cannot have more than one clustered index, follow the steps below.

1. Open the <API-M_ANALYTICS_HOME>/repository/components/features/org.wso2.carbon.analytics.spark.server_VERSION/spark-jdbc-config.xml file.

2. Update the value for the <indexCreateQuery> element of the MySQL database as shown below.

   Code Block
   language xml
   <database name="Microsoft SQL Server"> <indexCreateQuery>CREATE INDEX {{TABLE_NAME}}_INDEX ON {{TABLE_NAME}} ({{INDEX_COLUMNS}})</indexCreateQuery> </database>

Step 1 - Download WSO2 API-M and WSO2 API-M Analytics

Step 2 - Install WSO2 API-M Analytics

Take the following steps to install WSO2 APIM Analytics. Because this procedure is identical to installing WSO2 Data Analytics Server (DAS), these steps take you to the DAS documentation for details.

1. Ensure that you have met the Installation Prerequisites.
2. Go to the installation instructions relevant to your operating system:
   
   • Installing on Linux
   • Installing on Windows
   • Installing as a Windows Service
   • Installing as a Linux Service

Step 3 - Configure WSO2 API Manager to publish statistics

Follow the instructions below to do the required configurations for WSO2 API-M to publish statistics in the WSO2 API-M Analytics server.

1. Open the <API-M_HOME>/repository/conf/api-manager.xml file. 
2. Under the <Analytics> sub element, set the Enabled parameter to true.

3. Configure the following parameters if required.

   Parameter	Value	Description
   <DASServerURL>	<protocol>://<hostname>:<port>/	The server URL of the remote DAS/CEP server used to collect statistics from WSO2 API Manager. An event can also be published to multiple receiver groups, where each group has one or more receivers. Receiver groups are delimited by curly braces, whereas receivers are delimited by commas. e.g., Three receivers within a single group can be specified as follows. tcp://localhost:7612,tcp://localhost:7613,tcp://localhost:7614 Two receiver groups with two receivers each can be specified as follows. {tcp://localhost:7612,tcp://localhost:7613},{tcp://localhost:7712,tcp://localhost:7713} For more information on configuring multiple data receivers, see Setting up Multi Receiver and Load Balancing Data Agent.
   <DASUsername>	A valid administrator username	The administrator user name to log into the remote DAS/CEP server that collects statistics from WSO2 API Manager. Info If you enable email user, you need to configure @carbon.super to the username of the API-M Analytics admin user. e.g., If the username of the API-M Analytics admin use is demo@wso2.com, it must be demo@wso2.com @carbon.super once you have enabled email user. It is required to change the values DASUsername and DASPassword parameters if the user of WSO2 API-M is different to the user of WSO2 DAS/CEP. The default value ${admin.username} retrieves the admin user of the current API-M node as the DASUsername.
   <DASPassword>	The password of the username specified.	The administrator password to log into the remote DAS/CEP server that collects statistics from WSO2 API Manager. Info It is required to change the values DASUsername and DASPassword parameters if the user of WSO2 API-M is different to the user of WSO2 DAS/CEP. The default value ${admin.password} retrieves the admin user of the current API-M node as the DASUsername .
   <DASRestApiURL>	https://<host>:<port>	The WSO2 DAS (WSO2 API-M Analytics) REST API URL. The WSO2 DAS REST API connection information, which are included under the REST API-M connection information, are defined as global properties, as they are common to all the WSO2 API-M analytics.
   <DASRestApiUsername>	A valid administrator username	The administrator username to log into the remote WSO2 DAS (WSO2 API-M Analytics) server.
   <DASRestApiPassword>	The password of the username specified.	The administrator password to log into the remote WSO2 DAS (WSO2 API-M Analytics) server.

4. Save the changes.

Step 4 - Configure the Log Analyzer

Follow the steps below to configure the Log Analyzer.

1. Add DAS_AGENT to the end of the root logger in the <API-M_HOME>/repository/conf/log4j.properties file as shown below.

   Code Block
   log4j.rootLogger=<other loggers>, DAS_AGENT

   
   Then check and make sure that the following configuration is available in the same file. Modify the values for userName, password and/or url if required.

   Info
   The values given below are the default values of the configuration.

   Code Block

   # DAS_AGENT is set to be a Custom Log Appender. log4j.appender.DAS_AGENT=org.wso2.carbon.analytics.shared.data.agents.log4j.appender.LogEventAppender # DAS_AGENT uses PatternLayout. log4j.appender.DAS_AGENT.layout=org.wso2.carbon.analytics.shared.data.agents.log4j.util.TenantAwarePatternLayout log4j.appender.DAS_AGENT.columnList=%D,%S,%A,%d,%c,%p,%m,%H,%I,%Stacktrace log4j.appender.DAS_AGENT.userName=admin log4j.appender.DAS_AGENT.password=admin log4j.appender.DAS_AGENT.url=tcp://localhost:7612 log4j.appender.DAS_AGENT.maxTolerableConsecutiveFailure=5 log4j.appender.DAS_AGENT.streamDef=loganalyzer:1.0.0

2. To view log analytics on the API-M Admin portal, you have to set the DAS REST API configurations (DASRestApiURL, DASRestApiUsername, DASRestApiPassword). You can give the same previous value as <DASUsername> to <DASRestApiUsername> and <DASPassword> to <DASRestApiPassword>. The <DASRestApiURL> value should be in the following format,
   https://<DAS Hostname>:<DAS Https port> . Go to the <API-M_HOME>/repository/conf/api-manager.xml file and change the value given below.

   Code Block
   language xml
   <DASRestApiURL>https://analytics.wso2.com:9444</DASRestApiURL>

3. If the API-M server and the DAS server run on two different hosts with their default certificates, set the HostnameVerifier to AllowAll in the Pass Through HTTP SSL Sender section of the <API-M_HOME>/repository/conf/axis2/axis2.xml file as follows. If this setting is not changed, the javax.net.ssl.SSLException: Host name verification failed for host exception may occur for the API-M instance.

   Code Block
   language xml
   <transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender"> <parameter name="non-blocking" locked="false">true</parameter> <parameter name="keystore" locked="false"> <KeyStore> <Location>repository/resources/security/wso2carbon.jks</Location> <Type>JKS</Type> <Password>wso2carbon</Password> <KeyPassword>wso2carbon</KeyPassword> </KeyStore> </parameter> <parameter name="truststore" locked="false"> <TrustStore> <Location>repository/resources/security/client-truststore.jks</Location> <Type>JKS</Type> <Password>wso2carbon</Password> </TrustStore> </parameter> <parameter name="HostnameVerifier">AllowAll</parameter> </transportSender>

4. If the WSO2 API Manager was started before these configurations were done, restart it in order to apply the changes.

Step 5 - Secure the log4j properties file with a secure vault

Using secure vaults allows you to avoid exposing passwords by having them in plain text in the log4j properties file. Follow the procedure below if you want to secure the log4j properties file with a secure vault.

1. If you have not already generated the secret-conf.properties file with default values, navigate to the <API-M_HOME>/bin directory and execute the following command to generate it. This generates the secret-conf.properties file in the <API-M_HOME>/repository/conf/security directory. If you have already generated this file, proceed to Step 2.
   sh ciphertool.sh -Dconfigure
   
   Enter wso2carbon as the keystore password when the following appears in the console.
   [Please Enter Primary KeyStore Password of Carbon Server : ] 
2. Execute the following command from the <API-M_HOME>/bin directory. This generates the encrypted value for the clear text password.
   sh ciphertool.sh
   
   1. Enter wso2carbon when the following appears in the console.
      [Please Enter Primary KeyStore Password of Carbon Server : ]
   2. Enter admin as the input value when the following appears in the log. (This value is entered based on the secret-conf.properties file you generated in step 1.)
      [Enter Plain text value :]
[Please Enter value Again :]
   The following output is displayed in the console.
   
   Encryption is done Successfully
   
   The encrypted value is: 
   MpfXhKP+iJSImA/KNa+DoOXCPQAyF3JLhlFNAdG6F3naWK+N1/WEWOJkFx4kK34i1VtkywNN9SiC
MRQGTFw+nqzK5/INgcFFdoxv49lM/FJw8CyXKQ0JWdxw5QJPtrjJzvGp6Rj6xt4ysb6HdG5uNG+a
1E0lqdmzGUYQ6oejIlk=

3. Open the <API-M_HOME>/repository/conf/security/ cipher-text.properties  file and add the following entry.

   Code Block
   language js
   log4j.appender.DAS_AGENT.password=MpfXhKP+iJSImA/KNa+DoOXCPQAyF3JLhlFNAdG6F3naWK+N1/WEWOJkFx4kK34i1VtkywNN9SiC MRQGTFw+nqzK5/INgcFFdoxv49lM/FJw8CyXKQ0JWdxw5QJPtrjJzvGp6Rj6xt4ysb6HdG5uNG+a 1E0lqdmzGUYQ6oejIlk=

4. Open the <API-M_HOME>/repository/conf/log4j.properties file and configure the password as log4j.appender.DAS_AGENT.password=secretAlias:log4j.appender.DAS_AGENT.password (as shown below).

   Code Block
   language java
   log4j.appender.DAS_AGENTt=org.wso2.carbon.analytics.shared.data.agents.log4j.appender.LogEventAppender log4j.appender.DAS_AGENT.layout=org.wso2.carbon.analytics.shared.data.agents.log4j.util.TenantAwarePatternLayout log4j.appender.DAS_AGENT.columnList=%D,%S,%A,%d,%c,%p,%m,%H,%I,%Stacktrace log4j.appender.DAS_AGENT.userName=admin log4j.appender.DAS_AGENT.password=secretAlias:log4j.appender.DAS_AGENT.password log4j.appender.DAS_AGENT.url=tcp://localhost:7612 log4j.appender.DAS_AGENT.maxTolerableConsecutiveFailure=5 log4j.appender.DAS_AGENT.streamDef=loganalyzer:1.0.0

5. Start the WSO2 API Manager server by running one of the following commands from the <API-M_ANALYTICS_HOME>/bin directory. 
   
   • On Windows:  wso2server.bat --run

   • On Linux/Mac OS:  sh wso2server.sh

Enter wso2carbon when the following appears in the console.
[Enter KeyStore and Private Key Password :] 

Step 6 - Configure the databases

Configuring databases allow you to persist data relating to APIs, process them and analyze. Follow the procedure below to configure databases.

Step 7 - Configure keystores

In the SSL handshake between the API Manager and API Manager Analytics servers, the client (i.e. API Manager) needs to verify the certificate presented by the server (i.e. API Manager Analytics). For this purpose, the client stores the trusted certificate of the server in the client-truststore.jks keystore.

If you use a custom keystore in API Manager and/or API Manager Analytics, import the public key certificate of API Manager Analytics into the client-truststore.jks file of the API Manager. To export the public key from the server and import it into the client's trust store, follow the steps given in Adding CA-signed certificates to keystores in the Administration Guide.