Clarify docs about RUM without Limits Retention Filters (#30221)

* clarify docs about rum retention filters

* fix typo

* Update content/en/real_user_monitoring/guide/retention_filter_best_practices.md

Co-authored-by: Rosa Trieu <[email protected]>

* Update content/en/real_user_monitoring/rum_without_limits/retention_filters.md

Co-authored-by: Rosa Trieu <[email protected]>

* Update content/en/real_user_monitoring/rum_without_limits/retention_filters.md

Co-authored-by: Rosa Trieu <[email protected]>

* Update content/en/real_user_monitoring/rum_without_limits/retention_filters.md

Co-authored-by: Rosa Trieu <[email protected]>

---------

Co-authored-by: Rosa Trieu <[email protected]>

Author: MaelNamNam

content/en/real_user_monitoring/guide/retention_filter_best_practices.md

@@ -38,7 +38,7 @@ Sequencing your retention filters properly ensures you store the RUM data you ne
 ### Setting up filters
 - If unsure about your settings, start by arranging filters from highest to lowest retention rates.
 - Use more filters with a 100% rate, and limit filters with lower percentages.
-- Add a default "catch-all" retention filter at the end to capture any sessions not matched by previous filters.
+- Add a default "catch-all" retention filter at the end to capture any sessions not matched by previous filters. We recommend including `@session.is_active: false` in the query to ensure this retention filter only matches sessions that are complete and were not previously retained by another retention filter.
 
 ## Suggested retention filters and use cases
 Below we describe the set of default filters, suggested filters, and their typical use cases.
@@ -57,7 +57,7 @@ Below we describe the set of default filters, suggested filters, and their typic
 | Session with user attributes | `@type:session user.tier:paid` | Use user information from a session to create a filter. For example, you can retain sessions for all your paid tier users. |
 | Sessions with a specific user | `@type:session user.id:XXXXX` | This filter can target sessions from specific users, such as a production test account or an executive who regularly tests the application. |
 | Sessions with a specific action | `@type:action @action.name:XXXXX` | You can retain all sessions with a specific action that the SDK automatically tracks out-of-the-box or a custom action that you instrumented in your code.
-| Sessions with a specific duration | `@session.view_count > 3 OR @session.duration  > 15, retention rate 100%` | If you notice many short sessions, like a user viewing a page for 10 seconds without further action or errors, they are typically not useful. You can use a duration retention filter to reduce these sessions. |
+| Sessions with a specific duration | `@session.view_count > 3 OR @session.duration  > 15` | If you notice many short sessions, like a user viewing a page for 10 seconds without further action or errors, they are typically not useful. You can use a duration retention filter to reduce these sessions. |
 | Sessions with a network error 4XX and 5XX | `@type:resource @resource.status_code:>=400` | Frontend applications often encounter issues with downstream services returning 4XX or 5XX status codes. Using this filter, you can capture all sessions with resource calls that result in error codes. |
 
 

content/en/real_user_monitoring/rum_without_limits/retention_filters.md

@@ -20,18 +20,21 @@ The **retention rate** specifies the percentage of matching sessions you want to
 
 ## How it works
 
-A session is stored when at least one retention filter matches one of its constituting events and retains the underlying session based on the configured retention rate.
+A session is stored as soon as a retention filter matches one of its constituting events based on the predefined query, and samples it in based on the configured retention rate.
 
 {{< img src="real_user_monitoring/rum_without_limits/rum-without-limits-how-retention-filters-work-2.png" alt="Diagram showing the logical flow of retention filters and how they impact the number of sessions ultimately retained." style="width:80%" >}}
 
 The logical flow of retention filters is the following:
 
-- All RUM events are evaluated against each filter in sequence, starting with the first.
-- If an event matches a filter, a decision is made to retain or discard the session containing the event, and subsequent filters are not executed.
-- Retained sessions are saved and accessible in the Session Explorer and other RUM pages. New events coming from this session are automatically kept to ensure complete visibility.
-- If an event does not match any filters, or if it matches a filter but the decision is made not to retain the session based on the configured retention rate, future events from the same session will continue to be processed. As a result, the session may eventually be retained.
+- All RUM events are evaluated against each filter in sequence, starting with the first one received.
+- When an event `A` matches a filter, a decision is made based on the retention rate to either sample the entire session in, or wait for future events to be evaluated. In both cases, event `A` is not evaluated further against subsequent retention filters. This is why the **order of retention filters matters**.
+- Retained sessions are saved and accessible in the Session Explorer and other RUM pages. New events coming from this session do not go through the list of retention filters, but are automatically kept to ensure complete visibility.
 
-**Note**: Be cautious when defining filters on event attributes that update over time. For example, a filter retaining sessions with fewer than two errors might mistakenly retain sessions, as error counts update in real-time. Use "greater than or equal to" (≥) conditions for fields that update, such as `@session.error.count >= 2`.
+**Notes**:
+
+- If an event does not match any filters, or if it matches a filter but the decision is made not to retain the session based on the configured retention rate, future events from the same session will continue to be evaluated. As a result, the session may eventually be retained.
+- Be cautious when defining filters on event attributes that update over time. For example, a filter retaining sessions with fewer than two errors might mistakenly retain sessions, as error counts update in real-time, and all sessions start at zero. Either use "greater than or equal to" (≥) conditions for fields that update, such as `@session.error.count >= 2`, or ensure the Session and View objects that are mutable are complete before evaluating them against the retention filters, by adding `@session.is_active: false` or `@view.is_active: false`.
+- Our SDKs batch and compress events before sending them to Datadog, and failed uploads go back at the end of the queue on the device. Therefore, it could happen that event `B` is evaluated before event `A`, but all events are eventually evaluated against the list of retention filters to prevent gaps.
 
 ## How retention filters work with replays
 
@@ -41,6 +44,8 @@ Replays collected through the [force collection][1] mechanism are kept by the de
 
 {{< img src="real_user_monitoring/rum_without_limits/retention-session-filter.png" alt="When force collection is enabled, it is positioned first in the list of retention filters." style="width:90%" >}}
 
+**Note**: Though our mobile SDKs also provide APIs to conditionally start and stop the recording (instead of relying on a flat sample rate), only the replays that are force-recorded by our browser SDK are kept by default.
+
 
 ## Creating a retention filter