streamline changelog & update replay readme

Author: mydea

CHANGELOG.md

@@ -10,7 +10,7 @@
 
 - **doc(sveltekit): Promote the SDK to beta state (#7874)**
 
-The SvelteKit SDK (@sentry/sveltekit) is now officially in Beta.
+The SvelteKit SDK ([@sentry/sveltekit](./packages/sveltekit/README.md)) is now officially in Beta.
 This means that we do not expect any breaking changes anymore.
 
 - **feat(replay): Allow to configure URLs to capture network bodies/headers (#7953)**
@@ -40,44 +40,15 @@ new Replay({
 
 Note that bodies will be truncated to a max length of ~150k characters.
 
-**- feat(replay): Extend session idle time until expire to 15min (#7955)**
-
-Replay Sessions will now only be refreshed when a user is idle for 15min or more.
-Previously, we would consider 5min of idle time as the threshold for this, which sometimes resulted in a lot of consequitive sessions.
-
-**- feat(replay): Change the behavior of error-based sampling (#7768)**
-
-We have changed the behavior of error-based sampling, as well as adding & adjusting APIs a bit to be more aligned with expectations.
-
-First, the `replaysOnErrorSampleRate` will now be applied per-error at error-time, not in advance at session creation time -
-so the sampling rate was not accurate if you had sessions with many errors.
-Now whenever an error happens, we'll check the error sample rate, and potentially flush the session.
-
-Related to this, we also reworked the public `start()` method and added a new `startBuffering()` method.
-
-When calling `start()`, it will now _always_ start a session-based Replay, ignoring sample rates.
-Note that it will throw an error if a session is already running.
-
-You can use the new `startBuffering()` method to start a new Replay in buffering-mode.
-This will either wait for an error (when `replaysOnErrorSampleRate > 0`), or until you manually call `replay.flush()`.
-
-Note that with this change, as soon as either `replaysSessionSampleRate` or `replaysOnErrorSampleRate` are `> 0`,
-we will _always_ start recording in the background, either in session mode or in buffering mode.
-When both sample rates are set to `0`, you can manually start the session with either `replay.start()` or `replay.startBuffering()`.
-
-
-**- Improved Replay `flush()` & `stop()` APIs**
+**- feat(replay): Changes of sampling behavior & public API**
+  - feat(replay): Change the behavior of error-based sampling (#7768)
   - feat(replay): Change `flush()` API to record current event buffer (#7743)
   - feat(replay): Change `stop()` to flush and remove current session (#7741)
 
-We have revamped some existing public API of Replay in order to be better aligned with expectations.
-
-`replay.flush()` now works differently when in error sampling mode:
-It will send the buffered replay data, then convert the session to a "regular" session and continue recording.
-With this, you can manually start capturing at any point.
+We have changed the behavior of error-based sampling, as well as adding & adjusting APIs a bit to be more aligned with expectations.
+See [Sampling](./packages/replay/README.md#sampling) for details.
 
-`replay.stop()` will now flush the event buffer before stopping, and remove the session from session storage.
-This also means that `stop()` now returns a promise.
+We've also revamped some public APIs in order to be better aligned with expectations. See [Stoping & Starting Replays manually](./packages/replay/README.md#stopping--starting-replays-manually) for details.
 
 - **feat(core): Add multiplexed transport (#7926)**
 
@@ -105,25 +76,17 @@ init({
 });
 ```
 
-- **fix(core): fix(utils): default normalize() to a max. of 100 levels deep instead of Inifnity (#7957)**
-
-We used to default to normalize objects to a depth of `Infinity`.
-For most cases, this shouldn't matter, because objects aren't actually infinitely deep, and we handle circular dependencies reasonably well.
-However, we found out that there _are_ cases where we can still end up running into an infinitely deep recursion -
-for example, when using dynamicly generated proxies, which we cannot detect as "same instance", thus our circular dependency handling breaks down.
-
-In order to account for these cases, we now default `normalize()` to a max. depth of 100.
-This should avoid this crashing when, for whatever reason, circular dependencies are not properly detected.
-
 ### Additional Features and Fixes
 
 - feat(nextjs): Add `disableLogger` option that automatically tree shakes logger statements (#7908)
+- feat(replay): Extend session idle time until expire to 15min (#7955)
 - feat(tracing): Add `db.system` span data to DB spans (#7952)
 - fix(core): Avoid crash when Function.prototype is frozen (#7899)
 - fix(nextjs): Fix inject logic for Next.js 13.3.1 canary (#7921)
 - fix(replay): Ensure console breadcrumb args are truncated (#7917)
 - fix(replay): Ensure we do not set replayId on dsc if replay is disabled (#7939)
 - fix(replay): Ensure we still truncate large bodies if they are failed JSON (#7923)
+- fix(utils): default normalize() to a max. of 100 levels deep instead of Inifnity (#7957)
 
 ## 7.49.0
 

packages/replay/README.md

@@ -86,7 +86,7 @@ import * as Sentry from "@sentry/browser";
 Sentry.setUser({ email: "[email protected]" });
 ```
 
-### Stopping & re-starting replays
+### Stopping & starting Replays manually
 
 Replay recording only starts when it is included in the `integrations` array when calling `Sentry.init` or calling `addIntegration` from the a Sentry client instance. To stop recording you can call the `stop()`.
 
@@ -109,6 +109,16 @@ client?.addIntegration(replay);
 replay.stop();
 ```
 
+When both `replaysSessionSampleRate` and `replaysOnErrorSampleRate` are `0`, recording will _not_ start.
+In this case, you can manually start recording:
+
+```js
+replay.start(); // Will start a session in "session" mode, regardless of sample rates
+replay.startBuffering(); // Will start a session in "buffer" mode, regardless of sample rates
+```
+
+
+
 ## Loading Replay as a CDN Bundle
 
 As an alternative to the NPM package, you can use Replay as a CDN bundle.
@@ -154,8 +164,11 @@ Sampling allows you to control how much of your website's traffic will result in
 - `replaysSessionSampleRate` - The sample rate for replays that begin recording immediately and last the entirety of the user's session.
 - `replaysOnErrorSampleRate` - The sample rate for replays that are recorded when an error happens. This type of replay will record up to a minute of events prior to the error and continue recording until the session ends.
 
-Sampling occurs when the session is first started. `replaysSessionSampleRate` is evaluated first. If it is sampled, then the replay recording begins. Otherwise, `replaysOnErrorSampleRate` is evaluated and if it is sampled, the integration will begin buffering the replay and will only upload a replay to Sentry when an error occurs. The remainder of the replay will behave similarly to a whole-session replay.
-
+When Replay is initialized, we check the `replaysSessionSampleRate`.
+If it is sampled, then we start recording & sending Replay data immediately.
+Else, if `replaysOnErrorSampleRate > 0`, we'll start recording in buffering mode.
+In this mode, whenever an error occurs we'll check `replaysOnErrorSampleRate`.
+If it is sampled, when we'll upload the Replay to Sentry and continue recording normally.
 
 ## Configuration
 
@@ -234,5 +247,5 @@ This should not happen to often, but be aware that it is theoretically possible.
 ## Manually sending replay data
 
 You can use `replay.flush()` to immediately send all currently captured replay data.
-This can be combined with `replaysOnErrorSampleRate: 1`
-in order to be able to send the last 60 seconds of replay data on-demand.
+When Replay is currently in buffering mode, this will send up to the last 60 seconds of replay data,
+and also continue sending afterwards, similar to when an error happens & is recorded.