docs(core): Correct enableTurboModuleTracking docs and document TurboModule plumbing - #6582
Merged
Conversation
…Module plumbing `enableTurboModuleTracking`'s documentation claimed it forwards Turbo Module lifecycle callbacks "to the higher-level Sentry instrumentation (crash attribution, per-module spans, aggregated stats)". Neither half holds. The option installs the native `TurboModulePerfLogger`, which forwards to a swappable sink — and `SentryTurboModulePerfController::setSink` has no caller outside RNSentryCocoaTester. Enabling it forwards every callback into `nullptr`. Everything the old text promised comes from `turboModuleContextIntegration()`, a JS-side wrapper registered whenever `enableNative` is true, which never reads this option. The two stacks share a name prefix and nothing else. That made the option look like the feature's on/off switch, so it is now `@internal` and its documentation says plainly that it emits nothing. Keeping it rather than removing it: the native install path is already shipped and a sink is the intended consumer, so the flag is the seam that work will land on. The AGENTS.md section exists because the same confusion is a trap for anyone touching this code, along with three others found while auditing it: `logger` imported from `@sentry/core` is the Logs API rather than the debug logger, so the existing `logger.warn` calls capture log events from the wrap hot path and recurse through the wrapped `RNSentry.captureEnvelope`; the crash-attribution frame must pop synchronously or an unrelated later native crash gets blamed on the module; and the emitted attribute keys are split across `turbo_module.*` and `turbo_modules.*` with the dynamic segment mid-key, which makes them unregistrable in sentry-conventions. Refs #6168
Contributor
Semver Impact of This PR⚪ None (no version bump detected) 📋 Changelog PreviewThis is how your changes will appear in the changelog.
🤖 This preview updates automatically when you update the PR. |
Contributor
alwx
marked this pull request as ready for review
August 10, 2026 12:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📢 Type of change
📜 Description
Documentation only. No behaviour change, no public API change.
enableTurboModuleTracking's JSDoc claimed it forwards Turbo Module callbacks "to the higher-level Sentry instrumentation (crash attribution, per-module spans, aggregated stats)". Neither half holds:TurboModulePerfLogger, which forwards to a sink — andSentryTurboModulePerfController::setSinkhas no caller outsideRNSentryCocoaTester. Enabling it emits nothing.turboModuleContextIntegration(), registered wheneverenableNativeis true, which never reads this option.The option is now
@internaland documented accurately. Kept rather than removed: the native install path already shipped in 8.17.0 and a sink is the intended consumer.Adds a
packages/core/AGENTS.mdsection covering the two independent stacks and the traps in them — notably thatloggerfrom@sentry/coreis the Logs API, not the debug logger, so the existinglogger.warncalls inturbomodule/capture log events from the wrap hot path and recurse through the wrappedRNSentry.captureEnvelope. Documented, not fixed, to keep this diff docs-only.💡 Motivation and Context
First slice of #6168. Two of that issue's premises were wrong and are corrected here rather than propagated into docs: there is no
turboModulesIntegration(it isturboModuleContextIntegration), andslowCallThresholdMs/ignoreTurboModules/maxTopModulesPerSpanare onTurboModuleContextOptions, not on the SDK options.The attribute rename is not here — conventions must merge before an SDK ships them, so it is gated on getsentry/sentry-conventions#564.
💚 How did you test it?
No tests added — docs and JSDoc only.
yarn build:sdk,yarn api-report:check(surface unchanged),yarn lint(0 errors),yarn circularDepCheck,yarn test— 1850 + 334 + 1 passing.Native and E2E suites not run.
📝 Checklist
sendDefaultPIIis enabled.🔮 Next steps
Separate follow-ups: the
logger→debugfix inturbomodule/, and #6542. When #6561 lands, the AGENTS.md section needs theturboModuleCallbacks.tsrow added back.