This server provides Enduser Monitoring data by using the OpenCensus toolkit.
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.
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
The configuration file defines the mapping between the concrete Boomerang metric and a OpenCensus metric, as the following sample configuration file shows:
inspectit-eum-server:
definitions:
page_ready_time:
measure-type: LONG
beacon-field: t_page
unit: ms
views:
'[page_ready_time/SUM]': {aggregation: SUM}
'[page_ready_time/COUNT]': {aggregation: COUNT}
load_time:
measure-type: LONG
beacon-field: t_done
unit: ms
views:
'[load_time/SUM]': {aggregation: SUM}
'[load_time/COUNT]': {aggregation: COUNT}
start_timestamp:
measure-type: LONG
beacon-field: rt.tstart
unit: ms
navigation_start_timestamp:
measure-type: LONG
beacon-field: rt.nstart
unit: ms
end_timestamp:
measure-type: LONG
beacon-field: rt.end
unit: ms
views:
end_timestamp:
aggregation: LAST_VALUE
tags: {APPLICATION : true}
tags:
extra:
APPLICATION: my-application
beacon:
URL: u
OS: ua.plt
global:
- URL
- OS
- COUNTRY_CODE
exporters:
metrics:
prometheus:
enabled: true
host: localhost
port: 8888
security:
enabled: false
authorization-header: Authorization
permitted-urls:
- "/actuator/health"
- "/boomerang/**"
auth-provider:
simple:
enabled: false
watch: true
frequency: 60s
token-directory: "" # Empty by default to force users to provide one
default-file-name: "default-token-file.yaml"
A metric is defined through the following attributes:
name
: Defines the name of the metric. The name of the exposed view will have the used aggregation as suffix.measure-type
: Can be eitherLONG
orDOUBLE
.beacon-field
: The beacon key name, which is used as source of metric.description
: Optional. Defines an additional description of the exposed metric.unit
: The unit of the metric.tag-keys
: Optional. Defines a list of tag keys, which are exposed with the current metric.views
: A list of the views, which should be exposed. The aggregation can be eitherSUM
,COUNT
,LAST_VALUE
orHISTORGRAM
. For usingHISTOGRAM
, the fieldbucket-boundaries
is mandatory.bucket-boundaries
: Used for theHISTOGRAM
aggregation, defines the bucket boundaries as list of Doubles.
We distinguish between to different types of tags:
extra
- tags: Extra tags define tags, which are manually set in the configuration. The fieldextra
holds a list of key-value mappings.beacon
- tags: Beacon tags define tags, whose tag value is resolved by a beacon entry. The defined value of thebeacon
map will be resolved by using the provided beacon. In order to provide selected tags to each measurement by default, tags can be defined as global.global
holds a list of already defined tags, which will be then exposed for each measurement.
By using the tag COUNTRY_CODE
, the geolocation of the requester is resolved by using the requester IP and the GeoLite2 database. If the IP cannot be resolved, the tag value will be empty.
By now, the prometheus exporter is available. If ènabled
is set to true, the exporter is exposes the metrics under
http://[host]:[port]/metrics
Currently, the EUM Server only supports a simple API token security concept. In future, additional authentication providers
will be supported.
Security can be enabled by changing spring application.yml
, using system properties or environment variables.
inspectit-eum-server:
....
security:
enabled: true
authorization-header: Authorization
permitted-urls:
- "/actuator/health"
- "/boomerang/**"
auth-provider:
# List of providers
....
The simple token provider can be enabled from config file...
inspectit-eum-server:
...
security:
....
auth-provider:
simple:
# Enable/Disable Provider
enabled: true
# Flag indicates if the directory should be watched for changes and tokens reloaded
watch: true
# How often directory should be watched for changes
frequency: 60s
# The directory where token files are stored. Empty by default to force users to provide one
token-directory: ""
# The name of the initial token file
default-file-name: "default-token-file.yaml"
or via environment variables:
INSPECTIT_EUM_SERVER_SECURITY_AUTH_PROVIDER_SIMPLE_TOKEN_DIRECTORY=<my-directory>
INSPECTIT_EUM_SERVER_SECURITY_AUTH_PROVIDER_SIMPLE_ENABLED=TRUE;
INSPECTIT_EUM_SERVER_SECURITY_ENABLED=TRUE