feat: supporting advanced trace cases

[abelonogov-ld]

Summary

This PR adds React Native distributed-tracing documentation and the supporting LDObserve API surface, automatic track tracing via the LD plugin hook, an iOS/Android-parity example app, the RN external session-id wiring, and a tracing-origin matching fix.

Changes

Docs

• Distributed tracing guide (observability-react-native/guides/tracing.md): a cookbook of common patterns — root/nested spans, manual HTTP spans, automatic fetch/XHR instrumentation, exception recording, correlated logs, explicit context propagation across async boundaries, independent root spans via { root: true }, span events, end-to-end mobile-to-backend trace linking via tracingOrigins, and OpenTelemetry baggage propagation. Placed under guides/ (not the gitignored, Typedoc-generated docs/) and linked from the README.
• README: added a "Guides" link and a withSpan "Manual tracing" example.

SDK (observability-react-native)

• withSpan API (src/sdk/withSpan.ts, src/api/SpanScope.ts): an ergonomic wrapper that runs a callback inside a span and ends it automatically, with scope.child to parent nested spans off the captured context — important in RN where the active context is only tracked synchronously (lost across await).
• LDObserve.track (Observe, LDObserve, ObservabilityClient, InstrumentationManager): records a custom track span carrying the event key, optional numeric value, and properties — mirroring the iOS/Android track APIs.
• Automatic track tracing hook (plugin/observability.ts): the Observability plugin's TracingHook now implements afterTrack, so every LDClient.track call automatically emits a span (event key, optional metric value, evaluation context keys, and primitive track data) — no manual instrumentation needed. Flag-evaluation spans are additionally tagged with an internal attribute so SDK-emitted telemetry can be filtered out universally (independent of instrumentation scope).
• Root spans: { root: true } on startSpan/startActiveSpan is forwarded to the underlying OpenTelemetry tracer, which drops the active span from context so the new span begins a fresh trace regardless of ambient context.
• tracingOrigins matching fix (observability-shared/src/instrumentation/utils.ts + tests): match against the URL's origin (anchored host/subdomain regex) instead of an unanchored substring, so a configured host appearing as a query-param value in a third-party URL no longer leaks trace/baggage headers. String entries are escaped so . is literal.

React Native external session id (react-native-ld-session-replay)

• Wire the JS sessionId through to the native Android SDK so RN, native observability, and session replay share one session.id (SessionReplayClientAdapter.kt/.swift, NativeSessionReplayReactNative.ts, src/index.tsx).
• Bump com.launchdarkly:launchdarkly-android-client-sdk and the iOS LaunchDarklySessionReplay pod to 0.46.1.

Example app (react-native-ld-session-replay/example)

• New Tracing tab (TracingScreen.tsx) exercising every recipe in the guide, and an API tab (ApiScreen.tsx) mirroring the iOS TestApp (MainMenuViewModel): identify, spans, metrics, logs, errors, track (via LD client), network, crash.
• The independent-root-spans recipe creates root spans inside an active parent and asserts each child trace is detached from the parent and mutually unique (logs PASS/FAIL), so it actually exercises { root: true }.
• Register the Observability plugin with demo tracingOrigins in App.tsx; add @launchdarkly/observability-react-native + @opentelemetry/api deps; monorepo metro.config.js resolution (workspace watch folders + forced react/react-native singletons).
• Repo hygiene: gitignore the example's iOS/Ruby lock files and stop tracking Podfile.lock / Gemfile.lock.

Notes

• The original prompt referenced react-native-ld-session-replay, but that package is purely session replay/masking; the tracing API lives in observability-react-native, so the guide and APIs were added there.
• The LDObserve.track plain-dictionary (nested) reshaping is intentionally split into a separate stacked PR (feat(observability-react-native): accept plain nested dictionaries in track #650) on top of this branch.

Test plan

• observability-react-native unit tests pass (incl. tracingOrigins matching).
• Verify the guide renders on GitHub (Markdown + mermaid).
• Run the example app: Tracing tab recipes produce expected spans; root-span recipe logs PASS; LDClient.track auto-emits a span via the hook; API tab mirrors the iOS demo; shared session.id across JS + native (Android).
• Confirm trace/baggage headers are only sent to configured tracingOrigins.

---

Note

Medium Risk
Changes public tracing APIs and distributed trace header matching (security-sensitive); native session ID wiring and dependency bumps affect session-replay integration.

Overview
Adds manual tracing for React Native via LDObserve.withSpan and SpanScope (child, active, ctx) so span hierarchies survive awaits where OTel’s stack context does not, plus LDObserve.track and an afterTrack plugin hook so LDClient.track emits track spans like other mobile SDKs. Flag-evaluation spans get launchdarkly.internal for filtering.

Ships a tracing cookbook (guides/tracing.md) and README updates; the session-replay example gains Observability, Tracing and API tabs, and Metro monorepo fixes.

Security / propagation: tracingOrigins string hosts are origin-anchored in observability-shared so trace/baggage headers are not matched inside third-party URLs.

Session replay: Android forwards JS sessionId / serviceVersion into native observability; bumps Android/iOS LD dependencies; example lockfiles are gitignored.

E2E: Android sample sets sessionBackgroundTimeout to 3 minutes.

^{Reviewed by Cursor Bugbot for commit 9d06f16. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Vadman97]

could note to @dyozie-ld that we should make a docs update based on some of this?

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e2fc3e2. Configure here.}