perf(core): Batch and coalesce scope-persistence disk writes

[runningcode]

Summary

Scope persistence wrote to disk on every scope mutation, which a customer cold-start trace (JAVA-628) showed to be the single largest SDK cost during startup — larger than init itself. On the Sentry executor thread, during a 1.7 s startup window:

• FileObjectQueue#add ×107 — every breadcrumb was a synchronous, fsync'd QueueFile append (the file was opened in rwd mode).
• PersistingScopeObserver#store ×310 — setContexts/setTrace/setUser/setTags/… each rewrote their whole file on every change, even though only the latest value matters.
• JsonSerializer#serialize ×421.

(The trace was captured with method-level tracing, which inflates per-slice durations; the call counts are the reliable signal, so the wall-clock attributions from the ticket are omitted here.)

I did a benchmark to compare the performance improvement of this PR and an alternative.
Tape as shipped is what we have on main, tape without fsync is this PR and JSONL is replacing tape with a single json file.

What changed

Instead of writing eagerly on each mutation, mutations are recorded as pending state and flushed by a single task submitted to the Sentry executor:

• Latest-wins per file — each scope field keeps only its most recent pending value, collapsing the many redundant rewrites into a handful.
• Coalescing without a timer — at most one flush is queued at a time. The executor is single-threaded, so every mutation that arrives while the flush sits in the queue is folded into the same write. Coalescing therefore tracks executor load rather than a fixed delay: it's strongest exactly during startup, when the queue is deepest, and on an idle app the flush runs almost immediately.
• Batched breadcrumbs — breadcrumbs are buffered and appended together behind a single fsync. QueueFile gains an opt-in buffered-write mode (synchronousWrites(false)) plus a sync() method; only the breadcrumb queue opts in, the ANR-profile queues keep synchronous writes.
• Ordered breadcrumb operations — adds and clears share one queue (a CLEAR_MARKER sentinel, mirroring the existing DELETE_MARKER for field writes) rather than a list plus a separate flag, so a clear cannot wipe a breadcrumb added after it. Batching split what used to be one ordered stream of executor tasks into independent state; keeping both in one queue makes the ordering intrinsic again.
• Mutations no longer do I/O on the calling thread. Previously a mutation already on the Sentry executor thread ran its write inline; now it only records pending state.

Tradeoff

Persistence exists to enrich crash/ANR events on the next launch and was already asynchronous, so nothing changes about the "data is only needed if the process dies" contract. Because the flush is submitted rather than delayed, pending state is written as soon as the executor drains to it — there is no added time-based loss window. On-disk format is unchanged; restore is unaffected.

Notes

• Reuses the existing enableScopePersistence option; no new public option.
• requestFlush() guards against the executor rejecting the flush task. SentryExecutorService returns a CancelledFuture instead of throwing once its queue is full, which would otherwise leave the pending flag set and silently stop scope persistence for the rest of the process.
• resetCache() deliberately leaves pending mutations alone: they only ever hold values from the current process, so dropping them would lose scope state set during init rather than clearing the previous run's data.
• The trace also flagged a 24 ms main-thread Scopes#addBreadcrumb call (9.3 ms of it inside PersistingScopeObserver#addBreadcrumb, suspected lazy FileObjectQueue init). That is intentionally not addressed here.

🤖 Generated with Claude Code

[linear-code]

JAVA-628

[sentry]

📲 Install Builds

Android

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

⚙️ sentry-android Build Distribution Settings

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	312.40 ms	361.90 ms	49.49 ms
Size	0 B	0 B	0 B

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
6b019b7	343.31 ms	417.23 ms	73.91 ms
d15471f	342.08 ms	415.44 ms	73.35 ms
8687935	332.52 ms	362.23 ms	29.71 ms
5b1a06b	352.27 ms	413.70 ms	61.43 ms
91bb874	314.47 ms	440.00 ms	125.53 ms
0ee65e9	321.06 ms	361.24 ms	40.18 ms
e63ad34	323.67 ms	390.33 ms	66.67 ms
33a08cc	267.08 ms	340.45 ms	73.37 ms
27d7cf8	397.90 ms	498.65 ms	100.75 ms
ee747ae	405.43 ms	485.70 ms	80.28 ms

App size

Revision	Plain	With Sentry	Diff
6b019b7	0 B	0 B	0 B
d15471f	1.58 MiB	2.13 MiB	559.54 KiB
8687935	1.58 MiB	2.19 MiB	619.17 KiB
5b1a06b	0 B	0 B	0 B
91bb874	1.58 MiB	2.13 MiB	559.07 KiB
0ee65e9	0 B	0 B	0 B
e63ad34	0 B	0 B	0 B
33a08cc	1.58 MiB	2.12 MiB	555.28 KiB
27d7cf8	1.58 MiB	2.12 MiB	549.42 KiB
ee747ae	1.58 MiB	2.10 MiB	530.95 KiB

Previous results on branch: no/java-628-batch-scope-persistence

Startup times

Revision	Plain	With Sentry	Diff
9a85552	315.94 ms	370.50 ms	54.56 ms
3376dc7	322.45 ms	374.02 ms	51.57 ms
5ad5c95	318.13 ms	364.98 ms	46.85 ms
8e8cb90	313.06 ms	356.54 ms	43.48 ms
47395a5	312.85 ms	362.90 ms	50.05 ms
1afaf81	334.74 ms	380.29 ms	45.55 ms

App size

Revision	Plain	With Sentry	Diff
9a85552	0 B	0 B	0 B
3376dc7	0 B	0 B	0 B
5ad5c95	0 B	0 B	0 B
8e8cb90	0 B	0 B	0 B
47395a5	0 B	0 B	0 B
1afaf81	0 B	0 B	0 B

[0xadam-brown]

Thanks for this @runningcode! A few comments for your consideration.

And two big-picture thoughts...

Thread-safety:

I see that QueueFile isn't thread-safe. Worth double-checking that we don't expect the buffered write patterns to aggravate any concurrency concerns that were already there but perhaps less common (totally hand-wavy on my part – just flagging that I haven't done a thread-safety deep dive in my review).

Testing / monitoring:

Given that this is core infrastructure, do you plan to perform any manual tests / add tests to the sample app, etc.?

[runningcode]

Thanks for the thorough review, @0xadam-brown ! I've replied to your points and fixed the rest in the PR.

[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 54db93b. Configure here.}

[romtsn]

couple of minor things, but looks good, great improvement!