[tustanivsky]

When a game's GPU hangs or faults, the NVIDIA Aftermath SDK writes a crash dump and Sentry sends it to Teapot (Sentry's GPU crash decoder) to turn it into an event. The dump identifies the shader that was running only by a 64-bit hash. Teapot has no name to go with that hash, so today the event shows a placeholder such as compute_01 and the developer has to guess which shader it was.

This PR closes that gap with debug files, the same way native crashes get symbolicated. A game can upload its compiled shaders (DXIL binaries) as debug files, keyed by that Aftermath hash. When Teapot reports which shaders it could not name, Sentry looks them up, hands Teapot presigned links to the uploaded binaries and asks it to decode again. The event then shows the shader's real entry point and, for material shaders, the material and pass it belongs to.

Key Changes

• New dxil debug file format. The debug ID is the compiler's hash from the file name, the code ID is the Aftermath hash computed by the uploader, and an optional shader group from the engine's shader symbol export is stored with the file. Both arrive as new optional fields of the assemble request; re-uploading a known binary with a group fills it in.
• Second Teapot round. When Teapot's response is partial, Sentry collects the shader binaries it reported missing, presigns the ones the project has uploaded and calls Teapot again with a distinct idempotency key. Any failure in this round keeps the first response and does not touch the circuit breaker.
• Shader group on the event. It becomes the culprit, the gpu.shader_group, gpu.material and gpu.shader_class tags, part of the GPU crash context, and the frame's filename when Teapot provides none, so it is visible in the issue list and on the stack trace.
• Housekeeping: one dxil file is kept per debug ID when redundant debug files are cleaned up.

No migration. Events without uploaded shaders are processed exactly as before.

Known Limitations

Source file and line numbers are out of scope. Mapping a DXIL shader back to source needs the shader PDBs and the Windows build of the Aftermath library, which Teapot does not run on.

Testing

Unit tests cover the debug file format, the lookup and presigning, the second round and its fallbacks, and the event fields. Verified end to end against a local stack with a UE 5.8 game, for a global compute shader and a material pixel shader: both events completed with the shader name and group and no missing debug files.

Before:

After:

Related Items

• getsentry/teapot#22 names the shader from the binary
• feat(cli): Upload DXIL shader binaries as debug files toolkit#1943 uploads the binaries with --type dxil (getsentry/sentry-cliDuring artifact lookup, also consider full paths w/o host #3489 is the legacy CLI version)
• getsentry/sentry-unrealAdd filtering for assignees #1678 exports and hashes them after the cook

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

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

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