feat(dynamic-sampling): make docs simpler and easier to understand

[shellmayr]

• Remove references to transaction rules, we are in the process of removing them
• Simplify the architecture documentation - there's a lot of things in there that are not necessary for understanding
• Remove the concept of fidelity, we don't need this for understanding, and it complicates things
• Fix some URLs

Closes TET-2348

[linear-code]

TET-2348

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview, Comment	May 13, 2026 1:32pm
sentry-docs	Ready	Preview, Comment	May 13, 2026 1:32pm

[sentry]

Bug: Renaming fidelity-and-biases.mdx to biases.mdx broke existing redirect chains and internal links because the necessary redirects were not added to middleware.ts.
_{Severity: MEDIUM}

Suggested Fix

In middleware.ts, add two redirects. First, a redirect from the old final path /application-architecture/dynamic-sampling/fidelity-and-biases/ to the new path /application-architecture/dynamic-sampling/biases/. Second, a new redirect from the short path /dynamic-sampling/biases/ to the full path /application-architecture/dynamic-sampling/biases/ to fix the internal link.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: develop-docs/application-architecture/dynamic-sampling/biases.mdx#L1-L5

Potential issue: Renaming the file `fidelity-and-biases.mdx` to `biases.mdx` has broken
several navigation paths. First, the existing redirect chain for the old URL
(`/dynamic-sampling/fidelity-and-biases/` ->
`/application/dynamic-sampling/fidelity-and-biases/` ->
`/application-architecture/dynamic-sampling/fidelity-and-biases/`) now leads to a 404
page because the final destination was moved without an additional redirect. Second, the
'next page' link in `the-big-picture.mdx` points to the new short path
`/dynamic-sampling/biases/`, but no corresponding redirect was added in `middleware.ts`
to map it to the full path. Both external links and internal navigation will be broken.

Also affects:

• develop-docs/application-architecture/dynamic-sampling/the-big-picture.mdx:99

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[Dav1dde]

This seems a lot easier to understand for people who haven't fully embraced DS (yet), it does skip over some details which before were mentioned (e.g. how Relay behaves under certain circumstances/edge cases). Likely, this is a good thing, as it may be better to actually confirm edge cases with the code instead.

Curious what others think!

[loewenheim]

Suggested change

Dynamic Sampling defines a target sample rate for each project that specifies the amount of data to be retained. This target sample rate is a number between 0 and 1. This target sample rate is used to calculate the sample rate for each event, based on the project and transaction that the event belongs to. Dynamic Sampling does not use the project or transaction of the event, but rather the project and transaction that the trace was started from. The reason for this is that the system works on trace level, and not on an event level. So in order to retain an entire trace, decisions can only be made based on the information that is available at the start of the trace.

Dynamic Sampling defines a target sample rate for each project that specifies the amount of data to be retained. This target sample rate is a number between 0 and 1. It is used to calculate the sample rate for each event, based on the project and transaction that the event belongs to. Dynamic Sampling does not use the project or transaction of the event, but rather the project and transaction that the trace was started from. The reason for this is that the system works on trace level, and not on an event level. So in order to retain an entire trace, decisions can only be made based on the information that is available at the start of the trace.

Also, the second sentence in here is a pretty close restatement of the first: "Dynamic Sampling does not use the project or transaction of the event, but rather the project and transaction that the trace was started from. The reason for this is that the system works on trace level, and not on an event level."

I think something like "This is because we want traces to be sampled or discarded in their entirety, not partially sampled" might be better.