feat(telemetry): Capture failing resource URL on DOM event promise rejections

[sentry]

DESCRIBE YOUR PR

Problem

In Chrome, when a resource fails to load (such as a <link> stylesheet or a script) and rejection is triggered, the promise rejection reason is a DOM Event rather than an Error. This leads to Sentry events serializing merely as [object HTMLLinkElement], obscuring the actual URL of the failing asset and leaving the root cause unidentified.

Solution

Adds a beforeSend hook in src/instrumentation-client.ts to inspect unhandled promise rejections originating from DOM Events with an HTMLElement target. It extracts href or src attributes and tags the Sentry event with failing_resource_url and failing_resource_tag, along with snippet details in extra.failing_resource_element to make failing assets diagnosable.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

• Urgent deadline (GA date, etc.): YYYY-MM-DD
• Other deadline: YYYY-MM-DD
• No deadline: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 19, 2026 2:58pm UTC
sentry-docs	Ready	Preview	Oct 19, 2026 2:58pm UTC

[github-actions]

Please update the IS YOUR CHANGE URGENT? section of the PR description:

• Select exactly one option.
• If you selected an urgent or other deadline, provide the date as YYYY-MM-DD.

This information helps the Docs team prioritize your review.

[cursor]

The plan checks failing-resource tags on Event errors, accepted client errors, and page-load volume. An issue escalates when Event errors continue without those tags. An issue also escalates when accepted client errors fall while page loads hold.

Services: sentry-docs, develop-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

Unhandled promise rejections from failed DOM resource loads now carry resource URL tags on the error event. The hook sets failing_resource_url and failing_resource_tag. It also stores a short HTML snippet in extra.failing_resource_element. sentry-docs and develop-docs must deploy before this change is live. Both sites ship the same src/instrumentation-client.ts file.

Risk

If beforeSend throws, the SDK drops that error event. On-call then loses client error reports while pages still load. If client init fails to load, page-load traces also fall. The URL tag has high cardinality. The hook can tag any DOM Event whose target is an HTMLElement.

Intended effect

Production errors of type Event must start carrying failing_resource_url. That tag is new. Its pre-deploy count is zero. That zero is the baseline, not a gap. The tag increments when a resource load failure rejects with a DOM Event. That is an expected case. Do not use hold at 0 as the rule. Pair the tag with Event error volume. Absent: Event errors continue and the tagged count stays at zero.

Signal	Baseline	Rule	Source
Production errors with failing_resource_url, project docs	0 events in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z. 0 events in 2026-10-17T14:54:00Z to 2026-10-18T14:54:00Z.	Rise above 0. Confirmed when tagged events are a share of error.type:Event volume.	Sentry org sentry, project docs. Query environment:production AND has:tags[failing_resource_url].
Production error.type:Event errors, project docs	57 events in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z, 0.41% of pageload plus navigation spans. 11168 events in 2026-10-17T14:54:00Z to 2026-10-18T14:54:00Z, 72% of those spans. The prior window was an Event storm.	This is the volume path. Tagged count at 0 while this volume holds is absent.	Sentry org sentry, project docs. Query environment:production AND error.type:Event.
Production errors with failing_resource_url, project develop-docs	0 events in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z. error.type:Event was 0 in that window and 4 in the prior 24h.	Rise above 0 if Event errors occur. If Event count stays 0, leave this ship unknown.	Sentry org sentry, project develop-docs. Query environment:production AND has:tags[failing_resource_url].

Regression watch

This hook does not stop resource load failures. A new Event storm is not a regression of this change. Watch client errors that are not type Event. Watch page-load volume. A throw in beforeSend drops reports while pages still load.

Signal	Baseline	Rule	Source
Pageload plus navigation span count, project docs	13833 spans in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z. 15520 spans in 2026-10-17T14:54:00Z to 2026-10-18T14:54:00Z. Band 13833-15520.	Hold in that band. A fall below the band is a client init failure.	Sentry org sentry, project docs. Query environment:production AND span.op:[pageload,navigation].
Accepted production errors that are not error.type:Event, project docs	114 events in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z, 0.82% of pageload plus navigation. 39 events in 2026-10-17T14:54:00Z to 2026-10-18T14:54:00Z, 0.25% of those spans. Rate band 0.25%-0.82%.	Hold in that rate band. A rise above the band is new client breakage. A fall toward 0 while page loads hold means beforeSend dropped events.	Sentry org sentry, project docs. Production error count minus error.type:Event.
Accepted production errors, project develop-docs	34 events in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z. 11 events in 2026-10-17T14:54:00Z to 2026-10-18T14:54:00Z.	Hold near the last-24h weekday level. A fall toward 0 while page loads hold is lost error capture.	Sentry org sentry, project develop-docs. Query environment:production.
Pageload plus navigation span count, project develop-docs	1713 spans in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z. 744 spans in 2026-10-17T14:54:00Z to 2026-10-18T14:54:00Z. Last window includes Monday traffic. Prior window is Sunday.	Do not treat the Monday rise as a regression. A fall below 744 while weekday traffic exists is a client init failure.	Sentry org sentry, project develop-docs. Query environment:production AND span.op:[pageload,navigation].

Not observable

The string HTMLLinkElement is not in current production error messages. Count was 0 in 2026-10-18T14:54:00Z to 2026-10-19T14:54:00Z. Sentry stores these failures as error.type:Event instead. Whether originalException.target is an HTMLElement is not visible until the new tag exists. develop-docs had 0 Event errors in the last 24h, so that ship may stay unknown. Discard reasons in the last 24h were event_processor, network_error, and ingest filters. A before_send drop reason did not appear.