Upgrade data capturing
- Latest Dynatrace
- How-to guide
- 2-min read
- Published Oct 06, 2026
Upgrading data capturing is the first step when you move from RUM Classic to RUM. RUM shares most settings that control data capturing with RUM Classic. When you change them in RUM Classic, your changes also apply to RUM, and vice versa. For this reason, only a few settings need your attention during the upgrade. The steps below walk you through these settings and other upgrade tasks.
Configure your infrastructure
Activate RUM in your RUM Classic applications
Activate the new RUM cookies
Adapt your XHR exclusion rules
Configure frontend-backend linking
Migrate your properties and user tags
Configure your infrastructure
RUM largely relies on the same HTTP headers and cookies as RUM Classic. If you have already configured your firewalls and other infrastructure components to comply with the infrastructure pass-through requirements for RUM Classic, you only need to take care of the following additional items to comply with the infrastructure pass-through requirements for RUM.
Do not alter the beacon URL query string
When RUM is active, RUM beacons in a new format (recognizable by the query string parameter pv=4) are sent alongside RUM Classic beacons to the same endpoint. For these beacons, the beacon URL query string's integrity is verified using a checksum. Your infrastructure must therefore ensure that the beacon URL query string is not altered in any way. This includes modifying, removing, or reordering parameters.
If your infrastructure alters the query string, the beacon endpoint rejects the beacons in the new format. Rejected beacons return a JSON response with the field status set to ERROR.
Let the W3C trace context pass through
In RUM, the W3C trace context headers traceparent and tracestate are used for frontend-backend linking. Since RUM Classic did not use these headers, you may still need to configure your infrastructure to let them pass through.
Allow the new RUM cookies
Once an environment is upgraded to Latest Dynatrace, additional cookies are used. You can also activate these cookies in advance to identify and resolve compatibility issues with your infrastructure before the environment upgrade. We recommend this approach; step 3 describes it. Either way, you need to configure your infrastructure to allow these cookies. For details, see Cookies on upgraded environments.
Activate RUM in your RUM Classic applications
Follow the guides for your frontend technologies.
To achieve upgrade readiness for Latest Dynatrace, update to:
- RUM JavaScript version 1.347+
- OneAgent for Android version 8.347+
- OneAgent for iOS version 8.347+
- OneAgent for React Native version 2.347+
- OneAgent for Flutter version 3.347+
- OneAgent for .NET MAUI version 1.347+
You can turn on RUM only if RUM Classic is active. At this time, you can't deactivate data ingestion into RUM Classic.
Activate the new RUM cookies
Once your environment is upgraded to Latest Dynatrace, RUM sets additional cookies. Activating these cookies in advance lets you identify and resolve compatibility issues with your infrastructure before the upgrade.
Turn on the Upgrade RUM cookies setting as described in Cookies and client-side storage for RUM and Session Replay. You can turn it on for the whole environment or for individual web frontends. Activating it frontend by frontend lets you verify your infrastructure on a small scale before you roll out the change everywhere.
Adapt your XHR exclusion rules
The exclusion rules for XHR and Fetch requests that you configured in RUM Classic also apply in RUM, but the URL they are matched against can differ. RUM Classic matches a rule against whatever URL is passed to the XHR or Fetch call, whether it is relative or absolute. RUM always matches the rule against the absolute URL. For details, see Exclude XHR and Fetch requests from monitoring.
If requests that you excluded in RUM Classic are captured again in RUM, check whether you have rules that can only match a relative URL. Because a rule is a regular expression that needs to match only a substring of the URL, this usually affects rules anchored with ^.
For example, an application sends heartbeat requests to the relative URL /api/heartbeat, which RUM matches as https://example.com/api/heartbeat. A rule with the regular expression ^/api/heartbeat excludes these requests in RUM Classic, but not in RUM, because the absolute URL doesn't start with /api/heartbeat. Removing the anchor and using /api/heartbeat excludes the requests in both RUM and RUM Classic.
Configure frontend-backend linking
In RUM Classic, some scenarios require additional setup to connect frontend data with server-side distributed traces. Because RUM uses a different approach for frontend-backend linking, this setup doesn't carry over, so you need to set up the following scenarios again in RUM.
Cross-origin XHRs and Fetch requests on web frontends
In RUM Classic, you can link cross-origin XHRs and Fetch requests either by adding the x-dtc header through a regular expression or by using credentialed requests. Neither configuration can be migrated automatically, because RUM uses the W3C trace context instead, and adding it without the corresponding CORS configuration would cause CORS errors. To set up the W3C trace context for cross-origin requests, see Add the W3C trace context to cross-origin requests.
Use of custom networking stacks on mobile frontends
If you use a custom networking stack on your mobile frontend, RUM Classic requires you to propagate the x-dynatrace header manually to link RUM data with server-side distributed traces. In RUM, frontend-backend linking relies on the W3C trace context instead, which you also need to add manually in this scenario. For instructions and examples, see Android, iOS, or .NET MAUI.
RUM has no equivalent to the WebRequestTiming object for capturing web request timings. Your code needs to measure these timings and report them as shown in the linked examples.
Migrate your properties and user tags
The user action properties, user session properties, and user tags you configured in RUM Classic do not apply in RUM. RUM offers equivalent functionality through separate settings and APIs, together with OpenPipeline. This new functionality is described in Capture event and session properties for web frontends and Capture event and session properties for mobile frontends. The following sections outline the migration for web and mobile frontends.
Migrate user action properties
On web frontends, how you migrate a user action property depends on its expression type.
| Expression type in RUM Classic | Migration to RUM |
|---|---|
CSS selector | Add a capture rule with a CSS selector processing step. |
JavaScript variable | Add a capture rule with an Access property processing step. |
JavaScript API | Report the property via the new RUM JavaScript API as described in Capture event and session properties for web frontends. |
Meta tag | Add a capture rule with a CSS selector processing step for the meta tag, followed by a DOM attribute processing step for the |
Cookie value | Add a capture rule with a Cookie processing step. |
Query string | Add a capture rule with an Access property processing step for |
On mobile frontends, migrate properties with the expression type SDK reported value by reporting them via the new RUM APIs as described in Report properties via the API.
RUM does not support properties of the expression types Server-side request attribute and XHR/fetch response header at this point.
Migrate user session properties
To migrate your session properties, set them in one of two ways:
Migrate user tags
To migrate your user tags, populate the user identifier of a session in one of two ways:
- Report it with the
identifyUsermethod of the new RUM JavaScript API or the new mobile RUM APIs. - Enrich it from an event property in OpenPipeline. For details, see the instructions for web and mobile frontends.
Ready for more?
Once you have completed all steps for upgrading RUM data capturing, continue with upgrading data processing.