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 for the technologies listed in Technology support - Real User Monitoring - Web servers and applications. 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.

To control 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 or application server. OneAgent performs some initial monitoring of the data and then forwards it to the Dynatrace Cluster. The data is transmitted with XHR POST requests. By default, the beacon endpoint is relative to the current domain.

It is also possible to send the data through an ActiveGate (only for Dynatrace Managed).
If you don't have OneAgent installed
Data is sent directly to Dynatrace, bypassing your infrastructure.

For more information, see Configure beacon endpoint for web applications.

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, for example, check that your code has 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.

Injection rules

Rule names appear in the OneAgent log in the following format: (NAME rule). Example: (</head> tag rule).

Name	Condition	Action	Overrules
<!DOCTYPE>	The `<!DOCTYPE>` tag is not `<!DOCTYPE html>`.	Abort and do not inject. Note: only a single Doctype decleration is allowed.
initial tag	A tag appears before `<html>` that is not one of the following: `<!DOCTYPE ...>` `<html>` `<link>` `<meta>` `<script>` `<style>`	Abort without injecting.
<?xml?>	an `<?xml ...?>` specification is encountered.	Ignore and continue to scan the document.	non-<meta> tag non-<head> tag initial tag
<html> tag	The `<html>` tag is encountered.	If a potential injection point is found earlier, inject there, and do not scan further. If there are multiple potential injection points, the earliest one is used. Otherwise continue to scan the document
<script src> tag	A `<script src="...">` tag is found within `<head>`.	If a potential injection point is found earlier, inject there, and do not scan further. If there are multiple potential injection points, the earliest one is used. Otherwise, inject before this `<script>` tag and do not scan further.	non-<meta> tag <base>/<meta> tag
<title>/<noscript> tag	The `<title>` or the `<noscript>` tag is encountered.	Ignore everything until the `</title>` or the `</noscript>` tag, then continue to scan the document.	<body> tag
<base>/<meta> tag	Either the `<base>` or the `<meta>` tag is encountered.	Discard any conditional injection point found earlier. Continue to scan the document.	any conditional injection point found earlier by: non-<meta> tag unclosed <meta> non-<head> tag
non-<meta> tag	A tag is found within `<head>` that is neither `<meta>` nor `<title>`.	Inject before it (conditional injection). Continue to scan the document, in case this injection choice is overruled.
unclosed <meta>	The `</head>` tag arrives after a `<meta>` tag that isn't closed either by the closing `</meta>` tag or by the XML-style `<meta ... />` tag.	Add `</meta>` followed by the injection, both before the `</head>` (conditional injection). Continue to scan the document, in case this injection choice is overruled.
comment	The `<!- comment ->` tag is encountered.	Ignore and continue to scan the document.	non-<meta> tag non-<head> tag
non-<head> tag	A tag is found after `<html>` but before `<head>` that is neither `<head>` nor `<body>`.	Inject before it (conditional injection). Continue to scan the document, in case this injection choice isoverruled.
</head> tag	The `</head>` tag encountered.	If a potential injection point is found earlier, inject there, and do not scan further. If there are multiple potential injection points, the earliest is used Otherwise, continue to scan the document.
flush	Java only Flush is called on the injecting stream/writer outside of the `<head></head>` section and a conditional injection awaits confirmation.	Discard the conditional injection point, propagate the flush,and continue to scan the document for a new injection point.	any conditional injection point found before by: non-<head> tag
flush in <head>	Java only Flush is called on the injecting stream/writer inside `<head></head>` and conditional injection awaits confirmation.	Keep the injection point and continue to scan the document. Disregard the flush.
<body> tag	The `<body>` tag is encountered.	Document scan stops. Any potential injection point found earlier is used. If there are multiples potential injection points, the earliest one is used If no rule matched earlier, inject after the `<body>`.
end of file	End of file is reached and scanning didn't terminate before that.	Don't perform an injection.	any conditional injection point found before by: non-<meta> tag unclosed <meta> non-<head tag
parse error	The document's contents don't appear to exhibit the basic structure expected from HTML tags and attributes	Document scan stops. If a potential injection point is found earlier, inject there, and do not scan further. If there are multiple potential injection points, the earliest one is used. If no rule provides an earlier injection point, don't perform an injection

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. You can also disable the RUM JavaScript injection for particular resources.

To create a custom injection rule

In the Dynatrace menu, go to Web.
Select the application that you want to configure.
In the upper-right corner of the application overview page, select More (…) > Edit.

From the application settings, go to Injection.

Under Define custom injection rules, select Add custom rule.
Define the Operator and, if required, the corresponding URL pattern to control to which pages your custom injection rule applies.
Define the rule by either using Before specific HTML or After specific HTML, and enter the corresponding HTML pattern.

To disable the RUM JavaScript injection for particular resources, select Do not inject.
Select Add to create the custom injection rule.

How to 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.				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.

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.

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	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.		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: Monitoring code: 1 y	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!¹
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 (deferred)	Code snippet: Monitoring code: 1 y	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.¹
Inline Code (`jsInlineScript`)	Provides you the complete configuration and monitoring code to manually inline them in your web application code.		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 CDN²	1 y	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

Be aware that this needs regular code snippet updates to guarantee compatibility (tested for 1 year).

For Managed, use your own CDN. For SaaS, the Dynatrace CDN is used.

For all injection formats except for the Code snippet deferred (asyncCS), the full functionality of the monitoring code is loaded synchronously.

Updates in manual insertion

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.
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.

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

Retrieve via REST API

Use the Dynatrace API to insert the RUM JavaScript via build scripts.

Use manual insertion for process groups

If your process groups are instrumented with OneAgent and automatic injection is supported for your technology, you can still insert the RUM JavaScript manually if you prefer.

To suppress automatic injection and insert the RUM JavaScript manually

In the Dynatrace menu, go to Web.
Select the application that you want to configure.
In the upper-right corner of the application overview page, select More (…) > Edit.

From the application settings, go to Injection.

Under Define custom injection rules, select Add custom rule.
Define the Operator and, if required, the corresponding URL pattern to control on which pages you need to suppress automatic injection.
Under Rule, select Do not inject.
Select Add to save your custom injection rule.
Go to the Manual insertion tab, select the required injection format, and copy the provided snippet.

If you are not sure whether Real User Monitoring is working for your environment or if you have trouble with your setup, have a look at Why don't I see my applications or monitoring data?.

How to ensure timely configuration updates for automatic injection?

🟢 Enabled by default

To ensure the timely delivery of the RUM configuration changes, OneAgent modifies certain cache headers. This feature is called the cache control header optimization.

When the cache control header optimization is turned on and the RUM configuration has been changed, the requests that would otherwise result in 304 Not Modified respond with 200 OK, giving OneAgent a chance to inject the RUM JavaScript into your application HTML code. If the RUM configuration hasn't been changed, the requests result in a 304 Not Modified response.

Modified headers

OneAgent modifies the following response and request headers:

Response headers

ETag
Last-Modified

Request headers

If-None-Match
If-Modified-Since
If-Unmodified-Since¹
If-Match¹

Not modified for range requests, which are generally excluded from RUM monitoring.

OneAgent does not modify the Expires and Cache-Control headers, which contain explicit resource expiration times. To ensure the timely updates, we recommend that you specify shorter expiration times in these headers.

Here's how OneAgent modifies the cache control headers.

When the RUM configuration is changed

The incoming If-None-Match and If-Modified-Since request headers are removed.
Modifications made to the If-Unmodified-Since and If-Match headers are removed.
When both ETag and Last-Modified headers are used:
- A suffix is appended to the ETag header.
- One second is subtracted from the Last-Modified header.
When only the ETag header is used:
- A suffix is appended to the ETag header.
When only the Last-Modified header is used:
- The ETag header is created.
- One second is subtracted from the Last-Modified header.

When the RUM configuration isn't changed

Before the request is handled by the web or app server, the modifications made to the headers are removed so that the web or app server doesn't see the changes.

When the application consists of multiple instrumented tiers, the changes to the ETag and Last-Modified headers are applied on each tier.

Cache header optimization for non-HTML resources

Sometimes OneAgent modifies the cache control headers of non-HTML resources. This happens because the header modification occurs before the exact content type is known. Dynatrace excludes certain resources from the cache header optimization based on the URI suffix, but it's impossible to cover all non-HTML resources.

To exclude non-HTML resources from the cache header optimization, create a custom injection rule to disable the injection of the RUM JavaScript.

Troubleshooting

Under rare circumstances, the cache header optimization might impair your application functionality. In this case, either disable the cache header optimization or, if the issue affects only non-HTML resources, create a custom injection rule to disable the injection of the RUM JavaScript for these resources.

To disable the cache control header optimization

In the Dynatrace menu, go to Web.
Select the application that you want to configure.
In the upper-right corner of the application overview page, select More (…) > Edit.

From the application settings, go to Capturing > Advanced setup.

Under Cookie and header settings, turn off Optimize the value of cache control headers for use with Dynatrace Real User Monitoring.

If you turn off this feature for one of your applications, the time required to roll out a new RUM configuration will solely depend on your application caching behavior.