/monitor-analytics web application

This installation step is only necessary if interaction data is to be collected within map.apps on the client side.

To install the webapp of service.monitor deploy the given WAR file from monitor-analytics.war to the Servlet Container that shall be used.

To change the default configuration values,

  1. copy the file \monitor-analytics\WEB-INF\classes\application.properties to [data.directory.location]/application.properties,

  2. edit the file \monitor-analytics\WEB-INF\classes\custom-application.properties and point the value of key data.directory.location to the directory where you copied the application.properties file

  3. change the necessary values

  4. restart the Servlet Container or reload the context.

Configuration

Logstash - Send interation data

If the Logstash service is installed on a different host than localhost, configure it in the application.properties and connect it to the Logstash service.

application.properties
analytics.gelf.server=myserver.example.com
analytics.gelf.port=12201

It is also possible to change the port, on which outgoing log messages are send. If you change the port in the application.properties file, change the listening port in the Logstash configuration at /resources/analytics/elasticsearch/logstash/pipelines/ct-analytics/logstash-analytics-100-input.conf to open the port to receive messages.

After any configuration changes, restart the related component.

Restrict log endpoint access

It may be desired to restrict access to the /usage/log endpoint for persisting data. This can be done by setting up a list of allowed host names. Those host names will be tested against the HTTP Header value Referer. The referrer value typically contains the url of the web page sending the request.

default-application.properties
analytics.usagelog.referers=*

The default setting allows for sending /usage/log requests from anywhere.

Example

With the following setting, the restrictions below apply.

application.properties
analytics.usagelog.referers=example.com,https://www.example.net

The endpoint allows requests from pages that have, for example, the following HTTP header values:

  • http://example.com/application/index.html

  • https://example.com/webapp/somePage.jsp

  • https://www.example.net/client.aspx

The endpoint would not allow or store requests with such referrer values:

  • http://www.example.net/client.aspx because the setting explicitly points to https protocol.

  • http://www.example.org/some-page.html because the URL is not listed in the property.

Elasticsearch - Query collected data

Changes to the application.properties are necessary, for example, if Elasticsearch runs on another host than http://localhost:9200. In this case, the service URL has to be configured to connect the webapp with Elasticsearch. Also, if Elastic requires username and password for access, credentials can be configured here.

application.properties
analytics.elasticsearch.service.url=http://myserver:9200/analytics-*/_search
analytics.elasticsearch.service.user=<user>
analytics.elasticsearch.service.pwd=<password>

service.monitor Usage Log webapp provides a security layer to secure queries against the Elasticsearch indices. To protect the loggend data against unwanted access, it is HIGHLY RECOMMENDED to change the properties.

  • security.user.admin.name

  • security.user.admin.pw

Use a hash algorithm to encrypt it by setting the property security.user.pwenc to one of MD5, SHA-1, SHA-256, SHA-384 or SHA-512.

Note, that security.user.admin.pw then stores the encrypted password, e.g

security.user.pwenc=SHA-256
security.user.admin.pw=b18474123c790f30c300b6bb9ee146a4959b6bcd5eef20244b925d69ea996690

Overview of all default values

See \monitor-analytics\WEB-INF\classes\default-application.properties for an overview of the default values of the used properties.

The default value for [data.directory.location] is $\{user.home\}/.monitor.

In case the Tomcat server is operated as a windows service this folder corresponds to the user that executes the Tomcat service. If no such user is configured the Tomcat server runs under the system user’s account (not recommended!). In this case the .monitor folder is to be found under path C:\Windows\System32\config\systemprofile\.monitor.

If a custom folder should be used to store Analytics data, define this path in \monitor-analytics\WEB-INF\classes\custom-application.properties inside the webapp on the Tomcat.
Linux

When installing service.monitor on Linux systems, you have to change the following parameter in configuration file \monitor-analytics\WEB-INF\classes\custom-application.properties:

data.directory.location=$\{user.home\}/.monitor

to e.g.

data.directory.location=/opt/data/.monitor