Prerequisites to Publish Statistics¶
The following prerequisites should be fulfilled in order to set up the Analytics Dashboard to publish the data processed by WSO2 IS.
Step 01: Download WSO2 IS Analytics¶
The binary distribution contains the binary files for both MS Windows and Linux-based operating systems.
Follow the steps below to download WSO2 IS Analytics binary distribution.
- Go to the WSO2 IS Analytics download page.
-
Download the WSO2 Identity Server Analytics 5.8.0 pack.
Note
WSO2 Identity Server 5.11.0 analytics capabilities are fully compatible with WSO2 IS Analytics 5.8.0. Please note that WSO2 IS Analytics 5.8.0 is the recommended version for WSO2 Identity Server 5.11.0.
-
To download the pack with updates, click SIGN-IN & DOWNLOAD .
-
To download the pack without updates, click DOWNLOAD.
Note
The installation prerequisites for WSO2 IS Analytics is as same as for WSO2 Stream Processor (WSO2 SP). Therefore, for detailed information about the supporting applications you need to install, see WSO2 SP Installation Guide.
-
Step 02: Enable Analytics in WSO2 IS¶
Follow the steps below to enable event publishing in WSO2 IS.
-
Open the
deployment.toml
file in the<IS_HOME>/repository/conf/
directory. -
Enable the following event handlers by adding the following configurations to the same
deployment.toml
file.Event Handler org.wso2.carbon.identity.data.publisher.authentication.analytics.login.AnalyticsLoginDataPublishHandler
Purpose Enable this handler only when you want to analyze login statistics in WSO2 IS. For more information, see Analyzing Statistics for Local Login Attempts .
Configuration Event Handler org.wso2.carbon.identity.data.publisher.authentication.analytics.session.AnalyticsSessionDataPublishHandler
Purpose Enable this handler only when you want to analyze session statistics in WSO2 IS Analytics. For more information, see Analyzing Statistics for Sessions .
Configuration Enable analytics for Password grant logins Optionally, you can enable analytics for password grant type logins. Add the following configuration to the deployment.toml file to enable this feature.
[analytics] publish_password_grant_logins=true
Step 03: Configure Event Publishers¶
In a fresh WSO2 IS pack, you can view all the event publishers related
to WSO2 IS Analytics in the
<IS_HOME>/repository/deployment/server/eventpublishers
directory.
Tip
The required configurations described below are available by default. Thus, follow this section to understand the analytics-related configurations used in the process and do any modifications if required.
WSO2 Analytics presents the login and/or session data published by WSO2 IS. To receive these data by Analytics, you need to configure the event publishers.
Follow the steps below to configure the event publishers:
-
Configure the login analytics and session analytics using the following files. Update the properties based on the description given in the below table.
- Login analytics :
<IS_HOME>/repository/deployment/server/eventpublishers/IsAnalytics-Publisher-wso2event-AuthenticationData.xml
-
Session analytics :
<IS_HOME>/repository/deployment/server/eventpublishers/IsAnalytics-Publisher-wso2event-SessionData.xml
The configurations for login analytics and session analytics are almost the same except for event streams. This is because the format in which the events are captured for the two analytics are different. For more information event streams, see WSO2 SP Quick Start Guide.
Warning
The event streams that are specified for publishers should not be modified as that would cause errors in the default configuration.
The common properties that can be configured for event publishers in the files mentioned above are as follows.
Adapter Property Description Configuration File Example Receiver URL This captures the target receiver
URL
to which the WSO2 IS-related information are sent as events.Format:
- When specifying the thrift port, the default port offsets done for WSO2 IS Analytics should be considered, e.g., if WSO2 IS Analytics was started with a port offset of
1
, the thrift port should be7612
instead of7611
. For high availability scenarios, multiple analytics receivers can be defined by configuring multiple comma-separated URLs with the format.
- As per the above configuration, events are published to all the defined receivers. For other ways of configuring the receiver URLs, see Collecting Events .
receiverURL
For a single analytics receiver:
tcp://localhost:7612
For multiple analytics reievers:
- This captures the
URL
of the authenticator. Format:
- When specifying the SSL port, the default port offsets done for WSO2 IS should be considered, e.g., if WSO2 IS was started with a port offset of
1
, the SSL port should be7712
instead of7711
. This parameter is not included in the
<IS_HOME>repository/deployment/server/eventpublishers/IsAnalytics-Publisher-wso2event-AuthenticationData.xml
file by default. When it is not included, the authenticator URL is derived by adding 100 to the thrift port.
authenticatorURL
ssl://localhost:7712
User Name
This captures the user name of the listener.
If the
EnableEmailUserName
property in the<IS_HOME>/repository/conf/carbon.xml
is set to true, define the user name with the tenant domain.
Example:For more information, see Using Email Address as the User Name .
username
wso2event-user
Password This captures the
password
of the listener.
password
wso2event-password
Protocol This captures the
communication protocol
that is used to publish events.
protocol
thrift/binary
Publishing Mode This captures the
event publishing mode
.- Non-blocking : This refers to asynchronouns publishing.
- Blocking : This refers to sychronous publishing.
publishingMode
non-blocking/blocking
Publishing Timeout This captures the
timeout
for the non-blocking publishing mode that is denoted as a positive integer.
publishTimeout
0
- Login analytics :
Step 04: Change the Admin Password and Add Key-store certificates¶
Similar to Step 03, change the admin password and import keystore certificates.
-
Navigate to the
<IS_HOME>/repository/deployment/server/eventpublishers/IsAnalytics-Publisher-wso2event-AuthenticationData.xml
configuration file and update the admin password.Note
In a fresh WSO2 IS pack the password will appear in plain text. Once you restart the pack the password gets automatically encrypted.
Example:
<eventPublisher name="IsAnalytics-Publisher-wso2event-AuthenticationData" statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventpublisher"> <from streamName="org.wso2.is.analytics.stream.OverallAuthentication" version="1.0.0"/> <mapping customMapping="disable" type="wso2event"/> <to eventAdapterType="wso2event"> <property name="username">admin</property> <property name="protocol">thrift</property> <property name="publishingMode">non-blocking</property> <property name="publishTimeout">0</property> <property name="receiverURL">tcp://localhost:7612</property> <property encrypted="true" name="password">kuv2MubUUveMyv6GeHrXr9il59ajJIqUI4eoYHcgGKf/BBFOWn96NTjJQI+wYbWjKW6r79S7L7ZzgYeWx7DlGbff5X3pBN2Gh9yV0BHP1E93QtFqR7uTWi141Tr7V7ZwScwNqJbiNoV+vyLbsqKJE7T3nP8Ih9Y6omygbcLcHzg</property> </to> </eventPublisher>
If you want to change the admin password, include the new password in plain text in WSO2 IS event publishers.
-
Import the
public certificate
of each keystore to theclient-truststore.jks
of the WSO2 IS using the following command.keytool -import -alias <alias> -file <file_name> -keystore client-truststore.jks -storepass wso2carbon
Step 05: Run the Servers¶
Follow the steps below to run WSO2 IS and WSO2 IS Analytics.
- Run or restart WSO2 IS. For detailed instructions, see Running the Product.
-
Run the WSO2 IS Analytics profiles.
Note
- If you are using geolocation-based statistics, do the necessary configurations prior to the restart. For more information, see Enabling Geolocation Based Statistics.
- If you are running WSO2 IS Analytics in a clustered setup, see WSO2 Stream Processor Deployment Guide. The viable cluster types for WSO2 IS Analytics are Minimum High Availability Deployment (recommended) and Fully Distributed Deployment. For both types, database system state persistence need to be enabled and configured. If required, the dashboard profile can be hosted outside the cluster with the state persistence database of the cluster configured as a datasource.
-
Run the Worker node of WSO2 IS Analytics. For detailed instructions, see WSO2 SP - Starting Worker Node .
-
Run the Dashboard node of WSO2 IS Analytics. For detailed instructions, see WSO2 SP - Starting a Dashboard Node .