docs(effect): Document opt-in for external span parents

[JPeer264]

DESCRIBE YOUR PR

SDK 11.3.0 ignores Tracer.externalSpan parents by default. Document SentryEffectExternalSpanLayer, which continues the external trace for the whole runtime or for a single effect, with setup snippets for Effect v3 and v4.

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
sentry-docs	Ready	Preview	Oct 2, 2026 8:05pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
develop-docs	Ignored		Oct 2, 2026 8:05pm UTC

[cursor]

The plan checks page loads on the JavaScript custom-instrumentation pages, client errors, and server 5xx. An issue escalates when those pages stop loading or client errors rise. New Effect code tabs can break the shared page.

Services: sentry-docs.

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

Plan

What changed

Readers of the Effect custom-instrumentation page now get setup for SentryEffectExternalSpanLayer. The new section is gated to the Effect platform and adds Effect v3 and Effect v4 snippets. This change is live after sentry-docs deploys.

Risk

The changed include is shared by every JavaScript guide page on this path. A bad MDX fence or code tab can fail those pages together. Effect visits are rare, so a render bug may first show on a sibling JavaScript page.

Intended effect

Telemetry does not record the new heading text. Treat successful page loads of the shared custom-instrumentation path as the reachable effect. Absent means those page loads drop to zero while site page loads hold, or the Effect URL returns 404.

Signal	Baseline	Rule	Source
Pageload and navigation spans for http.url:*distributed-tracing/custom-instrumentation*	33 sampled spans in 2026-10-01T19:57:00Z to 2026-10-02T19:57:00Z. Navigation p50 was 928ms. Pageload p50 was 15620ms and is pulled by a 30s cap.	Hold near 33 sampled spans. Confirmed if this volume holds after deploy. Absent if the count falls to zero while site page loads hold.	Sentry spans, org sentry, project docs, environment production. Sample rate 0.3. Query: (span.op:pageload OR span.op:navigation) environment:production http.url:*distributed-tracing/custom-instrumentation*
Effect custom-instrumentation pageload and navigation spans	0 spans in 2026-10-01T19:57:00Z to 2026-10-02T19:57:00Z. 3 spans in 2026-09-25T19:57:00Z to 2026-10-02T19:57:00Z.	Zero in 24h is normal. Confirmed if a visit after deploy completes. Do not treat continued zero as absent. Absent if this URL 404s or errors while sibling JavaScript pages load.	Sentry spans, org sentry, project docs, environment production. Query: (span.op:pageload OR span.op:navigation) environment:production http.url:*platforms/javascript/guides/effect/tracing/distributed-tracing/custom-instrumentation*
Site page loads docs.page.load	16751 counts in 2026-10-01T19:57:00Z to 2026-10-02T19:57:00Z	Hold this volume as the traffic denominator.	Sentry metrics, org sentry, project docs, environment production. Query: metric.name:docs.page.load metric.type:counter environment:production

Regression watch

A broken include can fail every JavaScript custom-instrumentation page, not only Effect. Watch client errors users would see, then 5xx and 404s on that path family. Algolia insights.algolia.io TypeErrors are existing noise. Do not treat those as this change.

Signal	Baseline	Rule	Source
Client error rate	0.95% in 2026-10-01T19:57:00Z to 2026-10-02T19:57:00Z. That is 160 errors over 16751 page loads. One window, so this band is not seasonal.	Hold near 0.95%. Detected if the rate rises well above this window.	Sentry errors count environment:production over docs.page.load in the same window. Org sentry, project docs.
TypeError events	57 events in the same 24h window. 37 were Algolia fetch failures. 14 were Cannot read properties of undefined (reading 'h6'). 6 were proxy.kapa.ai fetch failures.	Hold near 57. Ignore a rise that is only Algolia fetch failures. Detected if h6 or other render TypeErrors rise, or if TypeErrors appear on custom-instrumentation URLs.	Sentry errors, org sentry, project docs. Query: error.type:TypeError environment:production
Errors on custom-instrumentation URLs	0 events in 2026-10-01T19:57:00Z to 2026-10-02T19:57:00Z	Any new event is a regression.	Sentry errors, org sentry, project docs. Query: environment:production (url:*distributed-tracing/custom-instrumentation* OR url:*custom-instrumentation*)
HTTP 5xx server spans	0 spans in 2026-10-01T19:57:00Z to 2026-10-02T19:57:00Z	Any rise is a regression.	Sentry spans, org sentry, project docs. Query: span.op:http.server environment:production http.status_code:>=500 http.status_code:<600
docs.page.not_found	100 counts in 2026-10-01T19:57:00Z to 2026-10-02T19:57:00Z. Rate 0.60% versus 16751 page loads.	Hold near 100. Detected if 404s rise while site page loads hold.	Sentry metrics, org sentry, project docs. Query: metric.name:docs.page.not_found metric.type:counter environment:production

If the error rate rises, inspect logs and traces for CodeTabs and MDX render failures on distributed-tracing/custom-instrumentation URLs. Sibling pages in the last 24h window included node, firebase, fastify, javascript, vue, and react.

Not observable

The new heading and snippet text are not in telemetry. LCP for this path did not return a value. Pageload p95 is capped at 30s, so it is not a usable latency band.