Skip to content

feat(ios): Attach a flame graph to JS hang events - #7042

Open
alwx wants to merge 11 commits into
mainfrom
alwx/feature/js-hang-flamegraph
Open

alwx wants to merge 11 commits into
mainfrom
alwx/feature/js-hang-flamegraph

Conversation

@alwx

@alwx alwx commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

📢 Type of change

  • Bugfix
  • New feature
  • Enhancement
  • Refactoring

📜 Description

Adds the experimental, iOS-only option attachJsHangFlamegraph. When enableJsHangTracking reports a JS hang, the native tracker now builds a flame graph from all Hermes samples of its existing 300 ms window and attaches it as flamegraph.json with the event.flamegraph attachment type. The event stack, grouping, and other event fields do not change.

The flag reaches native through the new setAttachJsHangFlamegraph bridge method, so the released startJsHangTracking signature stays the same and older native binaries still start JS hang tracking. Android gets no-op methods.

The flame graph also keeps Hermes native frames (built-in and host functions such as [Native] jsonStringify) with only a function name, so time spent in them is not counted to the calling JS function. JS frames are marked in_app: true and native frames in_app: false, so the flame graph view shows JS code as application functions. The device cannot tell app code from library code in the bundle, so React and React Native frames are marked in_app too until the backend symbolicates the JS frames of the attachment. The sample gets a button that blocks the JS thread with nested work.

💡 Motivation and Context

The JS hang event kept one stack and discarded all other samples of the window. A flame graph shows where the JS thread spent its time during the hang. It uses the same attachment format as the sentry-cocoa MetricKit hang flame graphs, and Relay already accepts it with platform: "javascript".

💚 How did you test it?

  • Link to Sentry: https://sentry-sdks.sentry.io/issues/7852567307/?project=5428561. The latest event comes from the current head (300cad2a6), built in Release for the iOS 26.1 simulator, where JS frames show as application functions.
  • XCTest tests for the flame graph builder. The full RNSentryCocoaTester suite passes (225 tests, 0 failures).
  • New and updated Jest tests for the integration, the default integrations, and the wrapper. yarn test, yarn lint, yarn circularDepCheck, and api-report:check pass.
  • Manual check in the React Native sample (iOS 26.1 simulator, Release, New Architecture): a real JS hang event arrived in Sentry with flamegraph.json (event.flamegraph). The flame graph had 23 samples in the 300 ms window, including [Native] jsonStringify and [Native] arrayPrototypeSort with the JS comparator under it.

📝 Checklist

  • I added tests to verify 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.
  • All tests passing.
  • Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.
  • No breaking changes.

🔮 Next steps

  • Check an Old Architecture build.
  • The backend does not apply source maps to JS frames in flame graph attachments yet. This needs a separate issue.

alwx added a commit that referenced this pull request Nov 16, 2026
Replace the PR link placeholder in the attachJsHangFlamegraph entry with #7042.
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Semver Impact of This PR

⚪ None (no version bump detected)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).


  • feat(ios): Attach a flame graph to JS hang events by alwx in #7042
  • chore(sample): Remove unused Detox setup from the React Native sample by antonis and claude in #7072
  • ci(ios): Build TestFlight sample with Xcode 27 by philprime with sentry-junior in #7065
  • perf(android): Create SDK view managers on demand by alwx in #7049
  • fix(core): Remove web Replay and Feedback from native bundles by default by huextrat, claude and antonis in #7062
  • fix(core): Define UnsafeObject locally instead of deep importing it by alwx in #7061
  • chore(deps): update Android SDK to v8.65.0 by github-actions in #7058

🤖 This preview updates automatically when you update the PR.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor
Messages
📖 Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 009136d

@alwx
alwx marked this pull request as ready for review November 16, 2026 13:32
@alwx
alwx requested review from a team, antonis and lucas-zimerman as code owners November 16, 2026 13:32
@alwx
alwx requested review from buenaflor, itaybre, markushi, philprime and runningcode and removed request for a team November 16, 2026 13:32
@antonis antonis added the ready-to-merge Triggers the full CI test suite label Nov 17, 2026
@sentry

sentry Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

📲 Install Builds

Android

🔗 App Name App ID Version Configuration
Sentry RN io.sentry.reactnative.sample 8.36.0 (116) Release

⚙️ sentry-react-native Build Distribution Settings

Comment thread packages/core/test/wrapper.test.ts Resolved
Comment thread packages/core/ios/RNSentry.mm Resolved
Comment thread packages/core/src/js/options.ts Resolved

@antonis antonis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Overall LGTM 🎉
Tested locally on an iOS Release build and got a flamegraph :)

Sentry link: https://sentry-sdks.sentry.io/issues/SENTRY-REACT-NATIVE-WDT/events/0992dabdb1054187bcb30475a757ddae/

Screenshot 2026-11-17 at 11 55 08

Left a few comments but nothing blocking.

Let's also merge the latest from main and move the changelog to unreleased.

@philprime

Copy link
Copy Markdown
Member

@antonis @alwx is it expected that none of the frames in the flame graph are marked as in-app?

@antonis

antonis commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

@antonis @alwx is it expected that none of the frames in the flame graph are marked as in-app?

Good point @philprime 👍 I guess not but I think @alwx is already iterating on this.

alwx commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

@philprime yep that's fixed already

@philprime

Copy link
Copy Markdown
Member

@lucas-zimerman

Copy link
Copy Markdown
Collaborator

Nothing extra to add from my side, Antonis and Philip already covered the main points from my review

@alwx
alwx requested a review from antonis November 19, 2026 10:16
@alwx

alwx commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Debugging MetricKit is much harder but I'm doing it here: #7059
This particular one is ready, JS events get send, so in my opinion this PR is valuable on its own and can be merged already.

@antonis antonis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@alwx let's adda link in the description to check how this PR works individually. My tests above show everything as system function

The JS hang tracker samples the JS thread for 300 ms but keeps only one stack for the event. Add flamegraphFromHermesTrace:newestFirst:bundleDebugId:, which turns all samples of the Hermes trace into an event.flamegraph payload (version 1, platform javascript), so the time spent during the hang becomes visible.

The builder keeps the JS frames of each sample, puts each Hermes frame into the frame table once, and builds one tree per thread with inclusive sample counts from caller to callee, without recursion. For a profile trace it uses only the samples within the sample window of the newest one. The tree of the thread that gives the event stack gets thread_attributed, and a known bundle Debug ID adds a sourcemap debug image. It returns nil for traces without JS samples, for invalid traces, and for payloads larger than 10 MiB.

The event stack and the flame graph now share one Hermes frame mapping and one stack walk, so their frames cannot differ. The report path does not call the builder yet. XCTest coverage is added to RNSentryCocoaTester.
alwx added 7 commits November 19, 2026 11:37
The JS hang event carried only one stack, although the tracker samples the JS thread for the whole window. When the new attachFlamegraph flag is on, the tracker now builds a flame graph from the same Hermes trace and attaches it to the event as flamegraph.json with the event.flamegraph attachment type.

The tracker reads the flag before it leaves the tracker thread. The capture goes through a new SentrySDKWrapper method that adds the attachment in a scope block. When the flag is off, or when the builder returns nothing (no trace, no JS samples, or more than 10 MiB), the event is captured as before. The capture stays inside the existing @try/@catch, and the event fields do not change.

RNSentry exports setAttachJsHangFlamegraph as a separate method, so the released startJsHangTracking signature stays the same for older JS bundles.
The native JS hang tracker on iOS can attach a flame graph of the sampled JS stacks to its events. The new experimental attachJsHangFlamegraph option turns this on. It is off by default and works only together with enableJsHangTracking.

Sentry.init passes the option to jsHangTrackingIntegration. After init, the integration calls the new setAttachJsHangFlamegraph bridge method before startJsHangTracking. The flag is a separate method, so the released startJsHangTracking signature does not change. The wrapper skips the call when an older native binary does not have the method, so JS hang tracking still starts there. initNativeSdk does not send the option to the native SDK.

Android gets methods that do nothing for both architectures, because JS hang tracking is iOS only. The API report is regenerated.
Add a CHANGELOG entry for the experimental, iOS-only attachJsHangFlamegraph option. The entry says that the frames in the flame graph are not yet symbolicated with source maps. The PR link is a placeholder until the PR is open.

The React Native sample already enables enableJsHangTracking. It now also enables attachJsHangFlamegraph, so the manual check of JS hang events includes the flame graph attachment.
Replace the PR link placeholder in the attachJsHangFlamegraph entry with #7042.
The existing hang buttons block the JS thread with a flat loop, so the flame graph of their JS hang event has a single path and shows nothing useful.

The new button on the Errors screen blocks the JS thread for 5 seconds with nested named functions. Each batch calls hashRecords and sortRandomNumbers through processBatch, so the flame graph attached by attachJsHangFlamegraph shows a call tree with two branches.
The flame graph kept only JS frames, so time spent in built-in and host functions, such as JSON.stringify, Array.prototype.sort, or a synchronous native module call, was counted to the calling JS function.

The flame graph now also keeps the non-JavaScript Hermes frames, as frames with only a function name. This matches how JS profiles map these frames. Native frames stay in their place in the stack, so a JS callback that a native function calls, such as a sort comparator, stays under it. A sample with only native frames now counts too, because a JS thread that waits in a synchronous native call is a hang. The [root] frame is still left out.

The event stack does not change. It keeps only JS frames, and thread attribution still uses the JS frames.

A run of the React Native sample on an iOS simulator gave 23 samples in the 300 ms window, including [Native] jsonStringify, [Native] arrayPrototypeSort with the comparator under it, [Native] stringPrototypeConcat, [Native] dateNow, and [Native] arrayFrom.
The Sentry flame graph view treats a frame without in_app as a system function, so every frame of the JS hang flame graph was shown as a system function.

The flame graph now sets in_app to true for JS frames and to false for Hermes native frames. The device cannot tell app code from library code in the bundle, because only source maps show the original file. So React and React Native frames are marked in_app too, until the backend symbolicates the JS frames of flame graph attachments.

The event stack does not copy in_app, so it does not change. A test checks this.
@alwx
alwx force-pushed the alwx/feature/js-hang-flamegraph branch from dfc0c9f to 300cad2 Compare November 19, 2026 10:43

alwx commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

@antonis the problem was that the commit with the fix ended up in a wrong PR (the one about the MetricKit improvements). I fixed that.
Also added the link to the description (it's now the first item under "How did you test it?")

@alwx
alwx requested a review from antonis November 19, 2026 11:10

@antonis antonis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thank you for your work on this @alwx 🙇
I've retested (link) and LGTM on my side.
Let's check with the team before shipping since it has public api changes and fix or resolve my previous nit/comment threads.

alwx added 3 commits November 19, 2026 15:15
Review feedback on #7042. The default integrations test mocked jsHangTrackingIntegration to check its arguments. It now initializes the integration that getDefaultIntegrations returns and checks what reaches native: setAttachJsHangFlamegraph(true) and startJsHangTracking with the timeout in milliseconds.

The wrapper test for a throwing setAttachJsHangFlamegraph now also checks that the error is logged with debug.error, not only that the call does not throw.
Review feedback on #7042. The attachJsHangFlamegraph docs said that the flame graph shows the time spent during the hang. It covers only the sample window of about 300 ms when the SDK detected the hang, so the JSDoc and the CHANGELOG entry now say that.
Review feedback on #7042. Hermes gives each call tree position its own frame id, so the same function reached from different callers got several entries in the frame table, and frames with the same content under one parent became separate sibling nodes. The develop docs say that producers should deduplicate frames by content. The builder now keys the frame table on filename, function, line, and column, and caches the result per Hermes id.

The report path now parses the Hermes trace once and passes the result to the event stack and the flame graph builders. The flame graph builder logs when it fails or when the payload exceeds 10 MiB, like the capture path does. setAttachJsHangFlamegraph catches exceptions at the bridge boundary.

@buenaflor buenaflor left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Had some questions for my clanker regarding this and this stood out to me - disregard if this is expected:


When the hang window only has native frames (GC, [Native] jsonStringify, etc.), the event goes out without a stack, so these all group together by the timeout message. With this flag on, the flame graph still gets attached in that case.

Relay now fills in a missing exception stack from the flame graph (getsentry/relay#6520). So these events show up with a stack of [Native] … frames and get split into separate issues per native function, instead of staying in the single "no stack" group.

Could we only attach the flame graph when frames.count > 0? That way the event's stack stays as it is, and the flame graph is just extra detail.

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

Labels

ready-to-merge Triggers the full CI test suite

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants