feat(react-native): Add NetworkRecordingOptions and network sanitizer (#485)

## Summary

Ports `NetworkRecordingOptions` and the network sanitizer from
`highlight-run` into
`@launchdarkly/observability-react-native`, wiring them up to the
existing OpenTelemetry
`FetchInstrumentation` and `XMLHttpRequestInstrumentation` via the
`applyCustomAttributesOnSpan`
hook.

When `recordHeadersAndBody` is enabled, the SDK will add sanitized
request/response headers
(and response bodies for XHR, request bodies for string fetch bodies) as
attributes on the HTTP
spans that OTel already creates. Sensitive headers (`authorization`,
`cookie`,
`proxy-authorization`, `set-cookie`, `token`) are always redacted by
default, regardless of
other configuration.

(Note: This PR was mostly generated with Claude.)

---

## Breaking Changes

**None**. The new `networkRecording` option on `ReactNativeOptions` is
optional and defaults to `{}`
(feature off). Existing SDK behavior is unchanged.

---

## New APIs

The following are added to the public API surface of
`@launchdarkly/observability-react-native`:

**`NetworkRecordingOptions`** (new exported type):
```typescript
type NetworkRecordingOptions = {
  recordHeadersAndBody?: boolean      // master gate; default false
  networkHeadersToRedact?: string[]   // headers to redact (case-insensitive)
  headerKeysToRecord?: string[]       // header whitelist (overrides redact)
  networkBodyKeysToRedact?: string[]  // JSON body keys to redact
  bodyKeysToRecord?: string[]         // JSON body key whitelist (overrides redact)
}
```

**`ReactNativeOptions.networkRecording`** (new optional field):
```typescript
networkRecording?: NetworkRecordingOptions
```

This is a **minor version bump** (new opt-in API, no breaking changes).

### Note: `urlBlocklist` placement

In the web SDK (`highlight-run`), `urlBlocklist` lives inside
`NetworkRecordingOptions`. In the
React Native SDK it is intentionally omitted from
`NetworkRecordingOptions` because it already
exists as a top-level field on `ReactNativeOptions` (where it controls
OTel trace header
propagation). The existing top-level `urlBlocklist` is reused to also
gate header/body recording,
so there is no duplication.

---

## Files Copied From `highlight-run`

- `src/listeners/network-listener/utils/models.ts` — copied from

`sdk/highlight-run/src/client/listeners/network-listener/utils/models.ts`
with no changes

- `src/listeners/network-listener/utils/network-sanitizer.ts` — copied
from

`sdk/highlight-run/src/client/listeners/network-listener/utils/network-sanitizer.ts`
with no
  changes

- `src/listeners/network-listener/utils/xhr-listener.ts` — copied from

`sdk/highlight-run/src/client/listeners/network-listener/utils/xhr-listener.ts`,
stripped to
`getBodyThatShouldBeRecorded` and its size-limit constants only; removed
`XHRListener`,
`getBodyData`, the `json-stringify-safe` import, and all other
browser-patching code

**New file** (no direct equivalent in `highlight-run`):

- `src/listeners/network-listener/network-listener.ts` — exports
`FetchHook` and `XHRHook`,
curried functions that take `NetworkRecordingOptions` and return the
appropriate
`applyCustomAttributesOnSpan` handlers for OTel's `FetchInstrumentation`
and
  `XMLHttpRequestInstrumentation`

---

## Testing

The existing source files copied from `highlight-run` have no unit tests
in that package, so adding unit tests is deferred to a follow-up PR, if
desired. The natural candidates would be:

- `network-sanitizer.test.ts` — `sanitizeHeaders` and `sanitizeUrl`
(pure functions)
- `xhr-listener.test.ts` — `getBodyThatShouldBeRecorded` (pure function)
- `network-listener.test.ts` — `FetchHook`/`XHRHook` with a mocked
`Span`

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds optional recording of HTTP headers/bodies onto OTel spans;
despite redaction controls, mistakes or misconfiguration could capture
sensitive data and increase span size/perf overhead.
> 
> **Overview**
> Adds a new `networkRecording` option (via exported
`NetworkRecordingOptions`) to optionally attach sanitized
request/response headers and bodies to OpenTelemetry
`FetchInstrumentation`/`XMLHttpRequestInstrumentation` spans.
> 
> Introduces a network listener + sanitizer utilities that **always**
sanitize span URL attributes (redacting credentials and sensitive query
params), redact known sensitive headers, support header/body
allowlists/redaction lists, and applies a built-in
`DEFAULT_URL_BLOCKLIST` (merged into `urlBlocklist`) to prevent
recording for specific auth/token endpoints.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
45db54b. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: beekld

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

@@ -1,6 +1,46 @@
 import { Attributes } from '@opentelemetry/api'
 import type { LDContext } from '@launchdarkly/js-sdk-common'
 
+export type NetworkRecordingOptions = {
+	/**
+	 * This enables recording XMLHttpRequest and Fetch headers and bodies.
+	 * @default false
+	 */
+	recordHeadersAndBody?: boolean
+	/**
+	 * Request and response headers where the value is not recorded.
+	 * The header value is replaced with '[REDACTED]'.
+	 * These headers are case-insensitive.
+	 * `recordHeadersAndBody` needs to be enabled.
+	 * This option will be ignored if `headerKeysToRecord` is set.
+	 * @example
+	 * networkHeadersToRedact: ['Secret-Header', 'Plain-Text-Password']
+	 */
+	networkHeadersToRedact?: string[]
+	/**
+	 * Specifies the keys for request/response JSON body that should not be recorded.
+	 * The body value is replaced with '[REDACTED]'.
+	 * These keys are case-insensitive.
+	 * `recordHeadersAndBody` needs to be `true`. Otherwise this option will be ignored.
+	 * @example bodyKeysToRedact: ['secret-token', 'plain-text-password']
+	 */
+	networkBodyKeysToRedact?: string[]
+	/**
+	 * Specifies the keys for request/response headers to record.
+	 * This option will override `networkHeadersToRedact` if specified.
+	 * `recordHeadersAndBody` needs to be `true`. Otherwise this option will be ignored.
+	 * @example headerKeysToRecord: ['id', 'pageNumber']
+	 */
+	headerKeysToRecord?: string[]
+	/**
+	 * Specifies the keys for request/response JSON body to record.
+	 * This option will override `networkBodyKeysToRedact` if specified.
+	 * `recordHeadersAndBody` needs to be `true`. Otherwise this option will be ignored.
+	 * @example bodyKeysToRecord: ['id', 'pageNumber']
+	 */
+	bodyKeysToRecord?: string[]
+}
+
 export interface ReactNativeOptions {
 	/**
 	 * The service name for the application.
@@ -81,6 +121,12 @@ export interface ReactNativeOptions {
 	 */
 	disableMetrics?: boolean
 
+	/**
+	 * Options for recording network request and response headers and bodies,
+	 * with controls for redacting sensitive data.
+	 */
+	networkRecording?: NetworkRecordingOptions
+
 	/**
 	 * A function that returns a friendly name for a given context.
 	 * This name will be used to identify the session in the observability UI.

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

@@ -39,6 +39,10 @@ import {
 import { SpanStatusCode } from '@opentelemetry/api'
 import { W3CBaggagePropagator, CompositePropagator } from '@opentelemetry/core'
 import { ReactNativeOptions } from '../api/Options'
+import {
+	FetchHook,
+	XHRHook,
+} from '../listeners/network-listener/network-listener'
 import { Metric } from '../api/Metric'
 import { SessionManager } from './SessionManager'
 import {
@@ -161,14 +165,23 @@ export class InstrumentationManager {
 		trace.setGlobalTracerProvider(this.traceProvider)
 
 		const corsPattern = getCorsUrlsPattern(this.options.tracingOrigins)
+		const networkRecording = this.options.networkRecording
 
 		registerInstrumentations({
 			instrumentations: [
 				new FetchInstrumentation({
 					propagateTraceHeaderCorsUrls: corsPattern,
+					applyCustomAttributesOnSpan: FetchHook(
+						networkRecording,
+						this.options.urlBlocklist,
+					),
 				}),
 				new XMLHttpRequestInstrumentation({
 					propagateTraceHeaderCorsUrls: corsPattern,
+					applyCustomAttributesOnSpan: XHRHook(
+						networkRecording,
+						this.options.urlBlocklist,
+					),
 				}),
 			],
 		})

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

@@ -14,6 +14,7 @@ import {
 	ATTR_TELEMETRY_SDK_VERSION,
 } from '@opentelemetry/semantic-conventions'
 import { ReactNativeOptions } from '../api/Options'
+import { DEFAULT_URL_BLOCKLIST } from '../listeners/network-listener/utils/network-sanitizer'
 import { Metric } from '../api/Metric'
 import { RequestContext } from '../api/RequestContext'
 import { SessionManager } from '../client/SessionManager'
@@ -70,7 +71,11 @@ export class ObservabilityClient {
 			disableMetrics: options.disableMetrics ?? false,
 			disableTraces: options.disableTraces ?? false,
 			tracingOrigins: options.tracingOrigins ?? false,
-			urlBlocklist: options.urlBlocklist ?? [],
+			urlBlocklist: [
+				...(options.urlBlocklist ?? []),
+				...DEFAULT_URL_BLOCKLIST,
+			],
+			networkRecording: options.networkRecording ?? {},
 			contextFriendlyName:
 				options.contextFriendlyName ?? (() => undefined),
 		}

sdk/@launchdarkly/observability-react-native/src/listeners/network-listener/network-listener.ts

@@ -0,0 +1,170 @@
+import { Span } from '@opentelemetry/api'
+import { FetchCustomAttributeFunction } from '@opentelemetry/instrumentation-fetch'
+import { NetworkRecordingOptions } from '../../api/Options'
+import { sanitizeHeaders, sanitizeUrl } from './utils/network-sanitizer'
+import { getBodyThatShouldBeRecorded } from './utils/xhr-listener'
+
+const applyNetworkAttributes = (
+	span: Span,
+	url: string,
+	recording: NetworkRecordingOptions,
+	urlBlocklist: string[],
+	requestHeaders: Record<string, string>,
+	responseHeaders: Record<string, string>,
+	requestBody: string | undefined,
+	responseBody: string | undefined,
+) => {
+	// Always overwrite OTel-set URL attributes with sanitized version to
+	// redact credentials and sensitive query params.
+	if (url) {
+		url = sanitizeUrl(url)
+		span.setAttribute('http.url', url)
+		span.setAttribute('url.full', url)
+	}
+
+	if (urlBlocklist.some((blocked) => url.toLowerCase().includes(blocked))) {
+		return
+	}
+
+	if (!recording.recordHeadersAndBody) {
+		return
+	}
+
+	const headersToRedact = (recording.networkHeadersToRedact ?? []).map((h) =>
+		h.toLowerCase(),
+	)
+	const headersToRecord = recording.headerKeysToRecord?.map((h) =>
+		h.toLowerCase(),
+	)
+	const bodyKeysToRedact = (recording.networkBodyKeysToRedact ?? []).map(
+		(k) => k.toLowerCase(),
+	)
+	const bodyKeysToRecord = recording.bodyKeysToRecord?.map((k) =>
+		k.toLowerCase(),
+	)
+
+	// Request headers
+	const sanitizedReqHeaders = sanitizeHeaders(
+		headersToRedact,
+		requestHeaders,
+		headersToRecord,
+	)
+	Object.entries(sanitizedReqHeaders).forEach(([key, value]) => {
+		span.setAttribute(`http.request.header.${key}`, value)
+	})
+
+	// Request body
+	if (requestBody !== undefined) {
+		const sanitizedBody = getBodyThatShouldBeRecorded(
+			requestBody,
+			bodyKeysToRedact,
+			bodyKeysToRecord,
+			requestHeaders,
+		)
+		if (sanitizedBody != null) {
+			span.setAttribute('http.request.body', sanitizedBody)
+		}
+	}
+
+	// Response headers
+	const sanitizedRespHeaders = sanitizeHeaders(
+		headersToRedact,
+		responseHeaders,
+		headersToRecord,
+	)
+	Object.entries(sanitizedRespHeaders).forEach(([key, value]) => {
+		span.setAttribute(`http.response.header.${key}`, value)
+	})
+
+	// Response body
+	if (responseBody !== undefined) {
+		const sanitizedBody = getBodyThatShouldBeRecorded(
+			responseBody,
+			bodyKeysToRedact,
+			bodyKeysToRecord,
+			responseHeaders,
+		)
+		if (sanitizedBody != null) {
+			span.setAttribute('http.response.body', sanitizedBody)
+		}
+	}
+}
+
+export const FetchHook =
+	(
+		recording: NetworkRecordingOptions,
+		urlBlocklist: string[],
+	): FetchCustomAttributeFunction =>
+	(span, request, result) => {
+		const url = request instanceof Request ? request.url : ''
+
+		let requestHeaders: Record<string, string> = {}
+		if (request instanceof Request) {
+			requestHeaders = Object.fromEntries(request.headers.entries())
+		} else if (
+			request &&
+			typeof request === 'object' &&
+			'headers' in request &&
+			request.headers
+		) {
+			requestHeaders = Object.fromEntries(
+				new Headers(request.headers as HeadersInit).entries(),
+			)
+		}
+
+		const bodyInit =
+			request instanceof Request
+				? undefined
+				: (request as RequestInit).body
+		const requestBody = typeof bodyInit === 'string' ? bodyInit : undefined
+
+		const responseHeaders =
+			result instanceof Response
+				? Object.fromEntries(result.headers.entries())
+				: {}
+
+		applyNetworkAttributes(
+			span,
+			url,
+			recording,
+			urlBlocklist,
+			requestHeaders,
+			responseHeaders,
+			requestBody,
+			undefined, // Fetch response body is a stream; not recorded
+		)
+	}
+
+export const XHRHook =
+	(recording: NetworkRecordingOptions, urlBlocklist: string[]) =>
+	(span: Span, xhr: XMLHttpRequest) => {
+		const url = (xhr as any)._url ?? ''
+
+		const responseHeaders: Record<string, string> = {}
+		xhr.getAllResponseHeaders()
+			.trim()
+			.split(/[\r\n]+/)
+			.forEach((line) => {
+				const parts = line.split(': ')
+				const header = parts.shift()
+				if (header) {
+					responseHeaders[header] = parts.join(': ')
+				}
+			})
+
+		const responseBody =
+			xhr.responseType === '' || xhr.responseType === 'text'
+				? xhr.responseText
+				: undefined
+
+		applyNetworkAttributes(
+			span,
+			url,
+			recording,
+			urlBlocklist,
+			{}, // XHR does not expose request headers
+			responseHeaders,
+			undefined, // XHR request body is not accessible post-send
+			responseBody,
+		)
+	}

sdk/@launchdarkly/observability-react-native/src/listeners/network-listener/utils/models.ts

@@ -0,0 +1,3 @@
+export interface Headers {
+	[key: string]: any
+}