docs(span-links): Add server_request link type

develop-docs/sdk/telemetry/traces/span-links.mdx

@@ -143,11 +143,12 @@ Links that are stored in child spans are serialized in `spans[i].links`.
 Links don't require a special meaning or type but if necessary (e.g. for identifying special links in the product), set the `sentry.link.type` attribute on the link to define the link type.
 Any string can be used, but these types have predefined meanings:
 
-| `sentry.link.type` | Usage                                                                                                        | UI Implications                                                                                   |
-|--------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
-| "previous_trace"   | Linking e.g. a navigation span to the previous page load span.                                               | Used to query linked traces. Shows a button to go to linked previous trace in the trace explorer. |
-| "cache_origin"     | Linking a span that reads a cached value to the trace that produced that value (e.g. server-side rendering). | Used to navigate from a cache-hit span to the origin trace.                                       |
-| "message_origin"   | Linking a span that processes a queue message to the span that published the message (e.g. a queue job).     | Used to navigate from a consumer span to the producer trace.                                      |
+| `sentry.link.type` | Usage                                                                                                                              | UI Implications                                                                                   |
+|--------------------|------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
+| "previous_trace"   | Linking e.g. a navigation span to the previous page load span.                                                                     | Used to query linked traces. Shows a button to go to linked previous trace in the trace explorer. |
+| "cache_origin"     | Linking a span that uses a cached value (e.g. a cache read, or a page load of a reused page) to the span that produced that value. | Used to navigate from a cache-hit span to the origin trace.                                       |
+| "message_origin"   | Linking a span that processes a queue message to the span that published the message (e.g. a queue job).                           | Used to navigate from a consumer span to the producer trace.                                      |
+| "server_request"   | Linking a page load span to the server request for its document, when the trace context arrived too late to continue it.           | Used to navigate from a page load span to the trace of its server request.                        |
 
 ### `previous_trace`
 
@@ -197,7 +198,7 @@ span.addLink({
 ```
 
 One trace can read multiple cache entries. Each cache-read span carries its own link.
-In case the entire response is the cached unit (for example, a cached HTML page) the link belongs on the root span instead.
+If the entire response is the cached unit (for example, a cached HTML page), the link belongs on the root span of the serving trace instead.
 
 To attach the link on a cache hit, the SDK must record trace context at cache-fill time:
 
@@ -210,6 +211,16 @@ The origin trace may be negatively sampled. The link is still added, with `sampl
 
 A background revalidation (for example, stale-while-revalidate) starts its own trace rather than continuing the serving trace, and becomes the origin for future cache hits.
 
+#### Page Loads of Reused Pages
+
+A server can render a page, or a static part of it (a shell), once and reuse the HTML for later requests. Examples are an ISR page or the shell of a partially prerendered page.
+The page load span of such a page uses HTML that an earlier render produced, so that render is the cache origin of the page load span.
+
+- Send the origin with the reused HTML, but not as `sentry-trace`. Every visitor gets the same HTML, so with `sentry-trace` every visitor would continue the trace of one earlier request. For example, the Next.js SDK uses a `sentry-cache-origin` meta tag.
+- Add the link at span start.
+- If the SDK knows how the server rendered the page, set [`page.server_rendering.type`](https://conventions.sentry.dev/attributes/page/#page-server_rendering-type) at span start. Then `tracesSampler` and `ignoreSpans` can use it.
+- If the server renders the other parts of the page for the current request (`partially_static`), the page load span continues the trace of that request as usual. The `cache_origin` link points only to the render of the reused part.
+
 ### `message_origin`
 
 When a consumer processes a message, the work often runs long after the producer published it, in another process, and with a different sampling decision.
@@ -239,6 +250,38 @@ span.addLink({
 
 The producer trace may be negatively sampled. The link is still added, with `sampled: false` from the stored span context (same behavior as `previous_trace`).
 
+### `server_request`
+
+A page load span continues the trace of the server request for its document, if the SDK reads the trace context of that request (e.g. from a `sentry-trace` meta tag) before the span starts.
+With streamed HTML, the context can arrive later. For example, the server first sends a prerendered shell. The part that the server renders for this request comes later, and it carries the context.
+A started span cannot move to another trace, so the page load span stays in its own trace.
+
+A `server_request` link connects such a page load span to the server request for its document:
+
+```ts
+pageloadSpan.addLink({
+  context: serverRequestSpanContext, // parsed from the late `sentry-trace` value
+  attributes: {
+    'sentry.link.type': 'server_request'
+  }
+})
+```
+
+- Add the link only when the page load span could not continue the trace. A page load span that continues the trace of its server request needs no link.
+- Add the link to the page load root span, and only while that span is still recording.
+- Use only the trace context of the request for this document. Trace context in a part of the page that the server reused belongs to an earlier request. Use `cache_origin` for it.
+
+The server request may be negatively sampled. Add the link anyway, with `sampled: false` from the trace context (same behavior as `previous_trace`).
+
+#### `server_request` or `cache_origin`
+
+Both types can link a page load span to a server span, but the linked spans have different roles:
+
+- `server_request`: the linked span handled the request for the document of this page load. It would be the parent of the page load span if its trace context had arrived in time.
+- `cache_origin`: the linked span rendered HTML that the server reused from an earlier request. It is never the parent of the page load span.
+
+A page load span can have both links. For example, the page reuses a prerendered shell (`cache_origin`), and the trace context of the part that the server renders for this request arrives late (`server_request`).
+
 ## Usage Example
 
 Adding span links should be possible at span start time, as well as when holding a reference to the span.