Migrate to Dynatrace New RUM Experience; single loading mechanism

[redbugz]

Summary

Migrates Frontier apps to the Dynatrace New RUM Experience (RUM on Grail) and reduces agent loading from three treatments across two feature flags to one flag with three states. Fixes a production 500, removes ~105 KB of dead agent bootstraps, and moves maintainer tooling out of the published package. Ships as @fs/react-scripts 8.17.0.

Full analysis: Dynatrace RUM: Loading Mechanisms & Agent Management (FRDOCS). Decision record in-repo: packages/react-scripts/tools/dynatrace/DYNATRACE_RUM_MECHANISMS.md.

What ships

Treatment	Renders	Role
off	nothing	Kill switch. Defined in int, beta and prod
asyncCS-inline	versioned OneAgent tag + SRI, sync	Retained fallback
anything else	_complete.js from the global CDN, async	Default

frontier_snow_dynatraceNewRUM is removed. It never controlled New RUM — both branches emitted the same URL and it only toggled async. New RUM enablement is the tenant's enabledOnGrail setting, per application, no deploy.

Reasoned Changes

Single loading mechanism, fail-open default (dynatrace.ejs)

What: Replaced six code paths (3 treatments × old/new RUM) with two. The default is a fallthrough, not an equality check on global-cdn.

Why: _complete.js is the only mechanism that tracks tenant configuration without a react-scripts release. Sampling production during the evaluation found two of the three treatments serving a RUM agent artifact dated 2022-11-04 — refreshing a self-hosted artifact required a fetch-script run, a release, and a redeploy of every consuming app, and that chain had not completed since 2022.

The fallthrough is deliberate: retired treatment names, a renamed flag, and a Split outage returning control must all still load RUM. Failing closed produces a silent monitoring gap, which is the one failure mode invisible in the data itself. There is a comment saying so — please don't tidy it into === 'global-cdn'.

Retained sync SRI arm as the fallback

What: Kept one non-default mechanism: the versioned OneAgent tag + SRI, loaded synchronously, under the existing asyncCS-inline treatment name.

Why: It covers both documented revisit triggers at once — immutably cached for a year (if Dynatrace never adds a cache validator to _complete.js) and synchronous (no blind window if async proves to lose early interactions). One arm rather than two.

The treatment name is historical and describes neither its load mode nor its format; renaming would need a coordinated Split-plus-deploy change.

Deleted all RUM Classic code paths (−219 lines, ~105 KB)

What: Removed edgeUrls, the old cdnUrls, and the three _inline_*.ejs bootstraps.

Why: Inlining is permanently ruled out for New RUM, not just deferred. EJS include() compiles the file as a template and the minified agent contains the EJS open-delimiter sequence inside a character-class string — this caused a production 500 (Could not find matching close tag for "<%"). It also re-shipped 300–460 KB in every HTML response with no caching.

Async readiness helper (layout.ejs)

What: Added dtWhenReady(which, fn) for both RUM APIs; enableManualPageDetection and window.dtinfo.appName no longer sit behind if (window.dtrum).

Why: That guard is always false under async loading, so both were silently inactive on the async treatments — manual page detection quietly fell back to automatic, and dtinfo.appName was never set. Verified fixed on int (see Testing).

Maintainer tooling moved out of the published package

What: fetch-dynatrace-scripts.js, its config artifact, and the RUM docs moved from scripts/ to tools/dynatrace/.

Why: scripts/ is in package.json files, so all of it was being published to consumers — including a script that needs a Dynatrace API token, AWS credentials and keychain access, and that carries internal infrastructure details (S3 bucket, tenant URL, keychain service names, the three APPLICATION-* entity IDs). tools/ is not in files, so exclusion is by construction rather than by remembering a negation pattern.

Published package: 119 files / 392 KB → 104 files / 247 KB. The only Dynatrace file still shipping is dynatrace.ejs, which consumers actually render.

Decision record and measurement harness

What: DYNATRACE_RUM_MECHANISMS.md (option matrix, candidates evaluated and rejected, revisit triggers, revival recipe) and beacon-harness/ with retained raw JSONL.

Why: The rejected candidates — inline bootstrap, self-hosted agent, auto-injection — each had a real case for them and lost for recorded reasons. Without that written down they get re-proposed. The harness measured New RUM's ~2.3× per-session upload increase and is the tool for re-verifying it after prod enablement.

Measurements behind the decision

Agent FCP cost	≈ download time (178 KB @ 205 KB/s → 869 ms predicted, 852 ms measured), stable across a 50× bandwidth range
Loading mechanism	moves FCP by tens of ms — inside run-to-run variance
Agent payload	moves FCP by hundreds of ms — the actual lever
Session Replay module	29,362 bytes gzipped ≈ +140 ms FCP
Enabling New RUM on prod	+59,302 bytes ≈ +290 ms FCP (51% payload increase)
Beacon upload	New RUM adds an unsampled ~19.7 KB/session channel alongside Classic — ~2.3× total
_complete.js caching	max-age=86400, no ETag/Last-Modified → full re-download every 24 h

Performance was a tie across mechanisms, so the decision was made on maintenance and freshness.

Risk Assessment

Behaviour change on deploy: the tag becomes async. Production currently renders it synchronously in <head>, so every page render blocks on js-cdn.dynatrace.com. Async removes that render-path dependency at no measured FCP cost, but introduces a blind window — measured at 925 ms on int — during which early clicks, XHRs and errors are not captured. CWV and navigation timing are recoverable retroactively via buffered PerformanceObserver, so the cost is early interactions, not page-performance data.

Revert path: flip the flag to asyncCS-inline (sync, no blind window) or off. No deploy required.

Watch after rollout: RUM session volume for a step change across the async transition. Note the healthy sessions-per-render baseline is ~33%, not 100% — costAndTrafficControl: 33 means one session in three is monitored by design.

Ordering constraint for prod: agent 1.341 is missing three of the four Gen3 API methods the RUM JavaScript SDK requires; 1.343 has all four. Prod is on PREVIOUS_STABLE. Move the version channel and re-run the fetch script before enabling enabledOnGrail, or API-reported session properties silently will not land.

Not addressed here: layout.ejs injects only when NODE_ENV === 'production' and only where the layout renders, so custom error pages and 500s get no RUM. Pre-existing and independent of mechanism choice.

Testing

Verified on frontier-app-react int with 8.17.0-alpha.17 deployed:

tag rendered      _complete.js with async          ✓
window.dtrum      object, enableManualPageDetection present   ✓
window.dynatrace  object, all four Gen3 methods present       ✓
dtWhenReady       fires for both classic and grail            ✓
dtinfo.appName    "frontier-app-react" (set unconditionally)  ✓
agentReadyMs      925
removed cleanly   no ruxitagent / __dTCookie / rum_loading_mechanism  ✓

Template rendering asserted for every flag state, including unknown ones:

off             -> no agent
asyncCS-inline  -> SRI, SYNC, +integrity hash
global-cdn      -> complete.js async
asyncCS-script  -> complete.js async   (retired name, fail-open)
control         -> complete.js async   (Split outage, fail-open)
undefined       -> complete.js async

npm pack --dry-run confirms zero files from tools/ in the published package.

Review hotspots

1. The fallthrough default in dynatrace.ejs — intentional, see the comment above it.
2. tools/ is not in package.json files — that is what excludes maintainer material. Adding tools to files would silently re-publish it.
3. cdnConfigNew strings were not retyped — the diff edits around them, so the ~1 KB data-dtconfig values are byte-intact.

Follow-ups (not in this PR)

• Dynatrace support ticket filed for the missing ETag on _complete.js. If granted, the retained SRI arm can be removed entirely.
• Re-run fetch-dynatrace-scripts.js immediately after prod moves to LATEST_STABLE — prod's SRI fallback is still 1.341 and the retained arm does not advance on its own.
• Confirm Snow reads locals.dynatrace.* in production (fs-webdev/snow feat/dynatrace-rum-config-injection, not merged). Until then every value comes from the baked fallback.

[Copilot]

Pull request overview

This PR upgrades Dynatrace RUM to a newer agent version and switches new-RUM loading to <script> tags (avoiding EJS include() compilation failures), adds runtime-config fallbacks via locals.dynatrace.*, and introduces tooling/docs to automate future RUM updates and publishing of a config artifact.

Changes:

• Reworked dynatrace.ejs to support dual-flag rollout (mechanism vs version) and load new RUM exclusively via script tags with SRI/config support.
• Added a fetch/publish automation script plus a generated dynatrace-rum-config.json artifact for Snow runtime injection.
• Bumped @fs/react-scripts to 8.17.0 and documented/released the change.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/react-scripts/layout/views/partials/dynatrace.ejs	Adds new-RUM script-tag branches, locals-first runtime config, and dual-flag gating.
packages/react-scripts/scripts/fetch-dynatrace-scripts.js	New automation script to fetch Dynatrace tags, update EJS fallbacks, generate config JSON, and publish to S3.
packages/react-scripts/scripts/dynatrace-rum-config.json	Generated per-env CDN URL/SRI/config values for Snow to consume at runtime.
packages/react-scripts/scripts/DYNATRACE_RUM_UPDATE.md	Operator runbook for fetching/publishing and validating treatment mappings.
packages/react-scripts/package.json	Version bump to 8.17.0.
package-lock.json	Lockfile version update for the react-scripts package entry.
CHANGELOG-FRONTIER.md	Release notes for 8.17.0 Dynatrace RUM changes.

Comments suppressed due to low confidence (3)

packages/react-scripts/scripts/DYNATRACE_RUM_UPDATE.md:81

• This relative link points to ./partials/dynatrace.ejs, but the actual file lives under layout/views/partials/dynatrace.ejs. As written, the link is broken.

Two flags drive the experiment (see [dynatrace.ejs](./partials/dynatrace.ejs)):

packages/react-scripts/scripts/DYNATRACE_RUM_UPDATE.md:184

• These relative links are incorrect from the scripts/ directory. dynatrace.ejs is under layout/views/partials/, and fetch-dynatrace-scripts.js is the current file (same directory), so the links should be updated to avoid 404s in the runbook.

- [dynatrace.ejs](./partials/dynatrace.ejs) - Main RUM configuration file
- [fetch-dynatrace-scripts.js](./fetch-dynatrace-scripts.js) - The fetch script itself

packages/react-scripts/scripts/DYNATRACE_RUM_UPDATE.md:73

• The example snippet treats cdnIntegrityNew as a single string, but dynatrace.ejs defines cdnIntegrityNew as an environment-keyed object (and integrity values may differ per env). The example should reflect the actual shape.

```javascript
const cdnUrlsNew = {
  int: '...',    // Copy from script output
  beta: '...',   // Copy from script output
  prod: '...'    // Copy from script output

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.