Localtab |
---|
active | true |
---|
id | Quick-Setup |
---|
title | Quick Setup |
---|
| Info |
---|
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. |
Download WSO2 API Manager and WSO2 API-M Analytics. Expand |
---|
| Tip |
---|
| - Go to https://wso2.com/api-management/previous-releases/
- Select Version 2.5.0 from the drop-down list.
 - Enter your email address.
 - Click on one of the installers based on your OS and install WSO2 API Manager.
- Click Download to download WSO2 API-M Analytics and extract the ZIP file.
|
|
- 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.
- Ensure that you have met the Installation Prerequisites.
- Go to the installation instructions relevant to your operating system:
To enable Analytics, open the <API-M_HOME>/repository/conf/api-manager.xml file and set the Enabled property under Analytics to true as shown below. Save this change. Code Block |
---|
| <Enabled>true</Enabled> |
Note |
---|
If you are working on a distributed (clustered) setup of API Manager, do the configurations instructed to be done in API Manager in Publisher, Store and Gateway nodes. |
- Share the
WSO2AM_STATS_DB datasource between WSO2 API-M and WSO2 API-M Analytics as follows.Open the <API-M_HOME>/repository/conf/datasources/master-datasources.xml file and make sure that a configuration for the WSO2AM_STATS_DB datasource is included with your datasource configurations. The default configuration which is already available in master-datasources.xml file is as follows. It is configured for the in-built h2 database by default. You can change the datasource according to the database you use referring to change statistics datasource. Code Block |
---|
| <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:h2:../tmpStatDB/WSO2AM_STATS_DB;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000;AUTO_SERVER=TRUE</url>
<username>wso2carbon</username>
<password>wso2carbon</password>
<defaultAutoCommit>false</defaultAutoCommit>
<driverClassName>org.h2.Driver</driverClassName>
<maxActive>50</maxActive>
<maxWait>60000</maxWait>
<testOnBorrow>true</testOnBorrow>
<validationQuery>SELECT 1</validationQuery>
<validationInterval>30000</validationInterval>
</configuration>
</definition>
</datasource> |
Note |
---|
If you are changing the datasource to a different database like MySQL, note that you do not need to run the database scripts against the created databases as the tables for the datasources are created at runtime. |
- Open the
<API-M_ANALYTICS_HOME>/repository/conf/datasources/stats-datasources.xml file and make sure that the same configuration forWSO2AM_STATS_DB in the <API-M_HOME>/repository/conf/datasources/master-datasources.xml file (mentioned in the previous sub step) is added in it.
Warning |
---|
The WSO2 Log Analyzer is deprecated (to be removed in a future release) and is disabled by default. To enable the WSO2 Log Analyzer, - Unzip the portal.zip file to the
<API-M_HOME>/repository/deployment/server/jaggeryapps folder. - Add the shinding.war file to the
<API-M_HOME>/repository/deployment/server/webapps folder. - Set the
enableLogAnalyzer property to true in the <API-M_HOME>/repository/deployment/server/jaggeryapps/admin/site/conf/site.json file.
|
Note |
---|
This configuration is required only if you need to analyze WSO2 API-M logs using the Log Analyzer. When you are disabling analytics, make sure to remove this configuration to avoid errors. If you are working on a distributed (clustered) setup of API Manager, follow these steps to configure the Log Analyzer in the Gateway node. |
Open the <API-M_HOME>/repository/conf/log4j.properties file. Add the DAS_AGENT to the end of the root logger as shown below. Code Block |
---|
log4j.rootLogger=<other loggers>, DAS_AGENT |
- Start the WSO2 API-M Analytics server, and then start the API Manager server. To start a WSO2 product server, navigate to the
<PRODUCT_HOME>/bin directory in your console and run one of the following scripts as relevant.
- On Windows:
wso2server.bat --run On Linux/Mac OS: sh wso2server.sh
Info |
---|
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. Code Block |
---|
INFO {org.wso2.carbon.databridge.core.DataBridge} - user admin connected |
|
You can now start using the API Manager for its usual operations and the required Analytics functionality is enabled. Info |
---|
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. - Open the
<API-M_ANALYTICS_HOME>/repository/components/features/org.wso2.carbon.analytics.spark.server_VERSION/spark-jdbc-config.xml file. Update the value for the <indexCreateQuery> element of the MySQL database as shown below. Code Block |
---|
| <database name="Microsoft SQL Server">
<indexCreateQuery>CREATE INDEX {{TABLE_NAME}}_INDEX ON {{TABLE_NAME}} ({{INDEX_COLUMNS}})</indexCreateQuery>
</database> |
|
|
Localtab |
---|
id | StandardSetup |
---|
title | Standard Setup |
---|
| Follow the instructions below to set up API-M Analytics for a production environment. Table of Content Zone |
---|
| Step 1 - Download WSO2 API-M and WSO2 API-M Analytics Expand |
---|
| Tip |
---|
| - Go to https://wso2.com/api-management/previous-releases/
- Select Version 2.5.0 from the drop-down list.
 - Enter your email address.
 - Click on one of the installers based on your OS and install WSO2 API Manager.
- Click Download to download WSO2 API-M Analytics and extract the ZIP file.
|
|
Step 2 - Install WSO2 API-M AnalyticsTake 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. - Ensure that you have met the Installation Prerequisites.
- Go to the installation instructions relevant to your operating system:
Follow the instructions below to do the required configurations for WSO2 API-M to publish statistics in the WSO2 API-M Analytics server. Note |
---|
If you are working on a distributed (clustered) setup of API Manager, do the configurations instructed to be done in API Manager in Publisher, Store and Gateway nodes. |
- Open the
<API-M_HOME>/repository/conf/api-manager.xml file. - Under the
<Analytics> sub element, set the Enabled parameter to true . 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. | - Save the changes.
Info |
---|
This configuration is required only if you want to analyze WSO2 API-M logs using the Log Analyzer. If your setup already has a log monitoring tool like splunk, kibana, logstash etc, we do not recommend you to configure log analyser. If you are working on a distributed (clustered) setup of API Manager, follow these steps below in Gateway node. |
Follow the steps below to configure the Log Analyzer. 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 |
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 |
---|
| <DASRestApiURL>https://analytics.wso2.com:9444</DASRestApiURL> |
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 |
---|
| <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> |
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 vaultUsing 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. - 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 : ] - Execute the following command from the
<API-M_HOME>/bin directory. This generates the encrypted value for the clear text password. sh ciphertool.sh
- Enter wso2carbon when the following appears in the console.
[Please Enter Primary KeyStore Password of Carbon Server : ] - 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= Open the <API-M_HOME>/repository/conf/security/ cipher-text.properties file and add the following entry. Code Block |
---|
| log4j.appender.DAS_AGENT.password=MpfXhKP+iJSImA/KNa+DoOXCPQAyF3JLhlFNAdG6F3naWK+N1/WEWOJkFx4kK34i1VtkywNN9SiC
MRQGTFw+nqzK5/INgcFFdoxv49lM/FJw8CyXKQ0JWdxw5QJPtrjJzvGp6Rj6xt4ysb6HdG5uNG+a
1E0lqdmzGUYQ6oejIlk= |
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 |
---|
| 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 |
- Start the WSO2 API Manager server by running one of the following commands from the
<API-M_ANALYTICS_HOME>/bin directory.
Enter wso2carbon when the following appears in the console. [Enter KeyStore and Private Key Password :] Info |
---|
If you want to start the server as a background process, carry out the following steps before starting the server. Create a file named password-tmp.txt in the <API-M_HOME> directory. Add wso2carbon (the primary keystore password) to this file and save. Tip |
---|
By default, the password provider assumes that both the private key and the keystore passwords are the same. If you want them to be different, the private key password should be entered in the second line of the file. |
The keystore password is picked from the password-tmp.txt file. This file is automatically deleted from the file system when you start the server. Make sure to add this temporary file back whenever you start the server as a background process. Tip |
---|
If you name the password file password-persist.txt instead of password-tmp.txt , then the file is not deleted once the server is started. Therefore, it is not required to provide the password in subsequent startups. |
|
Configuring databases allow you to persist data relating to APIs, process them and analyze. Follow the procedure below to configure databases. Excerpt |
---|
Info |
---|
The following is a list of database versions that are compatible with WSO2 API-M Analytics. - Postgres 9.5 and later
- MySQL 5.6
- MySQL 5.7
- Oracle 12c
- MS SQL Server 2012
- DB2
|
- Open the
<API-M_ANALYTICS_HOME>/repository/conf/datasources/analytics-datasources.xml file. Note that two datasources named as WSO2_ANALYTICS_EVENT_STORE_DB and WSO2_ANALYTICS_PROCESSED_DATA_STORE_DB are configured by default to point to the H2 databases. Create two database schemas in your database server (MySQL, Oracle, etc) for the two datasources, and change the configurations of those datasources to point to the relevant schemas. A sample configuration is given below. Info |
---|
The database user you provide here requires permissions to create tables. |
Note |
---|
Note that you do not need to run the database scripts against the created databases as the tables for the datasources are created at runtime. |
Code Block |
---|
| <datasource>
<name>WSO2_ANALYTICS_EVENT_STORE_DB</name>
<description>The datasource used for analytics record store</description>
<definition type="RDBMS">
<configuration>
<url>jdbc:mysql://localhost:3306/stats_200?autoReconnect=true&relaxAutoCommit=true</url>
<username>root</username>
<password>root</password>
<driverClassName>com.mysql.jdbc.Driver</driverClassName>
<maxActive>50</maxActive>
<maxWait>60000</maxWait>
<testOnBorrow>true</testOnBorrow>
<validationQuery>SELECT 1</validationQuery>
<validationInterval>30000</validationInterval>
<defaultAutoCommit>false</defaultAutoCommit>
</configuration>
</definition>
</datasource> |
Info |
---|
If you are using Oracle, its recommended to increase the DB block size as described in http://www.oratable.com/ora-01450-maximum-key-length-exceeded/, to avoid the error 'ORA-01450: maximum key length (6398) exceeded'. If you are using DB2, run this script before you start the WSO2 API-M Analytics server. - If you are using MySQL 5.7, open
<API-M_ANALYTICS_HOME>/repository/conf/analytics/spark/spark-jdbc-config.xml and configure the stringType property under the typeMapping element as follows. <stringType>VARCHAR(100)</stringType>
|
Tip |
---|
If you are using MSSQL, add the SendStringParametersAsUnicode property to the database connection URL in the data source configuration in the <API-M_ANALYTICS_HOME>/repository/conf/datasources/analytics-datasources.xml file as shown below to avoid deadlock issues that are caused when the same table row is updated in two or more sessions at the same time. <url>SQLSERVER_JDBC_URL;SendStringParametersAsUnicode=false</url>
|
- Share the
WSO2AM_STATS_DB datasource between WSO2 API-M and WSO2 API-M Analytics as follows.Open the <API-M_HOME>/repository/conf/datasources/master-datasources.xml file and make sure that a configuration for the WSO2AM_STATS_DB datasource is included. The default configuration is as follows. Code Block |
---|
| <datasource>
<name>WSO2AM_STATS_DB</name>
<description>The datasource used for setting statistics to API Manager</description>
<jndiConfig>
<name>jdbc/WSO2AM_STATS_DB</name>
</jndiConfig>
<definition type="RDBMS">
<configuration>
<url>jdbc:mysql://localhost:3306/WSO2AM_STATS_DB?autoReconnect=true&relaxAutoCommit=true</url>
<username>root</username>
<password>root</password>
<driverClassName>com.mysql.jdbc.Driver</driverClassName>
<maxActive>50</maxActive>
<maxWait>60000</maxWait>
<testOnBorrow>true</testOnBorrow>
<validationQuery>SELECT 1</validationQuery>
<validationInterval>30000</validationInterval>
<defaultAutoCommit>false</defaultAutoCommit>
</configuration>
</definition>
</datasource> |
Note |
---|
you need to enable analytics in publisher, store and gateway nodes. However, you need to add this datasource configuration in gateway nodes. Following table provides more information on Analytics usage of API Manager components in a distributed environment. Component | Enable statistics | Events Published | Read statsDB |
---|
Gateway_Manager | YES only if accept request | YES only if accept request | NO | Gateway_worker | YES | YES | NO | Key Manager | NO | NO | NO | Publisher | YES | NO | YES | Store | YES | YES | YES | Traffic Manager | NO | NO | NO | You do not need to enable analytics in Key Manager and Traffic Manager nodes as those components do not read or publish statistics. Though gateway nodes publish events, they are not reading statistics database. Therefore, you are not required to add the WSO2AM_STATS_DB datasource configuration in gateway nodes. Publisher node read statistics but not publishing events. Therefore, you can disable event publisher initialization at startup in publisher by setting <SkipEventReceiverConnection> value to true in <PUBLISHER_HOME>/repository/conf/api-manager.xml.API Store node reads statistics and also publish events. Therefore, we need to keep the statsource configuration for statsDB in Store node as well. |
- Open the
<API-M_ANALYTICS_HOME>/repository/conf/datasources/stats-datasources.xml file and make sure that the same configuration in the <API-M_HOME>/repository/conf/datasources/master-datasources.xml file (mentioned in the previous sub step) is added in it.
Create a schema in your database server similar to the WSO2AM_STATS_DB datasource. Make sure that this datasource points to the relevant schema. Info |
---|
The database user you provide here requires permissions to create tables. |
- Download and copy the relevant database driver JAR file to the
<API-M_ANALYTICS_HOME>/repository/components/lib directory. - Start the WSO2 API-M Analytics server.
Info |
---|
| 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. - Open the
<API-M_ANALYTICS_HOME>/repository/components/features/org.wso2.carbon.analytics.spark.server_VERSION/spark-jdbc-config.xml file. Update the value for the <indexCreateQuery> element of the MySQL database as shown below. Code Block |
---|
| <database name="Microsoft SQL Server">
<indexCreateQuery>CREATE INDEX {{TABLE_NAME}}_INDEX ON {{TABLE_NAME}} ({{INDEX_COLUMNS}})</indexCreateQuery>
</database> |
Restart the server for the above changes to take effect.
|
|
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. |
|
|