Introduction
The inspectIT now comes with a new, experimental feature: Browser End User Experience Monitoring (EUM). This feature allows you to measure the performance at the browser of the End User, giving more detailed insights than back-end instrumentation alone.
This is done by automatically injecting a JavaScript-Agent into your applications HTML code, which in turn captures relevant metrics at the client-side and sends them Back using AJAX Requests.
Currently, the captured metrics are only stored in the influx time-series database connected to the CMR and can be viewed using Grafana Dashboards. As a future feature however, it is planned to also integrate the captured End User Traces into the inspectIT UIs tracing view.
Prerequisites
The current implementation of the End User Monitoring only operates on the Java Servlet API, therefore only applications based on this API are supported. The used Servlet Container should not matter, as long as it adheres to the Servlet API standard. Therefore any common Servlet Container (e.g. Apache Tomcat, Glassfish) can be used.
As this feature is still experimental we recommend you to first try it on your system configuration in a safe environment.
All you need to do is to configure your application to start with the normal inspectIT Java Agent, the EUM-Instrumentation happens fully automatically when configured as described below.
To actually view any results, you also have to set up a connection from the CMR to your influx database as this currently is the only way of storing and accessing the data.
Configuration
The configuration of the End User Monitoring is available as a new tab in the Environment settings of the CMR, which is shown below:
To enable EUM, you first have to tick the corresponding Activate checkbox.
In addition, you have to specify the "Script Base URL": here you should provide a URL prefix, under which the Java Agent will make the JavaScript Agent Script available and to which the JavaScript Agent will send back the results. As this injection works through the Java Servlet API, you have to choose a URL prefix which is mapped to at least one Filter or Servlet. A typical good choice here is the URL under which your static content is available, e.g. "/scripts/" or "/img/".
Finally, you can select from the table which modules of the JavaScript Agent you would like to use, a description of each is given below:
| Module Name | Description |
|---|---|
| AJAX Capturing Module | When enabled, all AJAX requests issued by the webpage will be measured. |
| Async Module | Performs an instrumentation to trace the execution of asynchronous operations triggered using the JavaScript Functions setTimeout and setInterval. |
| Listener Instrumentation Module | This module instruments the addListener functions for DOM elements and therefore is able to capture User Actions such as clicks. |
| Speed index Module | Measures the RUM Speedindex, a metric describing how fast the page is rendered. |
| Navigation Timings Module | Captures the metrics provided by the HTML Navigation Timings API. |
| Resource Timings Module | Captures the metrics provided by the HTML Resource Timings API. |
After the set up you should now be ready to go! Navigate to your webpage and check out the Grafana Dashboard for the results.
Troubleshooting
If the EUM does not work even though you configured it as described above, you should look here first as we present the most common problems with their solutions in this section. However, first make sure you have restarted your instrumented Servlet Container, as currently changes to the environment settings are only effective after a restart.
If this section does not solve your problems, feel free to contact us or to fill out a bug report in our JIRA.
Problem: Script does not get injected into the HTML
If everything works properly, the JavaAgent should modify the HTML delivered by your sever injecting tags similar to the one shown below:
<script type="text/javascript">window.inspectIT_settings = {eumManagementServer : "/scripts/inspectIT_beacon_handler"}; </script> <script type="text/javascript" src="/scripts/inspectit_jsagent_1_ablr12.js"></script>
These tags should be the first tags to appear within the head section (or body if you don't have a head section).
Troubleshooting:
- If these tags are not present, first double check that EUM is enabled for your JVM which delivers the responses to the End User.
- A second possible root cause might be compression: The Java Agent has to parse the HTML delivered by your application in order to inject the JavaScript Agent tags.
- If the HTML is passed already compressed to the Servlet API output stream, the Agent is not able to do this, therefore try disabling the compression of the responses.
- If the compression is done "on-the-fly" however, e.g. by using a Servlet API Filter to perform the compression, compression should not affect the EUM injection.
Problem: JavaScript Agent script not reachable
This issue can be detected by opening your webpage with your browsers developer console opened up: The tags shown above are correctly injected, however the browser is unable to fetch the JavaScript Agent source?
The most common reason for this problem is that the configured "Script Base Url" is not a valid prefix, meaning that it is not mapped to any of your filters or servlets. You can test this by manually trying to fetch the JavaScript Agent source. For example, if your server is hosted on "localhost:8080" and you configured the base-url as "/scripts/", try entering "localhost:8080/img/inspectit_jsagent_1_1.js" in your browser. If everything works, you should receive the source of the agent, otherwise a HTTP 404 error.
This way you can test different settings for "Script Base Url" to find a prefix which works.