From 1dac6fe0a9c0eae10469f1b3d566ba15dca3df20 Mon Sep 17 00:00:00 2001 From: Rosa Trieu Date: Fri, 21 Aug 2026 11:37:52 -0700 Subject: [PATCH 1/4] [DOCS-15443] Clarify heatmap data retention and troubleshooting Distinguish the click overlay retention period from the Session Replay background screenshot retention period, and document how to view heatmaps beyond the default 30-day replay retention. --- hugo/content/en/session_replay/heatmaps.md | 28 ++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/hugo/content/en/session_replay/heatmaps.md b/hugo/content/en/session_replay/heatmaps.md index 104211417b9..50d1aafdcb5 100644 --- a/hugo/content/en/session_replay/heatmaps.md +++ b/hugo/content/en/session_replay/heatmaps.md @@ -172,12 +172,28 @@ To remove the currently saved screenshot and revert to an auto-picked one from a {{< img src="real_user_monitoring/session_replay/heatmaps/heatmaps-unpin-screenshot-1.png" alt="Click unpin to remove the currently pinned screenshot." style="width:100%;">}} +### Analyzing heatmaps beyond replay retention + +In Product Analytics, Datadog retains click data for 15 months and Session Replays for 30 days by default. To view a heatmap for a period older than your replay retention: + +1. Set the date range to a period within the last 30 days, so a heatmap renders with a background from a recent replay. +1. Click {{< ui >}}Save{{< /ui >}} on the current screenshot to pin it. +1. Set the date range back to the period you want to analyze. + +Your older click data appears on the pinned screenshot. You can also use {{< ui >}}Take new screenshot{{< /ui >}} to capture a specific state from your live application. + +**Note**: The background reflects your application as it looked recently, not as it looked during the period you are analyzing. If your page layout changed in between, clicks can appear over the wrong elements. + ## Data retention -The time periods you can view in a heatmap depend on where you access it: +A heatmap combines two pieces of data. Datadog retains each for a different period: + +- **The overlay** (clicks and scrolls). In RUM, the overlay uses RUM action events, which Datadog retains for 30 days. In Product Analytics, it uses Product Analytics click data, which Datadog retains for 15 months. +- **The background screenshot**, which Datadog captures from Session Replay and retains for 30 days by default. -- **RUM**: Session Replay heatmaps use RUM click data (RUM action events), which has a 30-day retention period. -- **Product Analytics**: Heatmaps use Product Analytics click data, which has a 15-month retention period. +A heatmap needs both to render. If you select a time frame where click data still exists but no replay remains to use as a background, the heatmap shows "No Replay Data" even though you can still query those actions in the Analytics Explorer. + +If you expect to analyze a view over a period longer than 30 days, save a screenshot for it while replays are still available. When you save a screenshot, Datadog extends the retention of the replay behind it to 15 months, so the heatmap keeps rendering for as long as your Product Analytics click data exists. See [Analyzing heatmaps beyond replay retention](#analyzing-heatmaps-beyond-replay-retention). ## Next steps @@ -203,7 +219,11 @@ The tooltip on the icon says element is not visible. This means that the element ### After attempting to create a heatmap, I see a "No Replay Data" state appear. -The "No Replay Data" state means that Datadog could not find any Session Replays to use as a heatmap background that matches the current search filters. If you just started to record sessions with the [Browser SDK][2], it may also take a few minutes for the Session Replay to be available for viewing. +The "No Replay Data" state means that Datadog could not find any Session Replay to use as a heatmap background. Common causes: + +- Your selected time frame is older than your Session Replay retention, which is 30 days by default. Click data can still exist, but no replay remains to use as a background. See [Analyzing heatmaps beyond replay retention](#analyzing-heatmaps-beyond-replay-retention). +- No replay matches your current search filters. +- You recently started recording with the [Browser SDK][2], and the replay is not yet available. This can take a few minutes. ### After attempting to create a heatmap, I see a "Not enough data to generate a heatmap" state appear. From 565fa244d6395f4b3e3f6300711bcf6f3548c36e Mon Sep 17 00:00:00 2001 From: Rosa Trieu Date: Fri, 21 Aug 2026 11:52:26 -0700 Subject: [PATCH 2/4] [DOCS-15443] Scope retention guidance to product and tighten wording Convert the retention breakdown to a table, scope the save-a-screenshot workaround to Product Analytics, and note that RUM heatmaps are not available past 30 days. Add links to the data retention periods and extended retention references. --- hugo/content/en/session_replay/heatmaps.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/hugo/content/en/session_replay/heatmaps.md b/hugo/content/en/session_replay/heatmaps.md index 50d1aafdcb5..996f8967178 100644 --- a/hugo/content/en/session_replay/heatmaps.md +++ b/hugo/content/en/session_replay/heatmaps.md @@ -174,7 +174,7 @@ To remove the currently saved screenshot and revert to an auto-picked one from a ### Analyzing heatmaps beyond replay retention -In Product Analytics, Datadog retains click data for 15 months and Session Replays for 30 days by default. To view a heatmap for a period older than your replay retention: +In Product Analytics, click data outlives the Session Replay used as a background. See [Data retention](#data-retention). To view a heatmap for a period older than your replay retention: 1. Set the date range to a period within the last 30 days, so a heatmap renders with a background from a recent replay. 1. Click {{< ui >}}Save{{< /ui >}} on the current screenshot to pin it. @@ -186,14 +186,21 @@ Your older click data appears on the pinned screenshot. You can also use {{< ui ## Data retention -A heatmap combines two pieces of data. Datadog retains each for a different period: +A heatmap combines two pieces of data, and Datadog retains each for a different period: -- **The overlay** (clicks and scrolls). In RUM, the overlay uses RUM action events, which Datadog retains for 30 days. In Product Analytics, it uses Product Analytics click data, which Datadog retains for 15 months. -- **The background screenshot**, which Datadog captures from Session Replay and retains for 30 days by default. +| Data | Source | Retention | +| ---- | ------ | --------- | +| **Overlay** (clicks and scrolls) in RUM | RUM action events | 30 days | +| **Overlay** (clicks and scrolls) in Product Analytics | Product Analytics click data | 15 months | +| **Background screenshot** in both | Session Replay | 30 days by default | A heatmap needs both to render. If you select a time frame where click data still exists but no replay remains to use as a background, the heatmap shows "No Replay Data" even though you can still query those actions in the Analytics Explorer. -If you expect to analyze a view over a period longer than 30 days, save a screenshot for it while replays are still available. When you save a screenshot, Datadog extends the retention of the replay behind it to 15 months, so the heatmap keeps rendering for as long as your Product Analytics click data exists. See [Analyzing heatmaps beyond replay retention](#analyzing-heatmaps-beyond-replay-retention). +In Product Analytics, if you expect to analyze a view over a period longer than 30 days, save a screenshot for it while replays are still available. Saving a screenshot extends the retention of the replay behind it to 15 months, so the heatmap keeps rendering for as long as Datadog retains your Product Analytics click data. See [Analyzing heatmaps beyond replay retention](#analyzing-heatmaps-beyond-replay-retention). + +In RUM, action events expire after 30 days, so heatmaps are not available beyond that window. + +For the retention periods that apply to other data types, see [Data retention periods][7]. To extend retention on individual replays, see [Extend data retention][8]. ## Next steps @@ -245,3 +252,5 @@ User information is not collected by default. Heatmaps use the user information [4]: /product_analytics/charts/analytics_explorer/ [5]: /session_replay/privacy_options?platform=browser#privacy-options [6]: https://chromewebstore.google.com/detail/datadog-test-recorder/kkbncfpddhdmkfmalecgnphegacgejoa +[7]: /data_security/data_retention_periods/ +[8]: /session_replay/#extend-data-retention From fc06764a1dceedbeb807db762da056ef37956289 Mon Sep 17 00:00:00 2001 From: Rosa Trieu Date: Fri, 21 Aug 2026 13:52:21 -0700 Subject: [PATCH 3/4] [DOCS-15443] Document automatic retention extension paths Note on the Session Replay page that adding a replay to a playlist or saving it as a heatmap screenshot extends retention to 15 months. --- hugo/content/en/session_replay/_index.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/hugo/content/en/session_replay/_index.md b/hugo/content/en/session_replay/_index.md index d76c7fbce7b..9811714bb62 100644 --- a/hugo/content/en/session_replay/_index.md +++ b/hugo/content/en/session_replay/_index.md @@ -98,6 +98,11 @@ To extend Session Replay data retention to 15 months, you can enable {{< ui >}}E To access any Session Replay at a later time, Datadog recommends saving the URL or adding it to a [Playlist][7]. +Datadog also extends retention to 15 months automatically when a replay is used elsewhere in the product: + +- Adding a replay to a [Playlist][7]. +- Saving a replay as a heatmap screenshot. See [Analyzing heatmaps beyond replay retention][12]. + Extended Retention only applies to Session Replay and does not include associated events. The 15 months start when Extended Retention is enabled, not when the session is collected. You can disable Extended Retention at any time. If the session replay is still within its default 30 days of retention, the replay expires at the end of the initial 30 day window. If you disable Extended Retention on a session replay that is older than 30 days, the replay immediately expires. @@ -142,4 +147,5 @@ Learn more about [Dev Tools][11]. [8]: /notebooks/ [9]: /account_management/audit_trail/ [10]: /rum/replay/playlists/my-watch-history -[11]: /session_replay/dev_tools \ No newline at end of file +[11]: /session_replay/dev_tools +[12]: /session_replay/heatmaps/#analyzing-heatmaps-beyond-replay-retention \ No newline at end of file From 2986a5075b953fa828193740baad051da03f17c8 Mon Sep 17 00:00:00 2001 From: Rosa Trieu <107086888+rtrieu@users.noreply.github.com> Date: Fri, 21 Aug 2026 13:54:38 -0700 Subject: [PATCH 4/4] Apply suggestion from @rtrieu --- hugo/content/en/session_replay/heatmaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hugo/content/en/session_replay/heatmaps.md b/hugo/content/en/session_replay/heatmaps.md index 996f8967178..db8b285a49f 100644 --- a/hugo/content/en/session_replay/heatmaps.md +++ b/hugo/content/en/session_replay/heatmaps.md @@ -186,7 +186,7 @@ Your older click data appears on the pinned screenshot. You can also use {{< ui ## Data retention -A heatmap combines two pieces of data, and Datadog retains each for a different period: +A heatmap combines two pieces of data (the **overlay** - clicks and scrolls, and the **background screenshot**), and Datadog retains each for a different period: | Data | Source | Retention | | ---- | ------ | --------- |