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 20d793b

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>

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?

apparently it can break a subtle edge-case #5978 (comment) so i reverted it to be safe

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?

we give customers an option to choose which mode they want to start recording in. This could've been a method argument, but we're mimicking the JS API here to stay aligned.

session mode would continuously send replay segments while in buffer mode customers would have to explicitly call flush() or raise an error to have anything sent

Can we document that flush() sends it up to Sentry? I think it isn't so clear (it could just be flushing to disk).

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

both, the stop logic does not differ between the two (also updated javadoc)

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?

Also following the JS API :) I agree it can be a real footgun though - there's one issue open in sentry-javascript re. that getsentry/sentry-javascript#12664. I think I'd still not introduce recordingMode as they suggest in the issue above for now, until someone actually hits this (we document the behaviour). Or we could also diverge from JS here and not start a new recording in flush at all.

Drop foreground and background callbacks received before Replay is registered instead of leaving stale work on the main queue. Clarify the manual replay API documentation. 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 df60eec. Configure here.}

Check Replay registration when the foreground callback executes so AppState catch-up can start Replay after registration. Cover both callback orderings with tests. Refs JAVA-325 Co-Authored-By: Codex <noreply@openai.com>

runningcode

looks good. I still think the start and startBuffering methods are confusing. Not sure if better javadocs would be less confusing. I understand that it is that way to align with js.

runningcode · 2026-08-24T14:28:51Z

+ */
 public interface IReplayApi {

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


Can we document that flush() sends it up to Sentry? I think it isn't so clear (it could just be flushing to disk).

runningcode

lgtm!

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

cursor Bot reviewed Aug 24, 2026

View reviewed changes

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

fix(replay): Preserve queued foreground startup

20d793b

Check Replay registration when the foreground callback executes so AppState catch-up can start Replay after registration. Cover both callback orderings with tests. Refs JAVA-325 Co-Authored-By: Codex <noreply@openai.com>

sentry Bot reviewed Aug 24, 2026

View reviewed changes

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

runningcode reviewed Aug 24, 2026

View reviewed changes

runningcode approved these changes Aug 24, 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!

Uh oh!

runningcode left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

runningcode left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

runningcode left a comment

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

romtsn Aug 24, 2026 •

edited

Loading