docs(tracing): Consolidate span attribute guidance

[sfanahata]

DESCRIBE YOUR PR

Retires the standalone span metrics guides and consolidates their useful guidance into JavaScript and Python instrumentation docs. The new examples show how attributes help explain a slow operation in a trace and distinguish that use case from tracking standalone signals with Application Metrics.

Old SDK and concept URLs redirect directly to the relevant instrumentation sections. The legacy Python performance-measurements URL redirects to Python Application Metrics. Other SDKs have been updated to use the term "span attributes" instead of "span metrics".

IS YOUR CHANGE URGENT?

• No deadline: Not urgent, can wait up to 1 week+

SLA

Please allow the docs team up to 1 week to review this PR.

PRE-MERGE CHECKLIST

• 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

[cursor]

The change retires standalone span-metrics guides and sends those URLs to instrumentation sections. The plan watches retired-URL redirects, destination page traffic, 404s, and client errors. An issue escalates when 404s or client errors rise, or when retired URLs still return 200.

Services: sentry-docs.

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

Plan

What changed

Requests to retired span-metrics URLs now permanently redirect to JavaScript or Python instrumentation sections. Those sections now show how span attributes explain a slow operation in a trace. Python performance-metrics URLs now redirect to the Python metrics guide. Trace Explorer copy no longer treats span metrics as a separate stored product. This ships when sentry-docs deploys.

Risk

A bad redirect returns 404 for old links and search hits. A wrong destination sends readers to the wrong SDK section. A broken include can fail custom-instrumentation pages across many platforms. A failed MDX render errors the catch-all docs route /:path*?.

Intended effect

The new behavior is a permanent redirect off retired span-metrics URLs, while destination instrumentation pages still load. Traces are sampled at 30 percent. Metric counters are not. absent looks like http.client 200 on retired URLs staying in the 643 band while 308 stays at 0.

Signal	Baseline	Window	Rule	Source
http.client 308 on http.url:*span-metrics*	0	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Rise above 0 after deploy	Sentry org sentry project docs. Query: environment:production span.op:http.client http.url:*span-metrics* grouped by http.response.status_code
http.client 200 on http.url:*span-metrics*	643	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Fall below 643 toward 0	Same query. Pre-deploy only 200 appeared
Spans with http.url /platforms/javascript/tracing/instrumentation/	300 sampled	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Hold or rise above 300	Sentry org sentry project docs. Query: environment:production http.url:*javascript/tracing/instrumentation*
Spans with http.url /platforms/python/tracing/instrumentation/custom-instrumentation/	200 sampled	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Hold or rise above 200	Sentry org sentry project docs. Query: environment:production http.url:*python/tracing/instrumentation/custom-instrumentation*

Regression watch

Wrong redirects and broken includes show up as 404s and client errors on the docs catch-all route. Watch sibling platform 404s too, not only JavaScript.

Watch	Baseline	Window	Rule	Source
docs.page.not_found for requested_path platforms/javascript	72 per 24h. 7d total 400, about 57 per day	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Hold in 57-72 per 24h. Escalate above 72	Sentry org sentry project docs. Query: metric.name:docs.page.not_found AND environment:production grouped by requested_path
docs.page.not_found total	134 per 24h. Hourly 1-31. Peak 31 at 2026-10-04T23:00Z	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Hold in 1-31 per hour. Escalate if 24h count rises above 134	Same metric without path group
docs.page.not_found for requested_path platforms/python	2 per 24h. 7d total 13	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Hold in 2-3 per 24h. Escalate above 3	Same metric grouped by requested_path
Production errors on transaction /:path*?	139 of 140 errors in 24h. Hourly 1-18. Peak 18 at 2026-10-05T12:00Z. About 0.63 percent of 22187 docs.page.load	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Hold in 1-18 errors per hour. Escalate above 18 per hour or above 140 per 24h	Sentry org sentry project docs. Query: environment:production errors grouped by transaction
HTTP status 500 or higher	0	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Stay at 0	Sentry org sentry project docs. Query: production spans with http.response.status_code:>=500
p95 span.duration on transaction /:path*?	839ms	2026-10-04T17:55:00Z to 2026-10-05T17:55:00Z	Hold. Escalate if p95 rises above 839ms	Sentry org sentry project docs. Query: environment:production transaction:"/:path*?" p95 span.duration

If 404s rise, inspect logs for MDX file not found at runtime, returning 404. That log was 0 in this window.

Not observable

Whether the new examples teach the intended distinction is not in telemetry. Hash scroll to #adding-span-attributes is not in traces. Vercel edge 308 may not appear as an http.client span if the client only records the destination page.

[coolguyzone]

Looks good!

[vercel]

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

Project	Deployment	Actions	Updated
sentry-docs	Ready	Preview	Oct 6, 2026 6:46pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
develop-docs	Ignored	Preview	Oct 6, 2026 6:46pm UTC