RUM: document exclusion filters and restructure the retention filters page

[qsellem]

What does this PR do? What is the motivation?

Documents exclusion filters, a new type of RUM filter evaluated between the permanent and the custom retention filters, and reorganizes the retention filters page around the three filter types that now exist.

An event matching an exclusion filter is not evaluated against the custom retention filters, so it can never be the reason its session is retained. Today customers achieve this by repeating negative queries inside every filter — one org maintains the same bot exclusion across 179 custom retention filters — which is the pain this feature removes.

New page structure (previous order in parentheses):

Section	Change
Overview	edited — names the three filter types
How it works	edited and shortened
Types of filters	new — the path an event takes, plus a table of what a match does
Permanent retention filters	unchanged content, new screenshot
Exclusion filters	new, marked Preview, with the Error Tracking filter as a subsection
Custom retention filters	new wrapper around Excluding sessions using retention filters (was ##)
Setup	new — how to reach the page, with Creating a filter, Modifying filters and Capping retention with quotas as subsections
How retention filters work with replays	moved down
Cross-product retention filters, Best practices, API, Next steps	unchanged

Sections follow the order in which an event is evaluated: permanent, exclusion, custom.

The distinction the page now makes explicit: retention filters are session-scoped — one matching event retains the whole session. Exclusion filters are event-scoped — a matching event is skipped, but its session can still be retained by another event. This is the single most confusable part of the feature, so it gets a callout in Exclusion filters.

Other changes

• Rewrote Excluding sessions using retention filters rather than deleting it: in-query exclusions still work but only apply to the filter that contains them, with a pointer to exclusion filters for configuration-wide exclusion.
• Updated guide/retention_filter_best_practices.md to mention exclusion filters, and fixed its link to retention_filters/#logic — an anchor that does not exist on the page (now #how-it-works).
• Heading text for Modifying filters and Excluding sessions using retention filters is unchanged even though both are now nested, so existing deep links from the best practices guides still resolve.

Merge readiness

• Ready for merge

Remaining before merge:

1. Two screenshots still show the previous UI: modifying-filters.png, and the rum-without-limits-how-retention-filters-work-2.png flow diagram at the top of How it works, which still shows the two-stage model. The three filter-group screenshots and the permanent filters screenshot are updated to the new grouped UI.
2. Preview launch timing — the Exclusion filters section links to https://www.datadoghq.com/product-preview/rum-exclusion-filters/, which 404s until the form is published.

For Datadog employees:

AI assistance

Used Claude Code to draft the restructure from the product brief and to audit inbound anchor links across the docs. Reviewed manually.

Additional notes

Open questions for reviewers:

• Error Tracking exclusion filter default state — the page says you can enable or disable it but not delete it. It does not say whether it is on or off by default for existing orgs, because the brief doesn't specify. Needs a sentence once decided.
• API — the API section is unchanged. The API reference does not document exclusion-filter endpoints yet (/api/latest/ has rum-retention-filters and rum-retention-quota only), so linking there now would send readers to a page that can't help them. Follow-up once the endpoints publish, along with Terraform coverage if applicable.
• UI steps for creating an exclusion filter were written against the design prototype in the brief and should be checked against the shipped UI.

[github-actions]

Preview links (active after the build_preview check completes)

Modified Files

• https://docs-staging.datadoghq.com/quentin.sellem/rum_exclusion_filters/real_user_monitoring/guide/retention_filter_best_practices
• https://docs-staging.datadoghq.com/quentin.sellem/rum_exclusion_filters/real_user_monitoring/rum_without_limits/retention_filters

[OliviaShoup]

this looks great!

one non-blocking structural note. ## Exclusion filters and ### Excluding sessions using retention filters (a subsection two headings later, under Custom retention filters) are very similarly named for two different concepts. I see the PR description explains the heading text is intentionally unchanged to preserve existing deep links but flagging since a reader or AI agent skimming headings alone could conflate the two

[OliviaShoup]

"simply" is on our remove-filler-word list

Suggested change

	Disabled filters simply ignore events. A disabled custom retention filter makes no sampling decision, and a disabled exclusion filter excludes no event.
	Disabled filters ignore events. A disabled custom retention filter makes no sampling decision, and a disabled exclusion filter excludes no event.

[OliviaShoup]

this is a style guide thing

Suggested change

	- Adding `-version:(1* OR 2*)` to a retention filter ensures that filter never keeps events from older versions 1 and 2 of your application.
	- Adding `-version:(1* OR 2*)` to a retention filter helps ensure that filter never keeps events from older versions 1 and 2 of your application.

[OliviaShoup]

totally optional

Suggested change

	- Once a session is retained, it is available in the Session Explorer and other RUM pages, and its later events are kept automatically instead of going through the filters.
	- After a session is retained, it is available in the Session Explorer and other RUM pages, and its later events are kept automatically instead of going through the filters.