Skip to content

docs: make DatadogProvider the documented way to initialize - #14

Merged
Fiona2016 merged 2 commits into
publishfrom
docs/onboarding-datadog-provider
Aug 26, 2026
Merged

docs: make DatadogProvider the documented way to initialize#14
Fiona2016 merged 2 commits into
publishfrom
docs/onboarding-datadog-provider

Conversation

@Fiona2016

Copy link
Copy Markdown
Collaborator

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.md and the example app — both showed DdSdkReactNative.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 on XMLHttpRequest.prototype, not a buffered call, so a request issued before the patch lands produces no resource event at all — never recorded, not recoverable.
  • RUM calls such as DdRum.startView are 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.
  • 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 does close it. The migration guide already told readers to switch, but its ## Overview section 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; document initializationMode inline 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.
  • Root 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 what firstPartyHosts is for — without it resources are reported but cannot be correlated with a backend trace, and resourceTracingSamplingRate defaults 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.
  • Add docs/troubleshooting_no_data.md, which TROUBLESHOOTING.md has linked to all along without the file existing.
  • Correct the site option: this SDK accepts CN and STAGING, and CN is the default. The core README still listed the seven upstream sites and defaulted to US1, which would send data nowhere reachable.
  • Repair every in-repo link. They pointed at the wrong GitHub organization 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 where it is a real API identifier or a log string the SDK actually emits.

Verification

  • Every relative link in the touched files resolves on disk (checked programmatically; 0 dead).
  • Log strings quoted in the new troubleshooting guide were taken verbatim from DdSdkReactNative.tsx and DdRumResourceTracking.tsx rather than from the rebranded product name, so grep finds them. SdkVerbosity.DEBUG does admit those INFO-level lines — confirmed against InternalLog's level map.
  • Documentation only; no source behaviour changes.

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.
@Fiona2016
Fiona2016 merged commit d7c8886 into publish Aug 26, 2026
1 check passed
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