End User Monitoring Server · inspectIT Ocelot Documentation

This server provides Enduser Monitoring data by using the OpenCensus toolkit.

Metrics

The inspectit-ocelot server offers a backend for Javascript monitoring with Boomerang. Boomerang is a Javascript metrics agent, which is able to capture arbitrary customizable metrics. By injecting the following snipped in your webpage, all measured metrics are sent to the inspectit-ocelot-eum-server:

<script src="boomerang-1.0.0.min.js"></script>
 <script src="plugins/rt.js"></script>
 <!-- any other plugins you want to include -->
 <script>
   BOOMR.init({
     beacon_url: "http://[inspectit-eum-server-url]:8080/beacon/"
   });
 </script>

Boomerang recommends to use an advanced injection, where the boomerang agent is loaded in an asynchronous way. For further information, please visit the Boomerang documentation.

If enabled, the server exposes the metrics by using the Prometheus exporter. A tutorial on how to install Prometheus can be found here.

Server Setup

Before starting the server, please build the server by cloning the repository and executing the following command or download the latest release.

$ ./gradlew build

Start the server with the following command:

$ java -jar inspectit-ocelot-eum-{version}.jar

By default, the server is starting with the port 8080. You can simply configure the port by using the Java property -Dserver.port=[port]:

$ java -Dserver.port=[port] -jar inspectit-ocelot-eum-0.0.1-SNAPSHOT.jar

Our server is delivered with a default configuration supporting the metrics t_page, t_done, rt.tstart, rt.nstart and rt.end of the Boomerang plugin RT. In order to provide a custom configuration, please set the Java property -Dspring.config.location=file:[path-to-config]:

$ java -Dserver.port=[port] -Dspring.config.location=file:[path-to-config] -jar inspectit-ocelot-eum-0.0.1-SNAPSHOT.jar

Configuration

The configuration file defines the mapping between the concrete Boomerang metric and a OpenCensus metric, as the following sample configuration file shows:

inspectit-ocelot-eum-server:
  definitions:
     page_ready_time:
      measure-type: LONG
      value-expression: "{t_page}"
      unit: ms
      views:
        '[page_ready_time/SUM]': {aggregation: SUM}
        '[page_ready_time/COUNT]': {aggregation: COUNT}

    load_time:
      measure-type: LONG
      value-expression: "{t_done}"
      beacon-requirements:
        - field: rt.quit
          requirement: NOT_EXISTS
      unit: ms
      views:
        '[load_time/SUM]': {aggregation: SUM}
        '[load_time/COUNT]': {aggregation: COUNT}

    calc_load_time:
      measure-type: LONG
      value-expression: "{rt.end} - {rt.tstart}"
      beacon-requirements:
        - field: rt.quit
          requirement: NOT_EXISTS
      unit: ms
      views:
        '[calc_load_time/SUM]': {aggregation: SUM}
        '[calc_load_time/COUNT]': {aggregation: COUNT}

    start_timestamp:
      measure-type: LONG
      value-expression: "{rt.tstart}"
      unit: ms

    navigation_start_timestamp:
      measure-type: LONG
      value-expression: "{rt.nstart}"
      unit: ms

    end_timestamp:
      measure-type: LONG
      value-expression: "{rt.end}"
      unit: ms
      views:
        end_timestamp:
          aggregation: LAST_VALUE
          tags: {APPLICATION: true}

  tags:
    extra:
      APPLICATION: my-application
    beacon:
      URL: u
      OS: ua.plt
    define-as-global:
      - URL
      - OS
      - COUNTRY_CODE

  exporters:
    metrics:
      prometheus:
        enabled: true
        host: localhost
        port: 8888

Metrics Definition

A metric is defined the same way as in the inspectIT Ocelot Java agent. Please see the section Metrics / Custom Metrics for detailed information.

In contrast to the agent's metric definition, the EUM server's metric definition contains additional fields. These additional fields are the following:

Attributes	Note
`value-expression`	An expression used to calculate the measure's value from a beacon.
`beacon-requirements`	Requirements which have to be fulfilled by Beacons. Beacons which do not match all requirements will be ignored by this metric definition.

Value Expressions

The value-expression field can be used to specify a field which value is used for the specified metrics. In order to reference a field, the following pattern is used: {FIELD_KEY}. For example, a valid expression, used to extract the value of a field t_load, would be {t_load}.

Note that a beacon has to contain all fields referenced by the expression in order to be evaluated and recorded.

Value expressions also support operations for basic arithmetic operations. Thus, to calculate a difference of two beacon fields, the following expression can be used:

  ...
    my-metric:
      ...
      value-expression: "{field.a} - {field.b}"
      ...

Value expression are supporting the following operations:

addition
subtraction
multiplication
division
unary plus/minus
parentheses

Using the operations above, complex calculations can be done, for example:

  ...
    my-metric:
      ...
      value-expression: "- {field.c} * ({field.a} - {field.b}) / {field.a}"
      ...

Beacon Requirements

The beacon-requirements field can be used to specify requirements which have to be fulfilled by the beacons in order to be evaluated by a certain metric. If any requirement does not fit a beacon, the beacon is ignored by the metric.

Beacon requirements consist of two attributes field and requirement. field specified the beacon's field which is validated using the requirement type specified in NOT_EXISTS.

  ...
    my-metric:
      ...
      beacon-requirements:
        - field: rt.quit
          requirement: NOT_EXISTS

The following requirement types are currently be supported:

Type	Note
`EXISTS`	The targeted field must exist.
`NOT_EXISTS`	The targeted field must not exist.

Tags Definition

We distinguish between to different types of tags:

Attributes	Note
`extra`	Extra tags define tags, which are manually set in the configuration and can be considered as constants.
`beacon`	Beacon tags define tags, whose value is resolved by an incoming beacon entry.

For example, the following configuration specifies the two tags APP and URL. The tag APP will always be resolved to the value my-application, where the tag URL will be resolved to the value of the field u of a received beacon.

inspectit:
  tags:
    extra:
      APP: my-application
    beacon:
      URL: u

Default Tags

The EUM server provides a set of default tags which don't have to be specified and always exist. Currently, the following default tags exist:

Tag	Description
`COUNTRY_CODE`	Contains the geolocation of the beacon's origin. It is resolved by using the client IP and the GeoLite2 database. If the IP cannot be resolved, the tag value will be empty.

Global Tags

Tags will not be attached to metrics unless a metric explicitly defines to use a certain tag.

In order to simplify the configuration, it is possilbe to define tags which are always attached to metrics, even a metric does not explicitly specifies it. This can be achieved by adding a tag's name to the define-as-global property. Each tag which is listed under this property will be added to each registered metric.

For example, the following configuration causes that each metric will be enriched by a tag called COUNTRY_CODE.

inspectit:
  tags:
    define-as-global:
      - COUNTRY_CODE

Exporters

By now, the prometheus exporter is available. If enabled is set to true, the exporter is exposes the metrics under the following HTTP endpoint: http://[host]:[port]/metrics