feat(replay): Add manual replay control API by romtsn · Pull Request #5978 · getsentry/sentry-java

romtsn · 2026-08-19T11:31:07Z

Depends on #5965.

📜 Description

Add Sentry.replay() controls for starting full-session or buffered recording, stopping, pausing, resuming, and flushing.

Lifecycle-driven background pauses remain separate from explicit user pauses. Foregrounding resumes only lifecycle-paused recording, so an app can pause replay on sensitive screens without the SDK unexpectedly restarting it. Starting an already-running replay is a no-op; flushing a stopped replay starts a full session, matching the JavaScript SDK. Explicit starts bypass replay sample rates, which continue to control automatic startup.

💡 Motivation and Context

Give Android applications explicit control over Session Replay for opt-in flows and sensitive screens while preserving automatic lifecycle behavior.

Refs JAVA-325

💚 How did you test it?

Ran ./gradlew spotlessApply apiDump.
Ran all sentry-android-core unit tests: 1,601 tests, 0 failures, 1 skipped.
Ran all sentry-android-replay unit tests: 252 tests, 0 failures, 1 skipped.
Added focused coverage for the public API, manual pause behavior, buffering, flushing, and lifecycle transitions.

📝 Checklist

I added GH Issue ID & Linear ID
I added tests to verify the changes.
No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
I updated the docs if needed.
I updated the wizard if needed.
Review from the native team if needed.
No breaking change or entry added to the changelog.
No breaking change for hybrid SDKs or communicated to hybrid SDKs.
Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

Document the public replay controls in the Android documentation repository.

Expose start, buffering, pause, resume, stop, and flush operations through Sentry.replay(). Keep lifecycle pauses distinct from explicit user pauses. Foregrounding therefore does not resume sensitive-screen recording unexpectedly. Refs JAVA-325 Co-Authored-By: OpenAI Codex <noreply@openai.com>

linear-code · 2026-08-19T11:31:11Z

JAVA-325

github-actions · 2026-08-19T11:31:47Z

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 0582fec

sentry · 2026-08-19T11:34:14Z

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.53.0 (1)	release

⚙️ sentry-android Build Distribution Settings

github-actions · 2026-08-19T11:37:36Z

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	315.47 ms	382.74 ms	67.27 ms
Size	0 B	0 B	0 B

Baseline results on branch: romtsn/feat/java-665-replay-start-stop

Startup times

Revision	Plain	With Sentry	Diff
`a21e537`	319.04 ms	357.04 ms	38.00 ms
`5cdb0b8`	311.75 ms	369.08 ms	57.33 ms
`b208705`	315.54 ms	354.54 ms	39.00 ms
`f158a9a`	352.96 ms	413.17 ms	60.21 ms

App size

Revision	Plain	With Sentry	Diff
`a21e537`	0 B	0 B	0 B
`5cdb0b8`	0 B	0 B	0 B
`b208705`	0 B	0 B	0 B
`f158a9a`	0 B	0 B	0 B

Previous results on branch: romtsn/feat/java-325-replay-control-api

Startup times

Revision	Plain	With Sentry	Diff
`a12ad59`	311.45 ms	364.02 ms	52.57 ms
`dbf03ab`	319.24 ms	369.88 ms	50.63 ms

App size

Revision	Plain	With Sentry	Diff
`a12ad59`	0 B	0 B	0 B
`dbf03ab`	0 B	0 B	0 B

A foreground callback can run before ReplayIntegration registers and initializes its options. Ignore lifecycle callbacks until the integration is enabled to avoid crashing during SDK initialization. Refs JAVA-325 Co-Authored-By: Codex <noreply@openai.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bd1914c. Configure here.}

Track whether a buffered replay was started automatically so only automatic buffers apply per-error sampling. Manually started buffers now capture on errors as documented. Refs JAVA-325 Co-Authored-By: Codex <noreply@openai.com>

This reverts commit 8073208. Reason: Match Sentry JavaScript by applying onErrorSampleRate to all buffered replay captures. Refs JAVA-325 Co-Authored-By: Codex <noreply@openai.com>

runningcode

I did a first pass quick review, ping me for a second round.

runningcode · 2026-08-20T13:24:13Z

+
+  override fun onAppForegrounded(startNewSession: Boolean) {
+    enqueueOnMainThread {
+      if (!isEnabled.get()) {


would it make more sense to check this condition before enqueing?

runningcode · 2026-08-20T13:24:34Z

+
+  override fun onAppForegrounded(startNewSession: Boolean) {
+    enqueueOnMainThread {
+      if (!isEnabled.get()) {


would it make more sense to check this condition before enqueing?

runningcode · 2026-08-20T13:26:38Z

+ */
 public interface IReplayApi {

+  /** Starts a new replay session. Does nothing if a replay is already being recorded. */


just for my understanding why is start and startBuffering two different calls. Why do we want to start a session separately from Buffering?

runningcode · 2026-08-20T13:28:04Z

+   */
+  void startBuffering();
+
+  /** Stops the current replay. A subsequent {@link #start()} begins a new replay session. */


does this mean the session is stopped or the buffering is stopped or both?

I ask because we have two different start methods but only a single stop/pause which makes it not clear which one the stop stops

runningcode · 2026-08-20T13:59:35Z

+    enqueueOnMainThread {
+      val current = state.get()
+      if (!current.isRecording) {
+        startInternal(isFullSession = true)


why does flush call startInternal if we're not recording?

changelog

05bdcbc

romtsn mentioned this pull request Aug 19, 2026

docs(android): Document manual Session Replay controls getsentry/sentry-docs#19077

Open

6 tasks

romtsn marked this pull request as ready for review August 19, 2026 16:24

romtsn requested review from 0xadam-brown, adinauer, markushi and runningcode as code owners August 19, 2026 16:24

romtsn added the deep-dive PR needs a thorough review of design, behavior, and edge cases label Aug 19, 2026

cursor Bot reviewed Aug 19, 2026

View reviewed changes

Comment thread sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt

romtsn and others added 2 commits August 19, 2026 20:28

fix(replay): Bypass sampling for manual buffers

8073208

Track whether a buffered replay was started automatically so only automatic buffers apply per-error sampling. Manually started buffers now capture on errors as documented. Refs JAVA-325 Co-Authored-By: Codex <noreply@openai.com>

revert: fix(replay): Bypass sampling for manual buffers

0582fec

This reverts commit 8073208. Reason: Match Sentry JavaScript by applying onErrorSampleRate to all buffered replay captures. Refs JAVA-325 Co-Authored-By: Codex <noreply@openai.com>

runningcode reviewed Aug 20, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

romtsn commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📜 Description

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

🔮 Next steps

Uh oh!

linear-code Bot commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sentry Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📲 Install Builds

Android

Uh oh!

github-actions Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance metrics 🚀

Baseline results on branch: romtsn/feat/java-665-replay-start-stop

Startup times

App size

Previous results on branch: romtsn/feat/java-325-replay-control-api

Startup times

App size

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

runningcode left a comment

Choose a reason for hiding this comment

Uh oh!

runningcode Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

runningcode Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

runningcode Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

runningcode Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

runningcode Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

romtsn commented Aug 19, 2026 •

edited

Loading

github-actions Bot commented Aug 19, 2026 •

edited

Loading

sentry Bot commented Aug 19, 2026 •

edited

Loading

github-actions Bot commented Aug 19, 2026 •

edited

Loading