feat(python): Add versioned span streaming pages for 3.0

[sentrivana]

The top-level Python SDK API for custom tracing instrumentation will be rewired to span streaming in the upcoming 3.0 major. Create a versioned copy of the relevant pages, once with the old API (<3.0), and one for 3.0+.

Direct link to preview:

• span streaming migration guide
• streamed spans page

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 19, 2026 9:32am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
develop-docs	Ignored	Preview	Oct 19, 2026 9:32am UTC

[cursor]

The change splits custom tracing docs into a current-version page and an older-version copy. The plan checks page loads on both paths, runtime 404 warnings, and client errors. An issue escalates when default pages stop loading, versioned pages 404, or client errors appear.

Monitoring in production

Services: sentry-docs.

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

Plan

What changed

Requests to the unversioned streamed-spans pages now describe stream mode as always on. Readers who pick the older SDK version get the prior opt-in API pages. Those versioned copies live at the __v2.x paths. sentry-docs must deploy before this change is live. develop-docs does not ship this docs-only path.

Risk

A missing new MDX file returns 404 when a reader picks the older version. A bad versioned link can send readers to a missing page. A render failure can break code tabs or the version picker on this path. Wrong copy can tell older-SDK readers to call APIs that do not exist yet.

Intended effect

The rewrite itself has no content signal. Use page loads to see that the pages still render. The new __v2.x paths start at zero. A later load above zero means a reader reached a new page. Zero after deploy is not absent if 404 warnings stay quiet.

absent looks like this. Other Python docs keep loading. These streamed-spans paths stay at zero or emit 404 warnings.

Signal	Baseline	Rule	Source
Page load on /platforms/python/tracing/streamed-spans/	10 per 24h and 23 per 7d. Observed daily rate 3-10.	Hold in the 3-10 per 24h band. absent if the count stays at 0.	Sentry org sentry project docs. Query metric.name:docs.page.load environment:production path:/platforms/python/tracing/streamed-spans/. Window 2026-10-06T13:15:49Z/2026-10-07T13:15:49Z and 2026-09-30T13:15:49Z/2026-10-07T13:15:49Z.
Page load on /platforms/python/tracing/streamed-spans/migration-guide/	10 per 24h and 23 per 7d. Observed daily rate 3-10.	Hold in the 3-10 per 24h band. absent if the count stays at 0.	Same source. Query metric.name:docs.page.load environment:production path:/platforms/python/tracing/streamed-spans/migration-guide/. Same windows.
Page load on __v2.x streamed-spans paths	0 per 7d. These pages are new.	confirmed if the count rises above 0. Stay-at-zero is unknown, not absent.	Same source. Query metric.name:docs.page.load environment:production path:*streamed-spans__v2.x*. Window 2026-09-30T13:15:49Z/2026-10-07T13:15:49Z.

Regression watch

This diff can 404 the new versioned files or throw on the version picker and code tabs. Watch client errors on this path first. Also watch the Python tracing sibling paths. A quiet success metric does not cover a 404.

Signal	Baseline	Rule	Source
Client errors on Python streamed-spans URLs	0 events per 24h. 0 errors in 20 page loads. Error rate 0%.	Hold at 0% per 24h. detected if the rate rises above 0%.	Sentry org sentry project docs. Query environment:production url:*platforms/python/tracing/streamed-spans*. Window 2026-10-06T13:15:49Z/2026-10-07T13:15:49Z.
Client errors on Python tracing URLs	0 events per 24h. 23 events per 7d. About 3 per day. 21 of the 7d events use title Event: Event \Event` (type=error) captured as promise rejection`.	Hold the 24h count in the 0-4 band. detected if it rises above 4.	Same source. Query environment:production url:*/platforms/python/tracing*. Windows 2026-10-06T13:15:49Z/2026-10-07T13:15:49Z and 2026-09-30T13:15:49Z/2026-10-07T13:15:49Z.
Runtime 404 warning MDX file not found at runtime	0 warnings per 24h and 0 per 7d.	Hold at 0. detected if a warning names a streamed-spans path.	Same source. Query severity:warn environment:production message:"*MDX file not found at runtime*". Windows 2026-10-06T13:15:49Z/2026-10-07T13:15:49Z and 2026-09-30T13:15:49Z/2026-10-07T13:15:49Z.
Page not found with requested_path:platforms/python	3 per 24h and 16 per 7d. Daily rate about 2-3.	Hold the 24h count in the 2-4 band. detected if it rises above 4. This path is coarse. Confirm with the 404 warning.	Same source. Query metric.name:docs.page.not_found environment:production requested_path:platforms/python. Windows 2026-10-06T13:15:49Z/2026-10-07T13:15:49Z and 2026-09-30T13:15:49Z/2026-10-07T13:15:49Z.

Not observable

The rendered API text is not in telemetry. A reader can still see the wrong version with healthy page loads. The has_versions page-load attribute is not queryable. docs.page.not_found keeps only the first two path segments. New __v2.x page loads may stay at zero if no reader picks that version.