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 the RUM JavaScript that is placed inside the HTML of your web applications' web pages. We call this RUM JavaScript placement an "injection."

How does the RUM JavaScript injection work?

You can initiate the injection in one of two ways:

  • OneAgent RUM JavaScript 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 the RUM JavaScript into the head section of each page.
  • You can alternatively insert the RUM JavaScript into the HTML code of your web application manually without installing OneAgent. We provide the RUM JavaScript 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 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 RUM JavaScript injected?

The Dynatrace RUM 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 RUM JavaScript is injected only into HTML. We don't modify images, CSS, REST services, or XML files. OneAgent always tries to inject its RUM JavaScript 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 RUM JavaScript 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 RUM JavaScript.

If OneAgent doesn't automatically inject the RUM JavaScript 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. In the Dynatrace menu, go to Web.
  2. Select the application you want to configure.
  3. Click Edit to go to the Application settings.
  4. Select Injection on the left side.
  5. Click 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 RUM JavaScript 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:

  • Monitoring code: the JavaScript code that provides you with RUM monitoring capabilities like capturing user actions.
  • Configuration: all the RUM related settings you defined in the Dynatrace UI, including activated modules like Session Replay.
  • optional JavaScript tag that you can use to easily integrate the previous two parts into your web application depending 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 Monitoring code 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 as early as possible into your application code.

Injection format Description Caching Monitoring code 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

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

The monitoring code and configuration are updated according to the caching duration until the changes become active. You can configure the caching duration when setting up the injection.

Has to be configured on your servers Configured on your servers

We recommend that you regularly update the snippet to have the new configuration available from the start. Otherwise, the new configuration will only be available after the page has reloaded for the first time. You must configure the caching in your own environment using your web server configuration.

Note: All provided caching durations refer to how long the Dynatrace CDN will cache either your 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 JavaScript 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 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 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 RUM JavaScript

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 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. In the Dynatrace menu, go to Technologies & Processes.
  2. Select the technology tile that includes the process group where the RUM JavaScript 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).