Troubleshooting automatic RUM injection failures

[MargitM]

• The problem
• Find out which OneAgent is responsible for injecting the RUM JavaScript
• Use OneAgent's built-in RUM health check
• Run the health check
• Interpret the diagnostic data added by the health check
• Ignoring browser and IP exclusion rules
• Injection suddenly working withdtHealthCheck
• Troubleshooting injection failures without OneAgent's RUM health check
• Does the RUM JavaScript injection diagnostics feature return an injection failure reason?
• Is automatic injection supported for your technology?
• Is the HTML served through a cache?
• Are full-stack monitoring and deep monitoring active?
• Is RUM enabled for ASP.NET Core?
• Is RUM enabled for your application?
• Is application detection set up properly?
• Is RUM disabled on the process group?
• Is your HTML valid and well-formed?
• Do you have a valid license?
• Are browser or IP restrictions rules configured?
• Is RUM disabled for "Do not track" enabled browsers?
• Is the document request a range request?
• Does a custom injection rule suppress injection?
• Is a web request URL exclusion rule in place?
• Managed Offline: Has the RUM JavaScript been deployed?
• What's Next?

 

The problem

Dynatrace Real User Monitoring (RUM) supports the automatic injection of the RUM JavaScript across a wide range of technologies. When OneAgent is deployed in full-stack monitoring mode, it automatically injects the RUM JavaScript into the HTML of your web applications.

If injection succeeds, you'll find a script element containing the string data-dtconfig—either as an attribute or embedded within the code—in the HTML of your page.

However, in certain scenarios, OneAgent may fail to inject the RUM JavaScript. This troubleshooting guide is designed to help you systematically identify and resolve such issues. For best results, follow the steps in the order presented.

Find out which OneAgent is responsible for injecting the RUM JavaScript

Applications often include multiple instrumented tiers. In such cases, RUM injection is performed by the first OneAgent—running on a technology where RUM injection is supported—that has access to the response HTML.

For example, consider an application that includes an Apache HTTP server acting as a proxy and an Apache Tomcat generating the HTML. In this setup, the OneAgent on Tomcat performs the injection.

When the OneAgent on Tomcat initiates the injection, it adds the response header X-OneAgent-JS-Injection. If the OneAgent on the Apache HTTP server detects this header, it skips its own injection attempt to avoid double injection.

If you are unsure about the application tiers that handle the HTML document request, use the Distributed Traces screen or the Distributed Tracing app to locate and inspect a distributed trace of the request.

Use OneAgent's built-in RUM health check

For technologies that support automatic RUM injection, OneAgent provides a built-in health check mechanism offering a convenient way to identify the root cause of injection failures.

The feature is triggered by setting the user agent string dtHealthCheck on requests. When such a request is received, OneAgent adds diagnostic data to the response. This section provides context to help you interpret this data and resolve many common causes of RUM injection failures independently.

Run the health check

Add the dtHealthCheck user agent as described in How to enable dtHealthCheck.

The response headers for the HTML document should now include x-dtAgentId and x-dtHealthCheck.

If the application cannot handle the dtHealthCheck user agent

Some applications may not work correctly with custom user agent strings like dtHealthCheck. If this applies to your application, use the section Troubleshooting injection failures without OneAgent's RUM health check.

If the headers are missing

If the response headers x-dtAgentId and x-dtHealthCheck are missing, go through the following checks:

1. Confirm that automatic injection is supported for your technology

Refer to Technology support - Real User Monitoring - Web servers and applications to verify that RUM injection is supported for at least one of the technologies delivering the HTML.

2. Check whether the HTML is served through a cache

A common reason for missing x-dtAgentId and x-dtHealthCheck headers is caching—for example, when the application is served via a CDN or caching proxy. If you're unsure, inspect the response headers. CDNs often add custom headers such as X-Cache: Hit.

To confirm whether caching is the issue, send a request that bypasses the cache. This allows the request to reach the instrumented server, giving OneAgent a chance to inject. If injection succeeds when bypassing the cache, you’ll need to either clear the cache or wait until it updates with the injected page.

3. Verify that full-stack monitoring and deep monitoring are active

For RUM injection to function, OneAgent must be installed in full-stack monitoring mode. To check this, go to Infrastructure → Hosts and select the relevant host. On the host overview page, look for Monitoring mode.

Also ensure that deep monitoring has not been disabled.

Make sure the monitored processes were restarted after deploying OneAgent.

4. Confirm that RUM is enabled for ASP.NET Core

If you are using ASP.NET Core, verify that the features Enable Real User Monitoring (RUM) for ASP.NET Core and .NET ASP.NET Sensor V2 are enabled under Settings → Preferences → OneAgent features. Restart the processes after enabling these features.

If the headers are still missing

If none of the reasons above explain the missing headers, your infrastructure may be stripping them.

Refer to the page Firewall Constraints for RUM, which lists all headers that must be preserved to ensure proper functioning of RUM. Verify that your setup complies with these requirements.

Until the necessary changes are implemented, you can continue troubleshooting by following the steps in the section Troubleshooting injection failures without OneAgent's RUM health check.

Interpret the diagnostic data added by the health check

The dtHealthCheck feature adds the response headers x-dtAgentId and x-dtHealthCheck, and, in some cases, inserts a special HTML marker into the response body. This section explains how to interpret that data.

Focus your analysis on the data added to the HTML document response; data added to other requests during page load is not relevant for troubleshooting injection failures.

The x-dtAgentId response header

The x-dtAgentId response header contains the IDs of all OneAgents supporting RUM that are involved in handling the request. These are the module IDs available on the OneAgent health overview and as part of the OneAgent Metadata in the latest Dynatrace.

In the following example, OneAgents on two tiers are involved in handling RUM for the request:

x-dtAgentId: 0x352ce8d5f768331c|0x589f2851fdfa6f1b

The IDs are listed from the innermost to the outermost tier. Here, 0x352ce8d5f768331c is the OneAgent that instruments the application server, and 0x589f2851fdfa6f1b is the OneAgent on the proxy. The header provides useful context for interpreting the second header, x-dtHealthCheck.

The x-dtHealthCheck response header

OneAgent reports its findings as short, descriptive strings in one or more x-dtHealthCheck response headers. On each tier, OneAgent can report multiple findings. Each header contains the ID of the OneAgent that added it. You can interpret the results using the section Health check results.

Example 1

x-dtHealthCheck: BLOCKED_BY_INCOMING_COOKIE|0x352ce8d5f768331c
x-dtHealthCheck: OK_IPRANGE|0x589f2851fdfa6f1b

In this case, the OneAgent on the proxy tier detected an IP exclusion rule that prevents RUM monitoring for the given IP address. As a result, it added the OK_IPRANGE finding. The OneAgent on the application tier recognized the cookie that the OneAgent on the proxy tier set to communicate this decision. It then skipped its injection attempt and reported BLOCKED_BY_INCOMING_COOKIE.

Example 2

x-dtHealthCheck: OK_BUT_PERCENTAGE|0x352ce8d5f768331c
x-dtHealthCheck: OK_BUT_PERCENTAGE|ALREADY_INJECTED_HEADER_FOUND|0x589f2851fdfa6f1b

Here, the OneAgent on the application tier determined that cost and traffic control is active. It proceeded with an injection attempt and reported OK_BUT_PERCENTAGE. The agent on the proxy tier also detected active cost and traffic control and, in addition, reported ALREADY_INJECTED_HEADER_FOUND. This indicates that it found an X-OneAgent-JS-Injection response header and therefore skipped its own injection attempt. As noted in the description of OK_BUT_PERCENTAGE, you should check the response body for an HTML marker in this case.

Health check results

When the health check is applied to an HTML document request, the x-dtHealthCheck header may return the following results:

OK

No issues were detected during the portion of request processing where OneAgent can reliably set response headers. However, you must inspect the response body for potential HTML markers, as problems may still exist beyond this point.

CAPTURING_OFF_SENSOR_CONF

This result can have two different meanings.

RUM is disabled on the process group

RUM is disabled on the process group by one of the following settings or their equivalents on the environment level:

• Your process group → Settings → Real User Monitoring → Enable Real User Monitoring
• Your process group → Settings → OneAgent features → Real user monitoring

On Java, make sure to restart the processes after enabling these settings.

A web request URL exclusion rule is in place

This request is not captured due to a web request URL exclusion rule in Settings → Server-side service monitoring → Deep monitoring → Exclude specific incoming web request URLs. On Java, this setting also suppresses RUM injection.

CAPTURING_OFF_APP_CONF

Most likely, the following setting is disabled in the RUM application:

• SaaS: Your RUM application → Settings → General settings -> Enablement and cost control → Enable Real User Monitoring Classic
• Managed: Your RUM application → Settings → General settings -> Enablement and cost control → Enable Real User Monitoring

If the application where you expect the request to be assigned to has the setting enabled, check if CAPTURING_OFF_APP_CONF appears together with DEFAULT_CONFIG. This combination usually indicates a licensing-related issue.

Otherwise, you are dealing with an application detection issue. Review the page Application detection rules approach. As described there, URL rewriting on an uninstrumented component is a common root cause of application detection issues. Use the Distributed Traces screen or the Distributed Tracing app to locate a trace of the request and identify the URL that actually reaches the first instrumented tier, where the application is detected.

Parts of the guide RUM data is assigned to a different application than expected are also applicable to this scenario, particularly the sections Double-check your application detection rules and Issues caused by URL rewriting on an uninstrumented component.

DO_NOT_TRACK

The request includes a DNT (Do Not Track) header, and the application has the setting Disable Real User Monitoring for "Do Not Track" enabled browsers enabled.

OK_BUT_BROWSER_RESTRICTION

A browser exclusion rule is configured that suppresses injection for the dtHealthCheck user agent. To bypass this rule, refer to Ignoring browser and IP exclusion rules.

OK_IPRANGE

An IP address exclusion rule is configured that suppresses injection for your IP address. To bypass this rule, refer to Ignoring browser and IP exclusion rules.

OK_BUT_PERCENTAGE

Cost and traffic control is configured to a value below 100%. While only a subset of sessions is captured with this configuration, OneAgent always makes an injection attempt. No injection issues were detected during the portion of request processing where OneAgent can reliably set response headers. However, you must inspect the response body for potential HTML markers, as problems may still exist beyond this point.

NO_CONTENT_TYPE

The response lacks a Content-Type header, preventing OneAgent from determining whether the content is HTML.

Note that even if the Content-Type header appears in browser developer tools, it may not have been present at the time OneAgent processed the response.

INVALID_MIME_TYPE

The MIME type specified in the Content-Type response header is not text/html.

INVALID_ENCODING

The charset (character encoding) defined in the Content-Type response header is not supported.

INVALID_HTML

OneAgent was unable to find a suitable injection point, usually due to ill-formed HTML.

As a workaround, create a custom injection rule that injects before or after a specific HTML pattern.

In Java, this result may also occur if OneAgent exceeded the 100,000-character threshold while scanning the HTML. This limit was removed for applications created in Dynatrace version 1.205 and later, and starting with version 1.315, it was discontinued entirely.

NO_HTML

OneAgent determined that the resource does not qualify for injection based on its URL suffix—for example, .js or .css. These suffixes typically indicate non-HTML content, and therefore injection is skipped.

OK_BUT_URL_RESTRICTION

A custom injection rule is configured that suppresses injection for this page.

INJECTION_PREVENTED_BY_HEADER

The request includes a Range header, indicating an HTTP range request. Since automatic RUM injection is not supported for range requests, you'll need to manually insert the RUM JavaScript into the HTML response.

JS_AGENT_MISSING

OneAgent did not receive the monitoring code for the configured RUM JavaScript version from the Dynatrace cluster. In Managed Offline environments, ensure that the required RUM JavaScript version is properly deployed to the cluster.

ALREADY_INJECTED_HEADER_FOUND

OneAgent skips injection because the response already includes an X-OneAgent-JS-Injection header. This header indicates that another agent has either already injected the RUM JavaScript or made an attempt to do so.

ENVIRONMENT_MISMATCH

OneAgent detected that this request was already processed by another OneAgent connected to a different Dynatrace environment, which instruments a tier closer to the browser. To avoid mixing RUM configurations across environments, the current OneAgent disables its own RUM functionality and defers injection to the other agent.

Since Dynatrace RUM does not support cross-environment scenarios, this health check result should be investigated to ensure consistent monitoring.

BLOCKED_BY_INCOMING_COOKIE

This result typically occurs alongside OK_IPRANGE, OK_BUT_BROWSER_RESTRICTION, or DO_NOT_TRACK, set by another OneAgent.

That agent determined that injection should be skipped—either to comply with the DNT header or due to an IP or browser exclusion rule—and communicated this decision to other OneAgents using the dtCookie. OneAgents that find and evaluate the cookie skip their injection attempts.

DEFAULT_CONFIG

OneAgent was unable to detect a RUM application and fell back to the default configuration, which happens when it doesn't receive application settings from the cluster.

This typically indicates licensing-related issues.

INJECTION_TRESHOLD

Note: The spelling INJECTION_TRESHOLD is a typo in the actual value reported by OneAgent. It’s documented as-is to match what you’ll see in the response headers.

It means OneAgent exceeded the 100,000-character threshold while scanning the HTML. This limit was removed for applications created in Dynatrace version 1.205 and later, and starting with version 1.315, it was discontinued entirely.

This health check result is only set by OneAgents on non-Java technologies, where you can work around the limit by using a custom injection rule that injects before or after a specific HTML pattern.

MARKER_LOST_IN_FLUSH

OneAgent lost the injection opportunity because one of the involved Java servlets or filters flushed the output stream. If you cannot remove the flush, try working around the issue by using a custom injection rule that injects after a specific pattern.

RESPONSE_BODY_ALREADY_GZIPPED

OneAgent does not inject because the response body is already gzipped. This result is specific to Java, where—unlike other technologies—injection into already compressed content is not supported. Typically, this isn't a problem, as OneAgent strategically selects an injection point in the filter chain before compression occurs.

However, in some cases—such as when a single servlet handles content creation, header writing, and compression—this strategy may not be feasible. In such scenarios, the following workarounds are available:

Injection on the proxy tier

On other technologies that support RUM injection, OneAgent can inject into compressed resources.

• If your Java application is already behind a proxy of a supported technology, you can disable RUM on the Java process group to shift injection to the proxy tier. To do this, go to: Your process group → Settings → Real User Monitoring → Enable Real User Monitoring.
• If no proxy is in place, consider adding one.

Manual insertion

If adding a proxy is not an option, you can manually insert the RUM JavaScript into your HTML pages. For details, see Use manual insertion for pages of an auto-injected application.

ORIGINAL_RESPONSE_REQUIRED

One of the involved servlets or filters requires the original ServletResponse through an explicit type cast. OneAgent had to return the original servlet response without the wrapper that injects the RUM JavaScript, and therefore could not perform the injection. The workarounds listed under RESPONSE_BODY_ALREADY_GZIPPED—injection on the proxy tier and manual insertion—are also suitable for this scenario.

HTML markers

During the HTML injection process, OneAgent may at some point not be able to reliably add the health check results INVALID_HTML and INJECTION_TRESHOLD anymore to the x-dtHealthCheck header. To compensate, the health check inserts HTML markers into the response body. These markers appear as:

<!-- Dynatrace RUM health check active. No suitable injection location in HTML found. -->

For details and possible workarounds, refer to the descriptions of INVALID_HTML and INJECTION_TRESHOLD.

Ignoring browser and IP exclusion rules

If your application is configured to restrict RUM to specific browsers or IP ranges, the default dtHealthCheck user agent may not provide visibility into potential injection issues. To bypass the exclusion rules during health checks, use the special user agent string dtHealthCheckIgnoreRestrictions. With this user agent, OneAgent reports the configured browser/IP restrictions, but then proceeds with injection and reports further injection issues, if there are any.

Injection suddenly working with dtHealthCheck

If injection starts working as soon as you set the dtHealthCheck user agent, the most likely cause of the previous injection failure is the user agent string you used previously.

Check whether you've configured any browser exclusion rules that might exclude this browser. Also note that OneAgent applies internal rules that disable all RUM functionality for user agents that clearly do not represent real users—such as strings starting with curl/ or PostmanRuntime/.

Troubleshooting injection failures without OneAgent's RUM health check

If your application cannot handle the dtHealthCheck user agent or your infrastructure strips the returned headers, review the following checks.

Does the RUM JavaScript injection diagnostics feature return an injection failure reason?

The RUM JavaScript injection diagnostics feature on the RUM application health check page offers a convenient way to diagnose injection failures. While it provides fewer insights compared to the health check triggered by the dtHealthCheck user agent, we still recommend starting with a diagnostics run before proceeding with the checks outlined below.

Is automatic injection supported for your technology?

If you haven't already done so, refer to Technology support - Real User Monitoring - Web servers and applications to verify that RUM injection is supported for at least one of the technologies delivering the HTML.

Is the HTML served through a cache?

A common reason for missing injection is that the HTML is served through a cache, such as a CDN or a caching proxy. If you're unsure whether this applies to your page, inspect the response headers—CDNs often include custom headers like X-Cache: Hit.

To determine if caching is the cause, try sending a request that bypasses the cache. This ensures the request reaches the instrumented server, giving OneAgent the opportunity to perform the injection. If the injection succeeds when bypassing the cache, then caching is the issue. In that case, you’ll need to either clear the cache or wait for it to update with the injected version of the page.

Are full-stack monitoring and deep monitoring active?

For RUM injection to function, OneAgent must be installed in full-stack monitoring mode. To check this, go to Infrastructure → Hosts and select the relevant host. On the host overview page, look for Monitoring mode.

Also ensure that deep monitoring has not been disabled.

Make sure the monitored processes were restarted after deploying OneAgent.

Is RUM enabled for ASP.NET Core?

If you are using ASP.NET Core, verify that the features Enable Real User Monitoring (RUM) for ASP.NET Core and .NET ASP.NET Sensor V2 are enabled under Settings → Preferences → OneAgent features. Restart the processes after enabling these features.

Is RUM enabled for your application?

Check whether the following setting is enabled in the RUM application:

• SaaS: Your RUM application → Settings → General settings -> Enablement and cost control → Enable Real User Monitoring Classic
• Managed: Your RUM application → Settings → General settings -> Enablement and cost control → Enable Real User Monitoring

With this setting disabled, the RUM JavaScript is not injected.

Is application detection set up properly?

Ensure that the request for the HTML document maps to the application where you expect it to. This is especially relevant if your environment has any auto-injected applications where RUM is disabled.

As described in Application detection rules approach, URL rewriting on an uninstrumented component is a common root cause of application detection issues. Use the Distributed Traces screen or the Distributed Tracing app to locate a trace of the request and identify the URL that actually reaches the first instrumented tier, where the application is detected.

Parts of the guide RUM data is assigned to a different application than expected are also applicable to this scenario, particularly the sections Double-check your application detection rules and Issues caused by URL rewriting on an uninstrumented component.

Is RUM disabled on the process group?

The RUM JavaScript can only be injected if RUM is enabled on the process group. Check whether one of the following settings—or their environment-level equivalents—is disabled:

• Your process group → Settings → Real User Monitoring → Enable Real User Monitoring
• Your process group → Settings → OneAgent features → Real user monitoring

On Java, make sure to restart the processes after enabling these settings.

Is your HTML valid and well-formed?

Ensure your HTML is well-formed by following basic best practices—for example, opening and closing all elements properly.

To work around ill-formed HTML, create a custom injection rule that injects before or after a specific HTML pattern.

Do you have a valid license?

Injection failures may also result from licensing issues. Make sure your license is still valid.

Are browser or IP restrictions rules configured?

Check if there are any browser or IP exclusion rules configured that suppress injection for your IP or browser.

Is RUM disabled for "Do not track" enabled browsers?

If the application has the setting Disable Real User Monitoring for "Do Not Track" enabled browsers enabled, ensure that your browser does not send a DNT (Do Not Track) header on the request.

Is the document request a range request?

Check if the document request includes a Range header and is therefore an HTTP range request.

If it does, you'll need to manually insert the RUM JavaScript into the HTML response, since automatic RUM injection is not supported for range requests.

Does a custom injection rule suppress injection?

Check whether you have a custom injection rule configured that suppresses injection for this page.

Is a web request URL exclusion rule in place?

Check if a web request URL exclusion rule is configured for the request URL in Settings → Server-side service monitoring → Deep monitoring → Exclude specific incoming web request URLs. On Java, this setting suppresses RUM injection.

Managed Offline: Has the RUM JavaScript been deployed?

In Managed Offline environments, ensure that the required RUM JavaScript version is properly deployed to the cluster.

What's Next?

If you've completed the troubleshooting steps above but haven't been able to identify the root cause of your issue and solve it, please contact Dynatrace via the in-product chat or by creating a support ticket.

To help our support team investigate efficiently, include the following information:

• Access details, if the page is publicly available and you can grant access to the support team.
• If access cannot be granted: A HAR file, or, preferably, a Fiddler session capturing the full scenario—ideally with dtHealthCheck enabled.
• A brief summary of the troubleshooting steps you've completed.

Providing this information upfront will help speed up the resolution process.