docs: make DatadogProvider the documented way to initialize - #14
Merged
Conversation
The only place that showed a working initialization snippet was the core package README, which npm renders but the repository root does not link to. A reader who starts from the root README finds no example at all and falls through to CONTRIBUTING.md or the example app, and both of those showed DdSdkReactNative.initialize(). That path is not equivalent. It awaits the native SDK and installs the JavaScript auto-instrumentation only afterwards, and that instrumentation is a live patch on XMLHttpRequest.prototype rather than a buffered call - so a request issued before the patch lands produces no resource event at all. RUM calls like startView are buffered and do survive, which makes the failure look resource-specific when it is really about ordering. Calling initialize() earlier shortens the window but cannot close it. DatadogProvider installs the instrumentation during its own render pass and initializes the native SDK second, which closes it. The migration guide told people to switch without ever saying why - its Overview section was empty - so the change read as a style preference. It now explains the ordering, and covers the one case that genuinely still needs the manual call: react-native-navigation, which has no single React root to wrap. The example app keeps that path for its Wix entry point, now labelled with the trade-off. Also in this change: - Root README gains the initialization example and links to the core reference. - firstPartyHosts is documented where it matters: without it resources are still reported but cannot be correlated with a backend trace, and resourceTracingSamplingRate defaults to 20 rather than 100. - Add docs/troubleshooting_no_data.md, which TROUBLESHOOTING.md has been linking to all along without the file existing. - Correct the site option: this SDK accepts CN and STAGING, not the seven upstream sites the core README still listed, and CN is the default. - Repair every in-repo link. They pointed at github.com/flashcat (wrong org) and at main, master and develop, none of which is this repository's default branch. In-repo targets are now relative paths, which no branch rename can break. - Drop the remaining upstream product name from prose, keeping it only where it is a real API identifier or a log string the SDK actually emits.
"Calling initialize() earlier shortens the window but cannot close it" was stated absolutely, and it is not true in general. Inside a React tree it holds - children mount before any effect of yours can await the call. But awaiting initialization in the entry file before the app is registered does close it, at the cost of startup latency. The Wix guidance further down already implied as much, so the two read as contradicting each other. Say which case each applies to, and name the trade-off, so a reader weighing the manual path against the provider can tell what they would actually be giving up.
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
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.
Problem
The only place in this repository that showed a working initialization snippet was
packages/core/README.md, which npm renders as the package page but the repository root never links to. A reader who starts from the root README finds no example at all, and the two places they fall through to —CONTRIBUTING.mdand the example app — both showedDdSdkReactNative.initialize().Those are not equivalent, and the difference is a correctness one:
DdSdkReactNative.initialize()awaits the native SDK and installs the JavaScript auto-instrumentation only afterwards. That instrumentation is a live patch onXMLHttpRequest.prototype, not a buffered call, so a request issued before the patch lands produces no resource event at all — never recorded, not recoverable.DdRum.startVieware buffered and do survive, so an app initialized this way reports views and native crashes normally while silently losing the API calls it makes while starting up. That asymmetry makes the failure look resource-specific when it is about ordering.initialize()earlier shortens the window but cannot close it.DatadogProviderinstalls the instrumentation during its own render pass and initializes the native SDK second, which does close it. The migration guide already told readers to switch, but its## Overviewsection was empty, so the change read as a style preference rather than a bug fix.Changes
docs/migrating_to_datadog_provider.md: fill in the Overview with the ordering rationale; documentinitializationModeinline instead of linking to a file that does not exist; add the react-native-navigation case, which genuinely still needs the manual call because it has no single React root to wrap.README.md: add the initialization example and link to the core package reference.packages/core/README.md: explain why the provider rather than the manual call, and whatfirstPartyHostsis for — without it resources are reported but cannot be correlated with a backend trace, andresourceTracingSamplingRatedefaults to 20 rather than 100.CONTRIBUTING.md: replace the manual snippet with the provider one.example/src/ddUtils.tsx: label both setups with when each is correct. The manual one stays — the example's Wix entry point needs it.docs/troubleshooting_no_data.md, whichTROUBLESHOOTING.mdhas linked to all along without the file existing.CNandSTAGING, andCNis the default. The core README still listed the seven upstream sites and defaulted toUS1, which would send data nowhere reachable.main,masteranddevelop, none of which is this repository's default branch. In-repo targets are now relative paths, which no branch rename can break.Verification
DdSdkReactNative.tsxandDdRumResourceTracking.tsxrather than from the rebranded product name, sogrepfinds them.SdkVerbosity.DEBUGdoes admit thoseINFO-level lines — confirmed againstInternalLog's level map.