RUM JavaScript injection

Dynatrace Real User Monitoring (RUM) collects metrics from your customers' web browsers and correlates the browser data with server-side information obtained from OneAgent. Web browser data is collected by a JavaScript tag that is placed inside the HTML of your web applications' web pages. We call this JavaScript tag placement an "injection."

How does JavaScript injection work?

You can initiate the injection in one of two ways:

  • OneAgent JavaScript tag injection is performed automatically during installation for Java, Apache HTTP Server, IIS, NGINX, and Node.js. All you need to do to initiate injection is to restart your web server processes after OneAgent installation. OneAgent identifies HTML content responses and automatically injects a small JavaScript tag into the head section of each page.
  • You can alternatively insert the JavaScript tag into the HTML code of your web application manually without installing OneAgent. We provide the JavaScript tag for you during the set up process. You can paste the tag into the pages you intend to monitor.

Note: To control the injection you can use alternative injection formats.

Depending on how you enable RUM, monitoring data is sent to Dynatrace within varying request types:

  • If you have OneAgent installed:
    The RUM JavaScript tag sends data back to your web server (Java, Apache, IIS). OneAgent performs some initial monitoring of the data and then forwards it to the Dynatrace Cluster. Transmission of data is performed using XHR Post requests. By default, the beacon endpoint is relative to the current domain. It is also possible to send it through an ActiveGate.
  • If you don't have OneAgent installed:
    Data is sent directly to Dynatrace, bypassing your infrastructure.

Where is the JavaScript tag injected?

The Dynatrace JavaScript only works with valid HTML. Messy page code is often the culprit when monitoring-data flow breaks down. So pay special attention to basic HTML best practices (i.e., no unclosed or missing tags).

Our JavaScript tag is injected only into HTML. We don't modify images, CSS, REST services, or XML files. OneAgent always tries to inject the JavaScript tag as the first script on the page. This helps to keep your web application intact but also guarantees more reliable monitoring results (for example, timing). If you insert the JavaScript tag manually, ensure that it's the first executable script on each page.

The following rules specify the criteria for determining a suitable location within an HTML document to inject the JavaScript tag.

If OneAgent doesn't automatically inject the RUM JavaScript tag into your application's pages because of HTML validation errors, first check potential errors by going through the instructions given above. Alternatively, define custom injection rules to control when and where the automatic injection happens on your application's pages.

  1. Select Applications from the navigation menu.
  2. Click on your application.
  3. Click on Edit to go to the Application settings.
  4. Select Injection on the left side.
  5. Click on Add custom rule under Define custom injection rules.
  6. Define the Operator and (Optional) the corresponding URL pattern to control on which pages your custom injection rule applies.
  7. Define the rule by either using Before specific HTML or After specific HTML and enter the corresponding HTML pattern.
  8. Click Add to save.

How can you control the injection?

Regardless of whether you use automatic injection via OneAgent or whether you've chosen to manually insert the monitoring code yourself into your web application, Dynatrace provides different injection formats to integrate RUM into your web application. But let's first look at the individual parts that are needed to integrate Dynatrace RUM into your web application:

  • Configuration: all the RUM related settings you defined in the Dynatrace UI, including activated modules like Session replay.
  • Monitoring code: the JavaScript code that provides you with RUM monitoring capabilities like capturing user actions.
  • (Optional) JavaScript tag: that you can use to easily integrate the previous two parts into your web application, however, this depends on the selected format.

Injection formats

Find the injection format that best suits your web application and needs in the following subsections related to each injection type.

Automatic injection

Automatic injection supports all injection formats and provides seamless automatic updates performed by OneAgent.

Injection format Description Caching Version updates Config updates When to use
All formats Dynatrace OneAgent can leverage all injection formats listed under manual insertion to automatically integrate RUM into your application. The only exception is the JavaScript tag format, since the OneAgent JavaScript tag is essentially the same with the difference of including the configuration, since OneAgent can automatically update it. Has to be configured on your servers Automatic update Automatic update Use when automatic injection into your web application is possible. Regardless of the selected injection format OneAgent will automatically update your configuration and monitoring code.

Manual insertion

Use manual insertion whenever automatic injection isn't possible. In this case, be aware that selecting the right injection format is important because otherwise you may end up losing information, such as certain timings or user actions, which are only available when both, the RUM monitoring code and configuration are fully loaded. This is especially true in cases where this point in time might be delayed. For example, when using the Code snippet format with deferred mode or when using a tag manager. Regardless of your selected injection format, it's always best to insert the provided RUM JavaScript code as early as possible into your application code.

Injection format Description Caching Version updates Config updates When to use
JavaScript tag (jsTagComplete) Provides you a JavaScript tag to manually insert it into your web application code. The referenced JavaScript file in the tag contains the configuration and monitoring code, which causes a lower possible caching duration. Can be configured in Dynatrace
1 h - 6 d
Automatic update Automatic update Use when you don't want to take care of configuration or monitoring code changes manually. Often used in combination with a tag manager to integrate RUM.
Code snippet synchronous (syncCS) Provides you a JavaScript code snippet (incl. configuration) with basic functionality to manually insert it into your web application code. The full functionality of the monitoring code is loaded synchronously Code snippet:
Has to be configured on your servers Monitoring code:
1 y
Automatic update Automatic update Use when configuration updates should be immediately reflected on the client of your real users and when you don't want to manually update the configuration or monitoring code. Be aware that this option is render blocking!1
Code snippet deferred (asyncCS) Provides you a JavaScript code snippet (incl. configuration) with basic functionality to manually insert it into your web application code. The full functionality of the monitoring code is loaded asynchronously (i.e., deferred) Code snippet:
Has to be configured on your servers Monitoring code:
1 y
Automatic update Automatic update Use when configuration updates should be immediately reflected on the client of your real users, when you don't want to manually update the configuration or monitoring code, and when you want to load Dynatrace RUM deferred.1
Inline Code (jsInlineScript) Provides you the complete configuration and monitoring code to manually inline them in your web application code. Has to be configured on your servers Manual update required Manual update required Use when you want to avoid another request and keep the number of web requests at a minimum. Ideally use this in conjunction with fully automatic updates of the inlined code via API, to ensure the monitoring code and the configuration is always up to date
OneAgent JavaScript tag (jsTag) Provides you a JavaScript tag (incl. configuration) to manually insert it into your web application code. The monitoring code is loaded as a separate file from a CDN2 1 y Manual update required Manual update required Use the same JavaScript tag that is inserted automatically by Dynatrace OneAgent with automatic injection turned on. Only use it for testing purposes or in conjunction with fully automatic updates of the inlined code API, to ensure the monitoring code and the configuration is always up to date

1 Be aware that this needs regular code snippet updates to guarantee compatibility (tested for 1 year).
2 For Managed, use your own CDN. For SaaS, the Dynatrace CDN is used.

Updates in manual insertion

Can be configured in Dynatrace Configured in Dynatrace

Has to be configured on your servers Configured on your servers

Note: All provided caching durations refer to how long the Dynatrace CDN will cache either your RUM monitoring code and/or configuration. If you use your own CDN (in Dynatrace Managed), the provided durations aren't applicable, since they depend on your own configuration.

Retrieve via REST API

Use the Dynatrace API to insert the RUM monitoring code via build scripts.

Not sure that Real User Monitoring is working in your environment? Having trouble with your setup? Have a look at Why don't I see my applications or monitoring data?

RUM injection and correlation for process groups

Injection of the RUM JavaScript tag into process groups is enabled by default. If you don't enable this setting, your RUM data may not be correlated with your server-side PurePaths, which will be a problem when the root of the server-side PurePath is captured on this process group.

This setting allows OneAgent to:

  • automatically inject the RUM JavaScript tag into each page delivered by this process group.
  • provide the necessary info to correlate RUM data with server-side PurePaths.
  • forward beacons to the Dynatrace cluster.
  • deliver the JavaScript monitoring code.

Example

Consider an Apache HTTP server as a proxy and a Java application server on the back end. Disabling this setting for the Apache HTTP server process group will break the correlation with the RUM data, even if Dynatrace injects the RUM JavaScript tag on the Java backend process group. For RUM data to correlate with server-side PurePaths, RUM must be enabled on the OneAgent that instruments the entry point of your application (the Apache HTTP server in this example).

Also see Set up process group monitoring.

To manually enable/disable RUM JavaScript injection for a process group

  1. From the navigation menu, select Technologies.
  2. Select the technology tile that includes the process group where the JavaScript tag is to be injected. The matching process groups are displayed further down the page.
  3. Scroll down and select the process group.
  4. Select Edit.
  5. On the General tab, turn on the setting Enable Real User Monitoring for this process group (or alternatively, turn off this setting to disable RUM JavaScript injection for the process group).