feat: supporting advanced trace cases

.gitignore

@@ -81,3 +81,9 @@ sdk/@launchdarkly/mobile-dotnet/**/*.csproj.user
 sdk/@launchdarkly/mobile-dotnet/**/*.sln
 sdk/@launchdarkly/mobile-dotnet/**/nupkgs/
 sdk/@launchdarkly/mobile-dotnet/**/xcuserdata/
+
+# React Native session-replay example: local iOS/Ruby tooling locks
+# (regenerated per-machine by `pod install` / `bundle install`).
+# NOTE: the monorepo yarn.lock is intentionally NOT ignored.
+sdk/@launchdarkly/react-native-ld-session-replay/example/ios/Podfile.lock
+sdk/@launchdarkly/react-native-ld-session-replay/example/Gemfile.lock

e2e/android/app/src/compose/java/com/example/androidobservability/BaseApplication.kt

@@ -20,6 +20,7 @@ import com.launchdarkly.sdk.android.LDClient
 import com.launchdarkly.sdk.android.LDConfig
 import io.opentelemetry.api.common.AttributeKey
 import io.opentelemetry.api.common.Attributes
+import kotlin.time.Duration.Companion.minutes
 
 open class BaseApplication : Application() {
 
@@ -43,6 +44,7 @@ open class BaseApplication : Application() {
         debug = true,
         otlpEndpoint = BuildConfig.OTLP_ENDPOINT,
         backendUrl = BuildConfig.BACKEND_URL,
+        sessionBackgroundTimeout = 3.minutes,
         tracesApi = ObservabilityOptions.TracesApi.enabled(),
         metricsApi = ObservabilityOptions.MetricsApi.enabled(),
         instrumentations = ObservabilityOptions.Instrumentations(

sdk/@launchdarkly/observability-react-native/README.md

@@ -39,6 +39,34 @@ const client = new LDClient(
 );
 ```
 
+### Manual tracing
+
+Use the `LDObserve` singleton to create spans by hand. `withSpan` runs your
+callback inside a span and ends it automatically — even across `await`s, where
+React Native only tracks the active context synchronously. Use `scope.child` to
+parent nested spans off the captured context:
+
+```typescript
+import { LDObserve } from '@launchdarkly/observability-react-native';
+
+await LDObserve.withSpan('LoadProducts', async (scope) => {
+  scope.span.setAttribute('source', 'api');
+
+  // `scope.child` parents off LoadProducts even after the await above.
+  const products = await scope.child('FetchFromApi', async (fetchScope) => {
+    const response = await fetch('https://api.example.com/products');
+    fetchScope.span.setAttribute('http.status_code', response.status);
+    return response.json();
+  });
+
+  scope.span.setAttribute('product_count', products.length);
+});
+```
+
+## Guides
+
+- [Tracing Guide](guides/tracing.md) — a cookbook of common tracing patterns (spans, nested operations, error handling, correlated logs, and end-to-end mobile-to-backend traces).
+
 ## About LaunchDarkly
 
 - LaunchDarkly Observability provides a way to collect and send errors, logs, traces to LaunchDarkly. Correlate latency or exceptions with your releases to safely ship code.

sdk/@launchdarkly/observability-react-native/src/api/Observe.ts

@@ -7,6 +7,7 @@ import {
 import { Metric } from './Metric'
 import { RequestContext } from './RequestContext'
 import { SessionInfo } from '../client/SessionManager'
+import { SpanScope, WithSpanOptions } from './SpanScope'
 
 export interface Observe {
 	/**
@@ -64,6 +65,20 @@ export interface Observe {
 	 */
 	recordLog(message: any, level: string, attributes?: Attributes): void
 
+	/**
+	 * Record a custom track event as a `track` span.
+	 *
+	 * Mirrors the iOS and Android `LDObserve.track(...)` API (and `LDClient.track`):
+	 * emits a span named `track` carrying the event `key`, an optional numeric
+	 * `value` for LaunchDarkly numeric custom metrics, and any `properties` as
+	 * additional span attributes.
+	 *
+	 * @param key The key for the event.
+	 * @param properties Optional data associated with the event; attached as span attributes.
+	 * @param metricValue Optional numeric value used by LaunchDarkly experimentation for numeric custom metrics.
+	 */
+	track(key: string, properties?: Attributes, metricValue?: number): void
+
 	/**
 	 * Parse headers to extract request context.
 	 * @param headers The headers to parse
@@ -116,6 +131,30 @@ export interface Observe {
 		ctx?: Context,
 	): T
 
+	/**
+	 * Start a span, run `fn` within it, and end the span automatically.
+	 *
+	 * This is an ergonomic wrapper over {@link startSpan} designed for React
+	 * Native, where the active context is tracked only synchronously and is lost
+	 * across each `await`. The {@link SpanScope} passed to `fn` exposes a
+	 * {@link SpanScope.child} method that parents child spans off the captured
+	 * context, so the hierarchy is preserved across `await`s and even under
+	 * concurrent (`Promise.all`) work — without manually threading context.
+	 *
+	 * The span's status is set to `OK` on success, or `ERROR` (with the error
+	 * recorded) if `fn` throws or returns a rejecting promise. If `fn` returns a
+	 * promise, the span ends when it settles and the promise is returned.
+	 *
+	 * @param spanName The span name
+	 * @param fn The callback to run within the span's scope
+	 * @param options Optional span options, including an explicit `parent`
+	 */
+	withSpan<T>(
+		spanName: string,
+		fn: (scope: SpanScope) => T,
+		options?: WithSpanOptions,
+	): T
+
 	/**
 	 * Get the context from a span.
 	 * @param span The span to get the context from

sdk/@launchdarkly/observability-react-native/src/api/SpanScope.ts

@@ -0,0 +1,67 @@
+import { Context, Span as OtelSpan, SpanOptions } from '@opentelemetry/api'
+
+/**
+ * Options accepted by {@link Observe.withSpan} and {@link SpanScope.child}.
+ *
+ * In addition to the standard OpenTelemetry {@link SpanOptions}, an explicit
+ * `parent` context can be supplied. This is the mechanism that makes spans
+ * nest correctly across `await`s in React Native, where the active context is
+ * tracked only synchronously (see the distributed tracing guide).
+ */
+export type WithSpanOptions = SpanOptions & {
+	/**
+	 * The context to parent the new span under. When omitted the currently
+	 * active context is used. {@link SpanScope.child} sets this automatically to
+	 * the parent scope's context, so children nest correctly even after an
+	 * `await`.
+	 */
+	parent?: Context
+}
+
+/**
+ * A handle to a span started with {@link Observe.withSpan}.
+ *
+ * A scope captures its own span context, so child spans created via
+ * {@link SpanScope.child} are parented correctly even across `await`
+ * boundaries — without manually threading context through your code.
+ */
+export interface SpanScope {
+	/** The underlying OpenTelemetry span. */
+	readonly span: OtelSpan
+
+	/**
+	 * This span's context. Pass it anywhere an explicit parent {@link Context}
+	 * is required.
+	 */
+	readonly ctx: Context
+
+	/**
+	 * Start a child span parented to *this* scope, run `fn`, and end the span
+	 * automatically. The span's status is set to `OK` on success, or `ERROR`
+	 * (with the thrown error recorded) if `fn` throws or rejects.
+	 *
+	 * Because the parent is captured from this scope rather than read from the
+	 * active context, the child nests correctly even when created after an
+	 * `await`.
+	 *
+	 * @param name The child span name
+	 * @param fn The callback to run within the child scope
+	 * @param options Optional span options
+	 */
+	child<T>(
+		name: string,
+		fn: (scope: SpanScope) => T,
+		options?: WithSpanOptions,
+	): T
+
+	/**
+	 * Run `fn` with *this* span active. Use this to parent auto-instrumented
+	 * `fetch`/`XMLHttpRequest` spans that are started after an `await` (the
+	 * point at which React Native loses the active context). Calls started in
+	 * the synchronous portion of a {@link Observe.withSpan} callback are already
+	 * parented automatically.
+	 *
+	 * @param fn The callback to run with this span active
+	 */
+	active<T>(fn: () => T): T
+}

sdk/@launchdarkly/observability-react-native/src/api/index.ts

@@ -1,3 +1,4 @@
 export * from './Options'
 export * from './Metric'
 export * from './RequestContext'
+export type { SpanScope, WithSpanOptions } from './SpanScope'

sdk/@launchdarkly/observability-react-native/src/client/InstrumentationManager.ts

@@ -6,6 +6,7 @@ import {
 	Gauge,
 	Histogram,
 	Span as OtelSpan,
+	SpanKind,
 	SpanOptions,
 	trace,
 	propagation,
@@ -59,6 +60,9 @@ export type InstrumentationManagerOptions = Required<ReactNativeOptions> & {
 	projectId: string
 }
 
+// Span name for custom track events, matching the iOS/Android SDKs (`track`).
+const TRACK_SPAN_NAME = 'track'
+
 export class InstrumentationManager {
 	private traceProvider?: WebTracerProvider
 	private loggerProvider?: LoggerProvider
@@ -393,6 +397,36 @@ export class InstrumentationManager {
 		}
 	}
 
+	/**
+	 * Single emitter for `track` spans, mirroring the iOS/Android `track` API.
+	 * Emits a span named `track` carrying the event `key`, an optional numeric
+	 * `value`, and any caller `properties` as attributes.
+	 */
+	public track(
+		key: string,
+		properties?: Attributes,
+		metricValue?: number,
+	): void {
+		try {
+			const sessionId = this.sessionManager?.getSessionInfo().sessionId
+			const attributes: Attributes = {
+				...(properties ?? {}),
+				key,
+				...(metricValue !== undefined ? { value: metricValue } : {}),
+				...(sessionId ? { ['highlight.session_id']: sessionId } : {}),
+			}
+
+			this.getTracer()
+				.startSpan(TRACK_SPAN_NAME, {
+					kind: SpanKind.CLIENT,
+					attributes,
+				})
+				.end()
+		} catch (e) {
+			console.error('Failed to record track event:', e)
+		}
+	}
+
 	public runWithHeaders(
 		name: string,
 		headers: Record<string, string>,

sdk/@launchdarkly/observability-react-native/src/client/ObservabilityClient.ts

@@ -167,6 +167,15 @@ export class ObservabilityClient {
 		this.instrumentationManager.recordLog(message, level, attributes)
 	}
 
+	public track(
+		key: string,
+		properties?: Attributes,
+		metricValue?: number,
+	): void {
+		if (this.options.disableTraces) return
+		this.instrumentationManager.track(key, properties, metricValue)
+	}
+
 	public parseHeaders(headers: Record<string, string>): RequestContext {
 		const sessionInfo = this.sessionManager.getSessionInfo()
 		return {

sdk/@launchdarkly/observability-react-native/src/constants/featureFlags.ts

@@ -19,9 +19,17 @@ export const FEATURE_FLAG_CONTEXT_ID_ATTR = `${FEATURE_FLAG_SCOPE}.context.id`
 export const FEATURE_FLAG_ENV_ATTR = `${FEATURE_FLAG_SCOPE}.environment.id`
 
 export const LD_SCOPE = 'launchdarkly'
+// Span name for `track` events recorded via the LaunchDarkly client's
+// afterTrack hook. Uses the simple "track" name to match the mobile SDKs
+// (iOS / Android / Flutter).
+export const LD_TRACK_SPAN_NAME = 'track'
 export const FEATURE_FLAG_APP_ID_ATTR = `${LD_SCOPE}.application.id`
 export const FEATURE_FLAG_APP_VERSION_ATTR = `${LD_SCOPE}.application.version`
 export const LD_IDENTIFY_RESULT_STATUS = `${LD_SCOPE}.identify.result.status`
+// Universal, cross-SDK marker for telemetry produced internally by the
+// LaunchDarkly SDK itself (e.g. flag-evaluation spans), so it can be filtered or
+// hidden regardless of which SDK/instrumentation-scope emitted it.
+export const LD_INTERNAL_ATTR = `${LD_SCOPE}.internal`
 
 export const FEATURE_FLAG_REASON_ATTRS: {
 	[key in keyof LDEvaluationReason]: string

sdk/@launchdarkly/observability-react-native/src/plugin/observability.ts

@@ -26,6 +26,8 @@ import {
 	getCanonicalKey,
 	getContextKeys,
 	LD_IDENTIFY_RESULT_STATUS,
+	LD_INTERNAL_ATTR,
+	LD_TRACK_SPAN_NAME,
 } from '../constants/featureFlags'
 import type { LDEvaluationReason } from '@launchdarkly/js-sdk-common'
 import {
@@ -35,6 +37,7 @@ import {
 	IdentifySeriesContext,
 	EvaluationSeriesContext,
 	EvaluationSeriesData,
+	TrackSeriesContext,
 } from '@launchdarkly/react-native-client-sdk'
 
 class TracingHook implements Hook {
@@ -126,6 +129,9 @@ class TracingHook implements Hook {
 					[FEATURE_FLAG_KEY_ATTR]: hookContext.flagKey,
 					[FEATURE_FLAG_PROVIDER_ATTR]: 'LaunchDarkly',
 					[FEATURE_FLAG_VALUE_ATTR]: JSON.stringify(detail.value),
+					// Mark this as SDK-internal telemetry so it can be filtered
+					// out universally (independent of instrumentation scope).
+					[LD_INTERNAL_ATTR]: true,
 				})
 
 				span.setStatus({ code: 1 })
@@ -146,6 +152,41 @@ class TracingHook implements Hook {
 
 		return data
 	}
+
+	afterTrack(hookContext: TrackSeriesContext): void {
+		try {
+			const trackAttributes: Attributes = {
+				...this.metaAttributes,
+				...(hookContext.context
+					? getContextKeys(hookContext.context)
+					: {}),
+				// Spread user-supplied track data first so the LaunchDarkly event
+				// `key` and metric `value` set below always win over any
+				// same-named properties in the payload. Non-primitive members are
+				// ignored by OpenTelemetry.
+				...(typeof hookContext.data === 'object' &&
+				hookContext.data !== null
+					? (hookContext.data as Attributes)
+					: {}),
+				key: hookContext.key,
+				...(hookContext.metricValue !== undefined &&
+				hookContext.metricValue !== null
+					? { value: hookContext.metricValue }
+					: {}),
+			}
+
+			_LDObserve.startActiveSpan(LD_TRACK_SPAN_NAME, (span) => {
+				span.setAttributes(trackAttributes)
+				span.setStatus({ code: 1 })
+				span.end()
+			})
+		} catch (error) {
+			_LDObserve.recordError(error as Error, {
+				'track.key': hookContext.key,
+				'error.context': 'track_tracing',
+			})
+		}
+	}
 }
 
 export class Observability implements LDPlugin {

sdk/@launchdarkly/observability-react-native/src/sdk/LDObserve.ts

@@ -9,8 +9,10 @@ import { ObservabilityClient } from '../client/ObservabilityClient'
 import { Metric } from '../api/Metric'
 import { RequestContext } from '../api/RequestContext'
 import { Observe } from '../api/Observe'
+import { SpanScope, WithSpanOptions } from '../api/SpanScope'
 import { BufferedClass } from './BufferedClass'
 import { noOpSpan } from '../utils/NoOpSpan'
+import { NOOP_SPAN_OPS, runInSpan, SpanOps } from './withSpan'
 
 class LDObserveClass
 	extends BufferedClass<ObservabilityClient>
@@ -56,6 +58,10 @@ class LDObserveClass
 		return this._bufferCall('recordLog', [message, level, attributes])
 	}
 
+	track(key: string, properties?: Attributes, metricValue?: number): void {
+		return this._bufferCall('track', [key, properties, metricValue])
+	}
+
 	parseHeaders(headers: Record<string, string>): RequestContext {
 		const response = this._bufferCall('parseHeaders', [headers])
 		return this._isLoaded
@@ -127,6 +133,18 @@ class LDObserveClass
 			: fn(noOpSpan.setAttribute('method', 'startActiveSpan'))
 	}
 
+	withSpan<T>(
+		spanName: string,
+		fn: (scope: SpanScope) => T,
+		options?: WithSpanOptions,
+	): T {
+		// When loaded, `this` provides real startSpan/recordError that execute
+		// immediately (no buffering). Before init we use no-op span ops so the
+		// callback still runs without enqueueing stray spans.
+		const ops: SpanOps = this._isLoaded ? this : NOOP_SPAN_OPS
+		return runInSpan(ops, spanName, fn, options)
+	}
+
 	getContextFromSpan(span: OtelSpan): Context {
 		const response = this._bufferCall('getContextFromSpan', [span])
 		return this._isLoaded ? response : context.active()