Analytics Installation and Configuration Guide

Installation of Stambia Analytics

Prerequisite

Stambia Analytics needs the following requirements:

• a J2EE Web Application Server such as:
  • Apache Tomcat 7
  • JBoss 6 or higher
• a Java virtual machine 1.8
• a folder to store parameters and data

Stambia Analytics can run on any operating systems that meet these requirements.

Installation

Stambia Analytics consists of a .war file (or .ear file) that shall be deployed on the application server.

Before proceeding:

1. Ensure that the application server uses java virtual machine 1.8 or higher.
2. Define a STAMBIA_WEBAPP_HOME environment variable. This will be the folder in which Stambia Analytics will store parameters and repositories information.

Warning: for the STAMBIA_WEBAPP_HOME variable, prefer a folder outside the application server. Don’t forget to set up backup procedure on this folder.

Tip: in the name of the STAMBIA_WEBAPP_HOME variable, you can add the IP Port like STAMBIA_WEBAPP_HOME_8081 to specify another installation of Stambia Analytics. This is useful when there are two installations of Stambia Analytics on the same server.

Right management

The Stambia Analytics authentication relies on the application server authentication.
You have to declare the users and their roles on the application server.

Each user can have several roles in the following list:

• analyticsConnect: connection right (mandatory)
• analyticsAdmin: super administrator rights. This role overpasses the other roles, that means that an analyticsAdmin role gives all the rights.
• analyticsParameterConsult: the user can consult the parameters
• analyticsParameterAdmin: the user can modify the parameters
• analyticsSessionConsult: the user can consult the sessions
• analyticsSessionAdmin: the user can administer the sessions (creation of session views)
• analyticsSessionAction: the user can manage the sessions (start, stop, restart, delete)
• analyticsRuntimeConsult: the user can consult the Runtimes
• analyticsRuntimeAdmin: the user can administer the Runtimes
• analyticsRepositoryConsult: the user can consult the repositories
• analyticsRepositoryAdmin: the user can administer the repositories

The rights management in Stambia Analytics will rely on these roles.

Tomcat detail

Setup

To setup Stambia Analytics on tomcat:

1. Declare the STAMBIA_WEBAPP_HOME environment variable in the the profile of the user who will launch tomcat.
2. Add the users and roles in Tomcat
3. start tomcat
4. copy the .war file provided by Stambia in the Tomcat folder "webapps". Tomcat will auto-deploy the application.

Warning: Tomcat versions higher than tomcat 8 are not supported.

Managing users and roles in Tomcat

In order to add your users and roles, you have to modify the "tomcat-users.xml" file.

Adding a user can be done with the following block:

<tomcat-users>
<user name="youruser" password="yourpassword" roles="admin-gui, manager-gui, analyticsAdmin, analyticsConnect" />
</tomcat-users>

In this example, the user has the two Stambia Analytics roles "analyticsAdmin" and "analyticsConnect", but also the two Tomcat roles «admin-gui» and «manager-gui».

JBoss detail

JBoss 7

Setup

To setup Stambia Analytics on JBoss 7:

1. Declare the STAMBIA_WEBAPP_HOME environment variable in the profile of the user who will launch JBoss.
2. Add the users and roles in JBoss (see below)
3. start JBoss
4. copy the .war file provided by Stambia in the deployments JBoss folder. JBoss will auto-deploy the application.

Managing users and roles in JBoss 7

• Add the following text to the standalone.xml or domain.xml file according to your installation. Contact your JBoss administrator for this part:

<security-domain name="analyticsRealm">
        <authentication>
           <login-module code="UsersRoles" flag="required">
              <module-option name="usersProperties" value="${jboss.server.config.dir}/analytics-users.properties"/>
              <module-option name="rolesProperties" value="${jboss.server.config.dir}/analytics-roles.properties"/>
           </login-module>
        </authentication>
    </security-domain>

• Add the two files analytics-users.properties and analytics-roles.properties in the domain or standalone folder according to your installation. Contact your JBoss administrator to do this part:

• In the analytics-users.properties file add a user and a password. Here is an example:

user=password

• In the analytics-roles.properties file add the roles. Here is an example:

user=analyticsConnect,analyticsSessionConsult

JBoss 6

Setup

To setup Stambia Analytics on JBoss 6:

1. Declare the STAMBIA_WEBAPP_HOME environment variable in the profile of the user who will launch JBoss.
2. Add the users and roles in JBoss (see below)
3. start JBoss
4. copy the .war file provided by Stambia in the deployments JBoss folder. JBoss will auto-deploy the application.

Managing users and roles in JBoss 6

• Add the following text to the login-config.xml file in the server\default\conf\ folder, according to your installation. Contact your JBoss administrator to do this part:

<application-policy name="analyticsRealm">
      <authentication>
		  <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"flag="required">
             <module-option name="usersProperties">props/analytics-users.properties</module-option>
				 <module-option name="rolesProperties">props/analytics-roles.properties</module-option>
				 <module-option name="unauthenticatedIdentity">anonymous</module-option>
         </login-module>
       </authentication>
   </application-policy>

• Add the two files analytics-users.properties and analytics-roles.properties in the server\default\conf\prop\ folder according to your installation. Contact your JBoss administrator to do this part:

• In the analytics-users.properties file add a user and a password. Here is an example:

user=password

• In the analytics-roles.properties file add the roles. Here is an example:

user=analyticsConnect,analyticsSessionConsult

Stambia Analytics Configuration

The Parameters of Stambia Analytics can be set up in the Windows->Parameters menu.
This menu will open the Parameters window in which Runtimes, Log Databases and Profiles can be defined.

Defining Runtimes

In the Runtime tab you can define connections to one or more Runtimes.

1. Click on the Add button
2. Specify a Name, the Host and the Port on which to connect
3. Optionally set a User and Password if the Runtime is secured
4. Test the connection through the Test button

If you check the Show in logs selection box, the Runtime name will appear in the selection combo box under the main menu.

If you check the Hide in navigator box, the Runtime will not appear in the selection Navigator view.

If you check the Disable log database proxy box, Stambia Analytics will not retrieve the session information from the Runtime.

When all the Configurations are done and saved, don’t forget to select the Runtime in the combo box under the main menu if you want to use it.

Note: To access to a Runtime, don’t forget to open the needed IP ports. By default 42000.

Important:
# If you configure Stambia Analytics to connect to the log databases using Datasources you should check the Disable log database proxy box on each Runtime.
# If your Runtime is configured to use a different log database than the default one: Add the corresponding JDBC drivers in:
<STAMBIA_WEBAPP_HOME>/jdbc folder

Defining log databases

In the Log databases tab you can define connections to one or more logging databases.

1. Click on the Add button
2. Specify the Name
3. Define the Connection:
   1. Select Standard if you want Stambia Analytics to open its own JDBC Connection to the database and provide:
      1. the JDBC Driver class
      2. the connection URL
      3. the User
      4. the Password
   2. Select Datasource if you want Stambia Analytics to use a Datasource defined in your Application Server and provide the Datasource Name
4. Specify the schema name, and if needed, the tables prefix
5. Test the connection through the Test button

If you select the check box Show in logs selection, the database name will appear in the selection combo box under the main menu.

Note: To access to a database, don’t forget to open the needed IP ports.

Tip: You can automatically fill the database information by connecting to a Runtime that knows the connection information. To do this, click on the Autoinit button and specify a Runtime host or IP, and a Runtime port.

Important: Don’t forget to add the JDBC drivers corresponding to the log databases in:
<STAMBIA_WEBAPP_HOME>/jdbc folder

Defining Profiles

Profiles are useful to gather Sessions from Runtimes and log databases.

For example, a «Production» profile can be created to administer all Runtimes and logging databases dealing with production executions.

You can define a Profile in the Profiles tab.

1. Click on the Add button
2. Give a name
3. Click on the button in the right of the Log providers text area. A new window will appear.
4. In this window, add from left to right the databases and the Runtimes you want to add to the profile.

The created profile will be automatically usable in the selection combo box under the main menu.

You can check the Default Profile box if you want to use the Profile as default for users that doesn’t have any profile selected.

Tip: All Runtimes and All Log Databases are virtual providers allowing to dynamically gather data from all configured Runtimes or Log Databases.

Defining statistics

Statistics can be added or removed in the Statistics tab.

Every numeric variable can become a statistic. These statistics will appear in the statistic view.

Defining preferences

In the Preferences tab, you can manage and configure Analytics behaviors.
The following properties are available: