/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

Elastic Ingest Pipeline (recommended)

The Usagelog web application uses the Elastic Ingest Pipeline to process client-side interaction data from map.apps and forward it to Elasticsearch. The following application.properties configuration activates the Elastic Ingest Pipeline:

application.properties
analytics.enabled=true
analytics.messengerType=elastic
analytics.elastic.url=https://elasticsearch.example.com
analytics.elastic.username=elastic
analytics.elastic.password=changeme

Logstash (discontinued)

The Logstash pipeline has been discontinued and is no longer being developed. Use the Elastic Ingest Pipeline instead. Logstash is a standalone server component that receives client-side interaction data from map.apps, processes it and forwards it to Elasticsearch. If the Logstash service is on a host other than localhost, configure it via the application.properties.

application.properties
analytics.enabled=true
analytics.messengerType=gelf
analytics.gelf.server=server.example.com
analytics.gelf.port=12201

Translated with DeepL.com (free version)

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.

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