[fateeand]

Summary

Backend logs and AWS X-Ray traces can now be tied to the journeys the library records, and embedded fragments get the same HTTP tracing as the shell.

• Scenario header (new, opt-in). Requests marked with a scenario carry X-Uwt-Scenario-Id, so the backend can log it and add it to its X-Ray trace as the scenarioId annotation.
• X-Ray on relative URLs (fix, breaking). HttpClient passes URLs like /api/... unresolved, and the default X-Ray rule only matched absolute URLs. So most HttpClient requests never got X-Amzn-Trace-Id. They do now.
• Fragments traced by the shell (new). The RUM client runs only in the shell, and a fragment's iframe has its own fetch/XHR, so fragment requests were invisible to RUM. The shell now applies the RUM client's own fetch/XHR plugins to each fragment's window, so fragment requests get the X-Ray header, RUM HTTP events and the shell's session.
• Fragments follow the shell's channel (new). A fragment with no channel set now uses the channel of the shell it's nested in. A per-tab channel is now one line in the shell; fragments need no setup.

Changes

Main entry (@absaoss-cps/ngx-ui-watchtower)

• uwtScenarioHeaderInterceptor({ headerName? }) and uwtScenarioContext(scenario), plus UwtScenarioHeaderOptions and UWT_DEFAULT_SCENARIO_HEADER ('X-Uwt-Scenario-Id').
• The header goes only on marked, same-origin requests, only while telemetry is on, only in a browser, and only when the request doesn't already carry it.
• The interceptor never changes how a request succeeds or fails. Settling the scenario stays with the caller or traceScenario.
• The 'broadcast' sink is created at startup. It hands its window to the shell for HTTP tracing, and uses the shell's channel unless one is set explicitly.
• UwtTelemetryBroadcastHost publishes its channel name for fragments nested in its page. A host never takes a channel from a page above it.

RUM entry (@absaoss-cps/ngx-ui-watchtower/rum)

• The default X-Ray rule resolves each URL the way the browser does before comparing origins, so relative URLs count as same-origin. Lookalikes such as /\host, a leading space or a tab are resolved correctly.
• provideUwtTelemetryRumSink({ xRayExcludeUrls }) (UwtRumSinkOptions) keeps the X-Ray header off listed URLs, e.g. an endpoint that redirects to another origin.
• The sink traces fragment windows that join it, and releases a fragment when its iframe is removed or its app is destroyed, but not on a back/forward-cache visit. This works with Web Fragments, which reroutes listeners added through a fragment window's own addEventListener.
• Fragment tracing doesn't run while the client is switched off (enableRumClient: false) or without http telemetry.

Shell handle. A single library-owned handle on the shell's window (Symbol.for('ngx-ui-watchtower.host')) carries channelName (set by the broadcast host) and traceHttp (set by the RUM sink). Fragments find each field by walking up window.parent, skipping frames from other origins.

Compatibility

• API: additive only. Nothing exported was removed or changed. provideUwtTelemetryRumSink() gains an optional parameter.
• Channel discovery changes nothing for existing setups. An explicit fragment channel still wins, the default channel is unchanged, and followers outside the shell's page (popups, other tabs) behave as before.
• The one change: a nested fragment that set no channel under a shell with a custom channel used to be silently lost. It now reaches its shell.
• Mixed shell/fragment versions: apps using the documented window.__uwtTelemetryChannel pattern should keep that global until every fragment is upgraded (see DESIGN.md §13, "Upgrading from the manual pattern").
• Breaking: see the footer.
• Behaviour changes to call out in the release notes:
  • Backends that follow the incoming trace header's sampling decision (X-Ray SDK and OpenTelemetry defaults) will record a backend trace for every request in a recorded RUM session, not just their own sampled share. That raises X-Ray volume and cost.
  • Fragment requests now count against the shared RUM session's event budget (200 by default), like the shell's.

Closes #28

BREAKING CHANGE: the X-Ray trace header (X-Amzn-Trace-Id) is now sent on
same-origin requests with relative URLs (e.g. HttpClient calls to /api/...)
and on requests from embedded fragments, not only on absolute same-origin
URLs. A same-origin endpoint that redirects to another origin passes the
header on, and the request fails if that origin's CORS rules don't allow
it. To fix: allow x-amzn-trace-id at the target, list the path in
provideUwtTelemetryRumSink({ xRayExcludeUrls: [...] }), or set
enableXRay: false.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	97.3% (+0.32% 🔼)	1407/1446
🟢	Branches	95.1% (-0.29% 🔻)	738/776
🟢	Functions	97.04% (+0.2% 🔼)	360/371
🟢	Lines	97.63% (+0.27% 🔼)	1358/1391

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / uwt-host-handle.util.ts	100%	87.5%	100%	100%
🟢	... / uwt-scenario-http.ts	100%	92.31%	100%	100%
🟢	... / uwt-rum-sink-options.ts	100%	100%	100%	100%
🟢	... / uwt-rum-realms.ts	97.37%	95.45%	96.43%	97.18%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / uwt-broadcast-host.service.ts	97.48% (+1.36% 🔼)	90.91% (-0.2% 🔻)	100%	97.37% (+1.45% 🔼)
🟢	... / uwt-broadcast.messages.ts	98.86% (+0.07% 🔼)	98.1% (-0.88% 🔻)	100%	98.81% (+0.08% 🔼)
🟢	... / uwt-rum-telemetry.sink.ts	95.72% (+0.48% 🔼)	92.31% (-0.25% 🔻)	93.75% (+0.73% 🔼)	97.21% (+0.31% 🔼)

Test suite run success

785 tests passing in 26 suites.

Report generated by 🧪jest coverage report action from b675aea

[Copilot]

🔵 Needs a closer look

Human confirmation is warranted because the change relies on aws-rum-web 3.2.1 plugin internals and cross-realm iframe behavior that mocked tests cannot fully validate without real-browser runtime checks.

No open issues 🎉

What changed in this PR

This pull request adds scenario-to-backend correlation, fixes X-Ray tracing for relative URLs, and extends RUM HTTP tracing and channel discovery to embedded fragments.

Changes:

• Adds opt-in scenario HTTP context and interceptor APIs.
• Resolves relative URLs for X-Ray matching and supports configurable exclusions.
• Shares shell RUM instrumentation, sessions, and broadcast channels with fragments, including lifecycle cleanup.

File	Description
projects/​ngx-ui-watchtower/​src/​public-api.ts	Exports the scenario HTTP correlation APIs and types.
projects/​ngx-ui-watchtower/​src/​lib/​sinks/​uwt-broadcast/​uwt-host-handle.util.ts	Provides shared shell-handle and ancestor lookup utilities.
projects/​ngx-ui-watchtower/​src/​lib/​sinks/​uwt-broadcast/​uwt-host-handle.util.spec.ts	Tests shell-handle lookup, cross-origin traversal, and fragment HTTP joining.
projects/​ngx-ui-watchtower/​src/​lib/​sinks/​uwt-broadcast/​uwt-broadcast.spec.ts	Tests fragment HTTP tracing and shell-channel inheritance.
projects/​ngx-ui-watchtower/​src/​lib/​sinks/​uwt-broadcast/​uwt-broadcast.messages.ts	Adds shell-channel discovery for broadcast connections.
projects/​ngx-ui-watchtower/​src/​lib/​sinks/​uwt-broadcast/​uwt-broadcast-telemetry.sink.ts	Joins fragment windows to shell HTTP tracing. Review note: Moderate issue (1 vote): fragments can miss the RUM hook if initialized during the sink’s setup window; an explicit readiness notification or retry is needed.
projects/​ngx-ui-watchtower/​src/​lib/​sinks/​uwt-broadcast/​uwt-broadcast-host.service.ts	Publishes and withdraws the shell’s broadcast channel. Review note: Moderate issue (1 vote): multiple host instances can overwrite shared-handle ownership and remove a surviving host’s channel.
projects/​ngx-ui-watchtower/​src/​lib/​scenario/​uwt-scenario-http/​uwt-scenario-http.ts	Implements opt-in, same-origin scenario request headers.
projects/​ngx-ui-watchtower/​src/​lib/​scenario/​uwt-scenario-http/​uwt-scenario-http.spec.ts	Tests scenario headers, retries, origins, telemetry state, and SSR behavior.
projects/​ngx-ui-watchtower/​src/​lib/​providers/​uwt-telemetry-common.providers/​uwt-telemetry-common.providers.ts	Eagerly initializes broadcast sinks for fragment tracing.
projects/​ngx-ui-watchtower/​src/​lib/​providers/​uwt-broadcast-log-api.provider/​uwt-broadcast-log-api.provider.ts	Makes fragment log forwarding follow the shell channel.
projects/​ngx-ui-watchtower/​rum/​src/​public-api.ts	Exports UwtRumSinkOptions.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum.providers/​uwt-rum.providers.ts	Accepts and provides RUM sink options.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum.providers/​uwt-rum.providers.spec.ts	Tests RUM option provisioning.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum-telemetry.sink/​uwt-rum-telemetry.sink.ts	Configures relative-URL X-Ray matching, exclusions, and fragment realm management.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum-telemetry.sink/​uwt-rum-telemetry.sink.spec.ts	Tests X-Ray matching, exclusions, and RUM lifecycle behavior.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum-sink-options/​uwt-rum-sink-options.ts	Defines configurable X-Ray exclusion options.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum-realms/​uwt-rum-realms.ts	Applies RUM fetch/XHR plugins to fragment windows and releases them.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum-realms/​uwt-rum-realms.spec.ts	Tests cross-realm fetch/XHR instrumentation and cleanup.
projects/​ngx-ui-watchtower/​rum/​src/​lib/​uwt-rum-credentials/​uwt-rum-credentials.ts	Documents HTTP tracing coverage for relative URLs and fragments.
projects/​ngx-ui-watchtower/​README.md	Documents X-Ray propagation, scenario headers, exclusions, and fragment channels.
projects/​ngx-ui-watchtower/​DESIGN.md	Updates API, correlation, realm, channel, and operational design documentation.

_{Review effort: Lite}