[FEAT] HTTP Headers Capture

.gitignore

@@ -109,3 +109,5 @@ packages/react-native-babel-plugin/svg-map.json
 
 # Session Replay assets
 packages/react-native-session-replay/assets/*
+
+.planning

packages/core/src/DdSdkReactNative.tsx

@@ -515,6 +515,8 @@ export class DdSdkReactNative {
         const resourceTraceSampleRate =
             configuration.rumConfiguration?.resourceTraceSampleRate ||
             RUM_DEFAULTS.resourceTraceSampleRate;
+        const headerCaptureRules =
+            configuration.rumConfiguration?.headerCaptureRules;
         const logEventMapper = configuration.logsConfiguration?.logEventMapper;
         const errorEventMapper =
             configuration.rumConfiguration?.errorEventMapper;
@@ -550,10 +552,18 @@ export class DdSdkReactNative {
             });
         }
 
+        if (!trackResources && headerCaptureRules != null) {
+            InternalLog.log(
+                'headerCaptureRules is set but trackResources is false. Header capture will be disabled.',
+                SdkVerbosity.WARN
+            );
+        }
+
         if (trackResources) {
             DdRumResourceTracking.startTracking({
                 resourceTraceSampleRate,
-                firstPartyHosts
+                firstPartyHosts,
+                headerCaptureRules
             });
         }
 

packages/core/src/__tests__/DdSdkReactNative.test.tsx

@@ -676,7 +676,8 @@ describe('DdSdkReactNative', () => {
                         match: 'something.fr',
                         propagatorTypes: ['datadog']
                     }
-                ]
+                ],
+                headerCaptureRules: undefined
             });
         });
 

packages/core/src/__tests__/DdSdkReactNativeConfiguration.test.ts

@@ -61,6 +61,7 @@ describe('DdSdkReactNativeConfiguration', () => {
                     "customEndpoint": undefined,
                     "errorEventMapper": null,
                     "firstPartyHosts": [],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": undefined,
                     "longTaskThresholdMs": 0,
                     "nativeCrashReportEnabled": false,
@@ -205,6 +206,7 @@ describe('DdSdkReactNativeConfiguration', () => {
                         ],
                       },
                     ],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": 0.123,
                     "longTaskThresholdMs": 567,
                     "nativeCrashReportEnabled": true,
@@ -308,6 +310,7 @@ describe('DdSdkReactNativeConfiguration', () => {
                     "customEndpoint": undefined,
                     "errorEventMapper": null,
                     "firstPartyHosts": [],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": 0,
                     "longTaskThresholdMs": false,
                     "nativeCrashReportEnabled": false,

packages/core/src/config/__tests__/FileBasedConfiguration.test.ts

@@ -55,6 +55,7 @@ describe('FileBasedConfiguration', () => {
                         ],
                       },
                     ],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": 456,
                     "longTaskThresholdMs": 44,
                     "nativeCrashReportEnabled": true,
@@ -167,6 +168,7 @@ describe('FileBasedConfiguration', () => {
                         ],
                       },
                     ],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": undefined,
                     "longTaskThresholdMs": 44,
                     "nativeCrashReportEnabled": false,
@@ -231,6 +233,7 @@ describe('FileBasedConfiguration', () => {
                     "customEndpoint": undefined,
                     "errorEventMapper": null,
                     "firstPartyHosts": [],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": undefined,
                     "longTaskThresholdMs": 0,
                     "nativeCrashReportEnabled": false,

packages/core/src/config/async/AutoInstrumentationConfiguration.ts

@@ -9,6 +9,7 @@ import type { ResourceEventMapper } from '../../rum/eventMappers/resourceEventMa
 import type { FirstPartyHost } from '../../rum/types';
 import type { LogEventMapper } from '../../types';
 import { LOGS_DEFAULTS } from '../features/LogsConfiguration';
+import type { HeaderCaptureRule } from '../features/RumConfiguration.type';
 import { RUM_DEFAULTS } from '../features/RumConfiguration';
 import type { TraceConfiguration } from '../features/TraceConfiguration';
 
@@ -24,6 +25,7 @@ export type AutoInstrumentationConfiguration = {
         readonly useAccessibilityLabel?: boolean;
         readonly actionNameAttribute?: string;
         readonly resourceTraceSampleRate?: number;
+        readonly headerCaptureRules?: 'defaults' | HeaderCaptureRule[];
         readonly nativeCrashReportEnabled?: boolean;
         readonly nativeLongTaskThresholdMs?: number;
         readonly nativeViewTracking?: boolean;
@@ -55,6 +57,7 @@ export type AutoInstrumentationParameters = {
         readonly errorEventMapper: ErrorEventMapper | null;
         readonly resourceEventMapper: ResourceEventMapper | null;
         readonly firstPartyHosts: FirstPartyHost[];
+        readonly headerCaptureRules?: 'defaults' | HeaderCaptureRule[];
     };
     readonly logsConfiguration?: {
         readonly logEventMapper: LogEventMapper | null;
@@ -114,7 +117,8 @@ export const addDefaultValuesToAutoInstrumentationConfiguration = (
                 RUM_DEFAULTS.nativeViewTracking,
             firstPartyHosts:
                 features.rumConfiguration.firstPartyHosts ||
-                RUM_DEFAULTS.getFirstPartyHosts()
+                RUM_DEFAULTS.getFirstPartyHosts(),
+            headerCaptureRules: features.rumConfiguration.headerCaptureRules
         },
         logsConfiguration: {
             logEventMapper:

packages/core/src/config/features/RumConfiguration.ts

@@ -10,6 +10,7 @@ import type { FirstPartyHost } from '../../rum/types';
 import { VitalsUpdateFrequency } from '../types';
 
 import type {
+    HeaderCaptureRule,
     RumConfigurationOptions,
     RumConfigurationType
 } from './RumConfiguration.type';
@@ -37,6 +38,10 @@ const DEFAULTS = {
     trackInteractions: false,
     trackMemoryWarnings: true,
     trackNonFatalAnrs: undefined,
+    headerCaptureRules: undefined as
+        | 'defaults'
+        | HeaderCaptureRule[]
+        | undefined,
     trackResources: false,
     trackWatchdogTerminations: false,
     useAccessibilityLabel: true,
@@ -112,6 +117,10 @@ export class RumConfiguration implements RumConfigurationType {
     // Track non-fatal ANRs enabled
     public trackNonFatalAnrs?: boolean = DEFAULTS.trackNonFatalAnrs;
 
+    // Header Capture Rules
+    public headerCaptureRules: 'defaults' | HeaderCaptureRule[] | undefined =
+        DEFAULTS.headerCaptureRules;
+
     // Track Watchdog Terminations enabled
     public trackWatchdogTerminations: boolean =
         DEFAULTS.trackWatchdogTerminations;

packages/core/src/config/features/RumConfiguration.type.ts

@@ -37,6 +37,108 @@ export interface RumConfigurationRequired {
     trackErrors?: boolean;
 }
 
+/**
+ * Captures a predefined set of caching and content headers from both
+ * request and response.
+ *
+ * Default headers captured:
+ * - **Response:** cache-control, etag, age, expires, content-type,
+ *   content-encoding, content-length, vary, server-timing, x-cache
+ * - **Request:** cache-control, content-type
+ *
+ * Optionally scoped to specific URLs via `forURLs`.
+ */
+export type DefaultsRule = {
+    type: 'defaults';
+    /**
+     * URL patterns to scope this rule to. Supports hostname-only
+     * ('api.example.com') or hostname+path prefix ('api.example.com/v2').
+     * Omit to match all URLs.
+     */
+    forURLs?: string[];
+};
+
+/**
+ * Captures the specified headers from both request and response.
+ *
+ * Use this when the same header names should be captured regardless
+ * of direction (e.g. 'content-type', 'x-request-id').
+ * Optionally scoped to specific URLs via `forURLs`.
+ */
+export type MatchHeadersRule = {
+    type: 'matchHeaders';
+    /**
+     * Header names to capture from both request and response.
+     * Preserved as-is; compared case-insensitively at capture time.
+     */
+    headers: string[];
+    /**
+     * URL patterns to scope this rule to. Supports hostname-only
+     * ('api.example.com') or hostname+path prefix ('api.example.com/v2').
+     * Omit to match all URLs.
+     */
+    forURLs?: string[];
+};
+
+/**
+ * Captures the specified headers from requests only.
+ *
+ * Use this when you need to capture request-specific headers
+ * (e.g. 'x-request-id', 'if-none-match') without capturing response headers.
+ * Optionally scoped to specific URLs via `forURLs`.
+ */
+export type MatchRequestHeadersRule = {
+    type: 'matchRequestHeaders';
+    /**
+     * Request header names to capture.
+     * Preserved as-is; compared case-insensitively at capture time.
+     */
+    headers: string[];
+    /**
+     * URL patterns to scope this rule to. Supports hostname-only
+     * ('api.example.com') or hostname+path prefix ('api.example.com/v2').
+     * Omit to match all URLs.
+     */
+    forURLs?: string[];
+};
+
+/**
+ * Captures the specified headers from responses only.
+ *
+ * Use this when you need to capture response-specific headers
+ * (e.g. 'x-request-id', 'x-ratelimit-remaining') without capturing
+ * request headers.
+ * Optionally scoped to specific URLs via `forURLs`.
+ */
+export type MatchResponseHeadersRule = {
+    type: 'matchResponseHeaders';
+    /**
+     * Response header names to capture.
+     * Preserved as-is; compared case-insensitively at capture time.
+     */
+    headers: string[];
+    /**
+     * URL patterns to scope this rule to. Supports hostname-only
+     * ('api.example.com') or hostname+path prefix ('api.example.com/v2').
+     * Omit to match all URLs.
+     */
+    forURLs?: string[];
+};
+
+/**
+ * A composable header capture rule.
+ *
+ * Discriminated union on the `type` field. Multiple rules can be combined
+ * in an array. Matching rules are merged additively (union of headers).
+ * If at least one scoped rule (explicit `forURLs` patterns) matches a URL,
+ * catch-all rules (omitted `forURLs` / `['*']`) are ignored for that URL.
+ */
+export type HeaderCaptureRule =
+    | DefaultsRule
+    | MatchHeadersRule
+    | MatchRequestHeadersRule
+    | MatchResponseHeadersRule;
+
 /**
  * Optional RUM configuration values.
  */
@@ -71,6 +173,21 @@ export interface RumConfigurationOptions {
      */
     firstPartyHosts?: FirstPartyHost[];
 
+    /**
+     * Controls which resource headers the SDK captures on network requests.
+     *
+     * - **Omitted** (default): No headers are captured.
+     * - `'defaults'`: Captures a predefined set of caching and content headers
+     *   across all URLs.
+     * - `HeaderCaptureRule[]`: An array of composable rules. When multiple rules
+     *   match a URL their header sets are merged. If at least one scoped rule
+     *   (with explicit `forURLs` patterns) matches, catch-all rules (no `forURLs`
+     *   or `['*']`) are ignored for that URL.
+     *
+     * Requires `trackResources: true` to take effect.
+     */
+    headerCaptureRules?: 'defaults' | HeaderCaptureRule[];
+
     /**
      * Initial resource collection threshold in seconds.
      */

packages/core/src/index.tsx

@@ -107,6 +107,13 @@ export {
     DdBabelInteractionTracking,
     __ddExtractText
 };
+export type {
+    HeaderCaptureRule,
+    DefaultsRule,
+    MatchHeadersRule,
+    MatchRequestHeadersRule,
+    MatchResponseHeadersRule
+} from './config/features/RumConfiguration.type';
 export type {
     Timestamp,
     FirstPartyHost,

packages/core/src/rum/instrumentation/resourceTracking/DdRumResourceTracking.tsx

@@ -7,12 +7,14 @@
 import BigInt from 'big-integer';
 
 import { InternalLog } from '../../../InternalLog';
+import type { HeaderCaptureRule } from '../../../config/features/RumConfiguration.type';
 import { SdkVerbosity } from '../../../config/types/SdkVerbosity';
 import { getGlobalInstance } from '../../../utils/singletonUtils';
 import type { FirstPartyHost } from '../../types';
 
 import { DistributedTracingSampling } from './distributedTracing/distributedTracingSampling';
 import { firstPartyHostsRegexMapBuilder } from './distributedTracing/firstPartyHosts';
+import { compileHeaderCaptureConfig } from './headerCapture/compileHeaderConfig';
 import { XHRProxy } from './requestProxy/XHRProxy/XHRProxy';
 import type { RequestProxy } from './requestProxy/interfaces/RequestProxy';
 
@@ -40,10 +42,12 @@ class RumResourceTracking {
      */
     startTracking({
         resourceTraceSampleRate,
-        firstPartyHosts
+        firstPartyHosts,
+        headerCaptureRules
     }: {
         resourceTraceSampleRate: number;
         firstPartyHosts: FirstPartyHost[];
+        headerCaptureRules?: 'defaults' | HeaderCaptureRule[] | undefined;
     }): void {
         // extra safety to avoid proxying the XHR class twice
         if (this._isTracking) {
@@ -55,11 +59,15 @@ class RumResourceTracking {
         }
 
         this._requestProxy = XHRProxy.createWithResourceReporter();
+        const headerCaptureConfig = compileHeaderCaptureConfig(
+            headerCaptureRules
+        );
         this._requestProxy.onTrackingStart({
             tracingSamplingRate: resourceTraceSampleRate,
             firstPartyHostsRegexMap: firstPartyHostsRegexMapBuilder(
                 firstPartyHosts
-            )
+            ),
+            headerCaptureConfig
         });
 
         InternalLog.log(

packages/core/src/rum/instrumentation/resourceTracking/__tests__/__utils__/XMLHttpRequestMock.ts

@@ -27,7 +27,7 @@ export class XMLHttpRequestMock implements XMLHttpRequest {
     timeout: number = -1;
     upload: XMLHttpRequestUpload = {} as XMLHttpRequestUpload;
     withCredentials: boolean = false;
-    getAllResponseHeaders = jest.fn();
+    getAllResponseHeaders = jest.fn().mockReturnValue('');
     overrideMimeType = jest.fn();
     DONE = 4 as const;
     HEADERS_RECEIVED = 2 as const;

packages/core/src/rum/instrumentation/resourceTracking/distributedTracing/firstPartyHosts.ts

@@ -15,7 +15,7 @@ export type Hostname = { _type: 'Hostname' } & string;
 export const NO_MATCH_REGEX = new RegExp('a^');
 
 // From https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
-const escapeRegExp = (string: string) => {
+export const escapeRegExp = (string: string) => {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string
 };