Skip to content

docs: backend symbolizer against Dart 3.14 stacks - #39

Open
krassx wants to merge 2 commits into
nextgenfrom
docs/dart-3-14-symbolization
Open

krassx wants to merge 2 commits into
nextgenfrom
docs/dart-3-14-symbolization

Conversation

@krassx

@krassx krassx commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Measured what the Bugsee backend's dart_symbolize does with stacks from Dart 3.14 / Flutter 3.50 --obfuscate --split-debug-info builds, and corrected the repo's claims.

  • The worker (bugsee-background-worker: crash/managed/dart.py, symbolfiles/flutter.py) strips everything before the first #00 and pipes the frames to dart_symbolize (bugsee-symbolication-aux, dart-symbolize/, commit 06db90f, Dart 2.19.6, vendored 2023 native_stack_traces).
  • Real Flutter 3.50.0 artifacts: with the header stripped it symbolizes (Dart 2.19.6 and 3.14 builds). With the header it crashes, as does flutter symbolize 3.50 (native_stack_traces 0.6.1). Cause: Dart 3.14 symbols have _kDartSnapshotText and no _kDartIsolateSnapshotInstructions. native_stack_traces 0.7.x decodes both forms; the backend works today because of the stripping and the virt address.
  • iOS: the release build writes a Mach-O symbols file with an LC_UUID; decoded with a synthetic stack only. A real iOS stack is not verified.
  • Adds a privacy-safe fixture (stack text, no symbols, no paths) with a test, makes verify_symbolization.dart --tool feed the worker's input, and updates doc/exceptions.md, doc/verification.md, PLAN.md and the harness not-covered entry.

No backend change was made; the suggested patch is for its owner.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8

Ran the backend's dart_symbolize (bugsee-symbolication-aux 06db90f, Dart 2.19.6
and 3.14) on the real stack and symbols of a Flutter 3.50.0 release build: it
decodes the stack the worker feeds it (header stripped) and crashes on the
same stack with its header, like flutter symbolize 3.50 (native_stack_traces
0.6.1); Dart 3.14 symbols have _kDartSnapshotText, not
_kDartIsolateSnapshotInstructions. 0.7.x decodes both. Adds the stack text as a
fixture with a test, makes verify_symbolization.dart feed --tool the worker's
input, and corrects the docs, PLAN gaps and the harness not-covered entry.
iOS: Mach-O symbols file checked with a synthetic stack only.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8
Change-Id: Ia2bf5c2674e13979c14785958f96fa9ac028d7cd
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Explain Change →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 48 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e20c7668-b799-4c42-a5f9-f88b749b7469
Commits

Reviewing files that changed from the base of the PR and between 66dd1f9 and 0045aa4.

Files selected for processing: 3

  • doc/exceptions.md
  • doc/verification.md
  • scripts/verify_symbolization.dart

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • Documentation
    • Added guidance on Android arm64 Dart 3.14 stack symbolization, including decoder behavior with and without stack headers and known limitations for iOS verification.
  • Tests
    • Added coverage using a real obfuscated Android stack trace, checking build ID and frame extraction and preservation of the full trace in exception payloads.

The changes document dart_symbolize results for Dart 3.14 Android traces, including its failure with a stack header and its success after header removal. They describe the tool’s build-ID lookup and decoder versions, record synthetic iOS results and remaining verification gaps, and add a real Android trace fixture with worker-contract tests.

Possibly related PRs

Change: Other

Merge Risk: Minimal · previous review 66dd1

This PR documents how the backend symbolizer handles Dart 3.14 Android stacks and adds a test fixture. It does not change runtime behavior, so merge risk is minimal.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: documentation and verification of the Bugsee backend symbolizer (dart_symbolize) against Dart 3.14 stack traces. The changeset adds Dart 3.14 measurements, a fixture…
Description check Passed The description states that the author measured the backend's dart_symbolize on Dart 3.14 / Flutter 3.50 builds. It names the worker files, the header-stripping behavior, the crash with the header, …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: documentation and verification of the Bugsee backend symbolizer (dart_symbolize) against Dart 3.14 stack traces. The changeset adds Dart 3.14 measurements, a fixture and test, and doc updates that match this focus. The title uses the 'docs:' prefix, which fits because most changes are documentation. It does not mention the verification-tool or test changes, which is acceptable.

Full details: Description check

Explanation

The description states that the author measured the backend's dart_symbolize on Dart 3.14 / Flutter 3.50 builds. It names the worker files, the header-stripping behavior, the crash with the header, the iOS verification limits, and the fixture, test, tool, and doc changes. This matches the changeset closely.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 94367e34-51f5-454a-bad7-cb8eea0261c3
Commits

Reviewing files that changed from the base of the PR and between 25ea503 and 66dd1f9.

Files selected for processing: 7

  • PLAN.md
  • doc/exceptions.md
  • doc/verification.md
  • scripts/device/android_scenarios.dart
  • scripts/verify_symbolization.dart
  • test/exceptions_worker_contract_test.dart
  • test/fixtures/exceptions/real_obfuscated_android_arm64_dart_3_14_trace.txt

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@claude

claude Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Claude finished @krassx's task in 33s —— View job


Review of PR #39 (docs: backend symbolizer against Dart 3.14 stacks)

  • Read the diff against origin/nextgen
  • Read the worker-contract port, the verify script and the surrounding docs
  • Posted one inline finding

I did not run flutter test or any script: neither flutter nor dart is installed on this runner. I also could not check the measurements against the private backend repos. All of this is from reading the diff and the repo.

Finding (P3 Low): --tool in scripts/verify_symbolization.dart does not feed dart_symbolize exactly what the worker sends. The strip keeps the newline and the indentation, while the worker port in the test trims every frame. See the inline comment.

Not verified, and worth saying when merging:

  • The claim that the decoder "falls back to the virt address" is an inference from the stripped stack decoding. The code of the backend tool is not in this repo.
  • The native_stack_traces 0.7.0 changelog wording differs between files. doc/exceptions.md and doc/verification.md say "removal of the VM isolate"; the comment in scripts/verify_symbolization.dart says "adjusted the readers to Dart 3.12+ snapshots". Pick one and check it against the changelog.

Summary

  1. Overall risk: Low. The change is docs, one dev script, one test and one text fixture. No product code, no bridge and no native pins are touched.
  2. Merge recommendation: Approve once the P3 item is fixed or accepted, and once someone with the private repos confirms the table.
  3. Most important issue: Make the --tool input match the worker's, so the verification script stays a faithful stand-in.
  4. Positives:
    • The fixture holds stack text only, with no symbols or paths.
    • The doc states what was not verified: the production upload, a real iOS stack, and Flutter 3.41.
    • The old claim that the worker's tool was the one verified was corrected in doc/exceptions.md, doc/verification.md, PLAN.md and the harness not-covered entry.
    • The new test pins the worker's virt-address dependency.

Comment thread scripts/verify_symbolization.dart Outdated
// With --tool: the worker's input, the stack from the first `#00` on.
if (tool != null) {
final m = RegExp(r'^(.*?)(\s*#00.*)', dotAll: true).firstMatch(stack);
if (m != null) stack = m.group(2)!;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3 Low: --tool input is not exactly what the worker sends

Problem: m.group(2) keeps the leading \s* (a newline plus the 4-space indent of #00) and every frame keeps its indent. The worker port in test/exceptions_worker_contract_test.dart (obfuscatedFrameLines) drops the empty first line and trim()s every frame. The comment above and doc/exceptions.md say this is "the input the worker gives it".

Impact: The check is meant to stand in for the backend's input. If dart_symbolize is sensitive to indentation or a leading blank line, this script can pass or fail where production does the opposite. The table in doc/exceptions.md says the stripped stack "symbolized", but I could not tell whether that run used the trimmed or the untrimmed form.

Fix: Reuse the same rule as the port: split into lines, drop a leading empty line, trim each line, and join with \n. Or soften the wording to "from the first #00" and say the whitespace is not normalised.

verify_symbolization.dart --tool now drops a leading empty line and trims each
frame (obfuscatedFrameLines). The earlier stripped-stack runs used the untrimmed
text flutter.py passes; re-run with the trimmed form on all three builds (Dart
2.19.6, 3.14, 0.7.1 vendored): same frames. The three places that cited the
native_stack_traces 0.7.0 changelog now quote it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8
Change-Id: Ie1dd86e4929ee3b1c0e00bef5b594097333b62d6
@claude

claude Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Claude finished @krassx's task in 22s —— View job


Re-review of PR #39 after the latest push (0045aa4)

  • Read the diff against origin/nextgen
  • Checked the earlier P3 finding and the changelog-wording note against 0045aa4
  • Read the worker port, the verify script, the fixture and the new tests

I read the code only. I did not run flutter test or any script, because flutter and dart are not installed on this runner. I could not check the measurements in the tables against the private backend repos either.

Earlier findings, both fixed by 0045aa4:

  • --tool input differed from the worker port (P3). scripts/verify_symbolization.dart now cuts from the first #00, drops a leading empty line and trims each line. That is the same rule as obfuscatedFrameLines in test/exceptions_worker_contract_test.dart. The comment and doc/exceptions.md both say so. They also say symbolfiles/flutter.py passes the untrimmed text, and that both forms decoded the same when measured.
  • Inconsistent native_stack_traces 0.7.0 changelog wording. The script comment, doc/exceptions.md and doc/verification.md now all quote "Adjusts snapshot readers for the removal of the VM isolate." The docs also say 0.7.0 itself was not run.

New findings: none. I checked these specifically:

  • The script imports dart:convert, so LineSplitter resolves.
  • The fixture ends in a single newline. obfuscatedFrameLines therefore returns 3 frames plus <asynchronous suspension>, which matches the test's length == 4.
  • The fixture is stack text only, with no symbols and no paths.
  • The virt-address regex matches all three frame lines in the fixture.
  • native_stack_traces: ^0.7.1 in pubspec.yaml matches the "0.7.1" the docs state.

Not verified, worth saying when merging:

  • The claim that the decoder falls back to the virt address is an inference from the header-less stack decoding. The backend tool's code is not in this repo.
  • Someone with the private repos should confirm the decoder table.
  • A real iOS stack, the production symbols upload and Flutter 3.41 are listed as unverified in the docs. That matches what the PR body says.

Summary

  1. Overall risk: Low. The PR changes docs, one dev script, one test and one text fixture. It touches no product code, bridge or native pins.
  2. Merge recommendation: Approve. The only open item is the backend-side confirmation of the table, which cannot be done from this repo.
  3. Most important issues to fix: none.
  4. Positives:
    • The --tool check now matches the worker's input rule, so it is a faithful stand-in.
    • The fixture and test pin the worker's dependency on the virt address and on stripping the header.
    • The not-verified list is explicit.
    • The old "the worker's tool was run" claims are corrected in doc/exceptions.md, doc/verification.md, PLAN.md and the harness not-covered entry.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant