Once OneAgent is deployed in full-stack monitoring mode on a host, it by default automatically injects the RUM JavaScript into the HTML of your web applications for the technologies listed in Technology support - Real User Monitoring - Web servers and applications. To initiate injection, simply restart your web server processes after installing OneAgent.
By default, injection follows a set of built-in rules for automatic injection, but there are scenarios where you may need to define a custom injection rule to achieve injection. Custom injection rules also support the exclusion of specific pages from injection, which allows you to set up manual insertion for the pages of an auto-injected application.
The RUM JavaScript is responsible for collecting RUM data from your customers' web browsers. It sends this data as XHR POST requests to a beacon endpoint, which performs initial validation before forwarding the data to Dynatrace. The default beacon endpoint in automatic injection scenarios is provided by the OneAgent instrumenting your web or application server, but alternative setups are possible, see Configure beacon endpoint for web applications.
The RUM JavaScript snippet injected into your application's HTML can vary in format, each designed to meet specific requirements as outlined in Select a snippet format. To configure the format used for automatic injection, refer to Configure the snippet format.
OneAgent injects the RUM JavaScript into each page based on the current configuration whenever the instrumented web or application server delivers the page. However, the page’s caching policy determines how frequently OneAgent has the opportunity to perform this injection. To address this, OneAgent includes a feature that optimizes cache control headers. For details on how this feature works and its limitations, see Cache control header optimizations.
If you don't have access to the web server hosting your application and therefore can't install OneAgent, you can monitor your application using agentless RUM.
OneAgent detects responses containing HTML content and injects the RUM JavaScript into the head section of each page. It does not modify other resources such as images, CSS files, JSON or XML documents, or plain text.
OneAgent tries to inject the RUM JavaScript as the first script on the page, which helps to ensure reliable monitoring results. Injection only works with valid HTML that follows basic best practices—for example, ensuring all elements are properly opened and closed. OneAgent follows the built-in rules specified below to determine the most suitable location within an HTML document for injecting the RUM JavaScript.
| Name | Condition | Action | Overrules |
|---|---|---|---|
<!DOCTYPE> | The | Abort and do not inject. Note that only a single Doctype declaration is allowed. | |
initial tag | A tag appears before
| Abort without injecting. | |
<?xml?> | an | Ignore and continue to scan the document. | non-<meta> tag non-<head> tag initial tag |
<html> tag | The | 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 | 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 | non-<meta> tag <base>/<meta> tag |
<title>/<noscript> tag | The | Ignore everything until the | <body> tag |
<base>/<meta> tag | Either the | 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 | Inject before it (conditional injection). Continue to scan the document, in case this injection choice is overruled. | |
unclosed <meta> | The | Add Continue to scan the document, in case this injection choice is overruled. | |
comment | The | Ignore and continue to scan the document. | non-<meta> tag non-<head> tag |
non-<head> tag | A tag is found after | Inject before it (conditional injection). Continue to scan the document, in case this injection choice is overruled. | |
</head> tag | The | 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 | 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 | Keep the injection point and continue to scan the document. Disregard the flush. | |
<body> tag | The | Document scan stops. Any potential injection point found earlier is used. If there are multiple potential injection points, the earliest one is used If no rule matched earlier, inject after the | |
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 you're unsure whether the RUM JavaScript was injected successfully or you're experiencing issues with your RUM setup, refer to Web applications: Issues with RUM JavaScript.
In some cases, OneAgent may be unable to perform injection using the built-in rules. This is typically due to malformed HTML, though other rare conditions may also prevent the ruleset from identifying a suitable injection point. In such scenarios, you can achieve automatic injection by defining a custom injection rule that explicitly specifies where the RUM JavaScript should be injected within the HTML document.
To create a custom injection rule that specifies the injection point in the HTML document
To disable injection for one or more pages within your application
This rule only disables injection and cache control header optimizations; it does not fully disable RUM functionality. For instance, cookies may still be set. If you're looking for a way to selectively enable RUM, please refer to the instructions in Roll out RUM selectively for your applications.
To configure the snippet format for automatic injection
To learn more about the different snippet formats, refer to Select a snippet format.
🟢 Enabled by default
Your application's caching policy directly influences how often OneAgent can inject the RUM JavaScript into a page using the current configuration. To ensure timely application of configuration changes, the cache control header optimizations feature modifies HTTP headers so that conditional requests result in a cache miss whenever the RUM configuration has changed, giving OneAgent a chance to inject. Details of these optimizations and the specific header modifications are provided below.
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.
OneAgent modifies the following response and request headers:
ETagLast-ModifiedHere's how OneAgent modifies the cache control headers.
If-None-Match and If-Modified-Since request headers are removed.If-Unmodified-Since and If-Match headers are removed.ETag and Last-Modified headers are used:
ETag header.Last-Modified header.ETag header is used:
ETag header.Last-Modified header is used:
ETag header is created.Last-Modified header.When the application consists of multiple instrumented tiers, the changes to the ETag and Last-Modified headers are applied on each tier.
OneAgent does not alter the Expires and Cache-Control headers, which explicitly define resource expiration times. To ensure timely updates, we recommend setting shorter expiration durations in these headers.
In rare cases, cache control header optimizations may interfere with your application's functionality. If this occurs, you can disable the feature. When disabled, the rollout of new RUM configurations will depend entirely on your application's existing caching behavior.
To disable the cache control header optimizations
In some cases, OneAgent may modify the cache control headers of non-HTML resources. This occurs because header modifications are applied before the exact content type can be determined. While OneAgent excludes certain resources from cache control header optimizations based on their URI suffix, it's not possible to account for all non-HTML content types.
If you want to prevent cache control header modifications for specific non-HTML resources, you can create a custom injection rule that disables injection for those resources.
If OneAgent is deployed on your process groups and automatic injection is supported for your technology, then OneAgent injects the RUM JavaScript automatically by default. But if you prefer, you can insert it manually instead into all or specific pages.
First, you need to suppress automatic injection as described in Disable injection for particular pages. Then, to insert the RUM JavaScript manually
Alternatively, you can also retrieve the snippet via the API, which allows you to integrate its insertion into your build process. This ensures that your application consistently operates with the latest configuration.