fix(screenshots): Attach screenshots to the error envelope by bitsandfoxes · Pull Request #2835 · getsentry/sentry-unity

bitsandfoxes · 2026-09-04T12:22:55Z

Screenshots are now attached to the event they belong to and sent in its envelope, instead of being sent as a separate envelope afterwards.

Sending them separately meant a screenshot got orphaned whenever its event was dropped, e.g. by sampling or rate limiting. Capturing also blocked the main thread: reading the frame back from the GPU and encoding it to JPG stalled the frame for every screenshot (up to ~130 ms per screenshot at High on a Pixel 6, ~50 ms on an iPhone 18 Pro). And only some events got a screenshot at all.

How it works now:

ScreenshotEventProcessor adds a SentryScreenshotAttachmentContent to the event's hint. Events captured while a screenshot is still being taken share it.
The screenshot gets taken at the end of the frame the event was captured in, and skipped if none of the events sharing it made it past BeforeSend and sampling. Where supported, it gets read back via AsyncGPUReadback and encoded to JPG on a background thread right away, so the main thread only issues GPU work and no raw frames pile up in memory. With SetBeforeSendScreenshot set, or without async readback (e.g. on the WebBackgroundWorker), it's read and encoded on the main thread as before.
The attachment content waits for the screenshot when the SDK serializes the envelope on its background worker. Its stream reports no length, so Envelope.FromEvent doesn't block on the capturing thread. It never waits on the main thread and gives up 1 s after the event was captured if the main thread stops rendering; a capture stuck that long gets replaced.
Batch mode no longer attaches screenshots, since the end of the frame never comes. Feedback only gets one when requested via addScreenshot.

Behavior changes:

SetBeforeCaptureScreenshot now runs when the event gets captured, which can be a background thread. Events from background threads get a screenshot too.
SetBeforeSendScreenshot runs once per screenshot, receiving the first of the events sharing it that didn't get dropped.

Known gap: when a screenshot is discarded, times out or fails, the event carries an empty screenshot.jpg. sentry-dotnet only skips empty attachments whose stream reports a length of 0, which this one can't do without blocking. This gets fixed upstream in sentry-dotnet.

Measured on an earlier revision of this PR, on a Pixel 6 and an iPhone 18 Pro (development builds, 1 error/s):

Frames over 20 ms: 19–22 down to ~1 per 20 screenshots on the Pixel, 14–19 down to 0 on the iPhone.
Every sent event carries its screenshot, against about a quarter before.

Docs: getsentry/sentry-docs#19972

🤖 Generated with Claude Code

Attaching a screenshot blocked the thread the error happened on for the GPU readback and the JPG encode, ~35 ms per error on an iPhone at High quality. Read the cached frame back via AsyncGPUReadback and attach it as content that only encodes once the SDK serializes the envelope on its background worker. The screenshot still rides in the event's envelope. Errors on background threads now get a screenshot too where async readback is supported. Also stop the refresh coroutine once the cache is disposed, so Close no longer leaks a render texture or throws when called off the main thread. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Builds a harness from the sample that runs screenshot configurations round-robin against a baseline with screenshots disabled, records frame timings, capture costs and encodes on the SDK's worker, and checks that sent events carry their screenshot. A report script summarizes a run against its baseline. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cursor

Stale Bugbot comment from a previous run.

Keep the change focused on how screenshots get attached to events. The device benchmark, the profiler markers and the encode timing log only served measuring it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Replace the periodically refreshed frame cache with screenshots requested by the event and taken at the end of the frame it was captured in. Idle frames no longer pay for screenshots, and the screenshot shows the frame the error happened in. Events in quick succession share a screenshot. Read back into pooled native buffers and encode them on the SDK's worker, so the main thread only issues the GPU work. The capture now happens at screen resolution and gets scaled down in a blit, as capturing straight into a smaller target cropped the screenshot. Add SetBeforeSendScreenshotPixels, which edits the raw pixels on the worker right before encoding. Deprecate SetBeforeSendScreenshot, whose Texture2D ties encoding to the main thread, and apply it once per screenshot. Default ScreenshotQuality to Low. Refs #2835 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The Unity SDK now takes the screenshot at the end of the frame the error happened in instead of periodically. Drop ScreenshotCaptureInterval, document SetBeforeSendScreenshotPixels and the Low default quality, and mark SetBeforeSendScreenshot as deprecated. Refs getsentry/sentry-unity#2835 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…up in the queue

…a missing frame can't stall every envelope

… runs once per shared screenshot

…ke them all at once

…on't skew the timeout

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 caac23e. Configure here.}

cursor · 2026-10-23T22:19:34Z

+        finally
+        {
+            RenderTexture.ReleaseTemporary(renderTexture);
+        }


Readback releases texture too early

Medium Severity

CaptureAsync calls RenderTexture.ReleaseTemporary as soon as AsyncGPUReadback.Request returns. Unity only queues that readback; the source must stay alive until the callback runs. A pooled screen-sized texture can be reused first, so the readback fails or returns overwritten pixels and the event gets a missing or corrupted screenshot.

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

bitsandfoxes and others added 5 commits September 4, 2026 14:14

reworked screenshots

3d2ce29

merged main

e30f504

Merge branch 'main' into fix/screenshots

2f155cb

bitsandfoxes changed the title ~~poc: capture screenshots with error envelope~~ fix(screenshots): Attach screenshots to the error envelope Oct 14, 2026

bitsandfoxes marked this pull request as ready for review October 14, 2026 15:54

bitsandfoxes mentioned this pull request Oct 14, 2026

docs(unity): Describe how screenshots get attached to events getsentry/sentry-docs#19972

Draft

bitsandfoxes marked this pull request as draft October 14, 2026 15:59

cursor Bot reviewed Oct 14, 2026

View reviewed changes

Comment thread src/Sentry.Unity/SentryScreenshotCache.cs Outdated

Comment thread src/Sentry.Unity/SentryScreenshotCache.cs Outdated

Comment thread src/Sentry.Unity/SentryMonoBehaviour.Screenshot.cs Outdated

bitsandfoxes and others added 2 commits October 15, 2026 11:08

bitsandfoxes added 11 commits October 20, 2026 17:24

skip screenshots of dropped events and warm up capture at startup

a83f1c1

stripped down

cc51434

Encode screenshots right after the readback so raw frames don't pile …

ccbb34a

…up in the queue

Make the screenshot timeout a deadline and replace stale captures so …

be644f3

…a missing frame can't stall every envelope

Skip the screenshot when none of the events sharing it got captured

06e8f78

Pass the first captured event to BeforeSendScreenshot and document it…

b63efa8

… runs once per shared screenshot

Update screenshot docs and comments to match when captures happen

da0fd4e

Cancel replaced stale captures so a recovering main thread doesn't ta…

74f9a18

…ke them all at once

Time screenshot captures with a monotonic clock so wall clock jumps d…

f99970e

…on't skew the timeout

Describe screenshots as shared while in flight rather than per frame

974b177

Merge remote-tracking branch 'origin/main' into fix/screenshots

caac23e

bitsandfoxes mentioned this pull request Oct 23, 2026

fix: drop attachments whose stream turns out empty when the envelope is sent getsentry/sentry-dotnet#5787

Draft

bitsandfoxes marked this pull request as ready for review October 23, 2026 22:13

cursor Bot reviewed Oct 23, 2026

View reviewed changes

Navigation Menu

Repository navigation

fix(screenshots): Attach screenshots to the error envelope - #2835

fix(screenshots): Attach screenshots to the error envelope#2835
bitsandfoxes wants to merge 18 commits into
mainfrom
fix/screenshots

bitsandfoxes commented Sep 4, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Oct 23, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

bitsandfoxes commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 23, 2026

Choose a reason for hiding this comment

Readback releases texture too early

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

bitsandfoxes commented Sep 4, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading