[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/README.md

@@ -83,7 +83,8 @@ export default function App() {
 
 `trackFetchResources` tracks calls made through the Expo-installed global
 `fetch`. Direct imports retained from `expo/fetch` are not intercepted. XHR
-tracking remains enabled for clients such as axios.
+tracking remains enabled for clients such as axios. Resource header capture
+(`headerCaptureRules`) applies to both XHR and Fetch resources.
 
 GraphQL error extraction (via `DatadogLink({ trackErrors: true })`) for
 requests made through `expo/fetch` requires Expo SDK 56 or later, as older

packages/core/datadog-configuration.schema.json

@@ -192,6 +192,125 @@
                             "description": "The app hang threshold in seconds for non-fatal app hangs on iOS.",
                             "type": "number"
                         },
+                        "headerCaptureRules": {
+                            "description": "Controls which HTTP request and response headers are captured on RUM resource events. Omit to disable header capture (default). Use `\"defaults\"` to capture a predefined set of caching and content headers on all URLs, or an array of composable rules. Sensitive headers (cookies, authorization, tokens, ...) and SDK tracing headers are never captured. Only takes effect when resource tracking is enabled.",
+                            "oneOf": [
+                                {
+                                    "const": "defaults"
+                                },
+                                {
+                                    "type": "array",
+                                    "items": {
+                                        "oneOf": [
+                                            {
+                                                "description": "Captures the predefined set of caching and content headers from requests and responses.",
+                                                "type": "object",
+                                                "properties": {
+                                                    "type": {
+                                                        "const": "defaults"
+                                                    },
+                                                    "forURLs": {
+                                                        "description": "URL patterns to scope this rule to. Supports hostname-only (`api.example.com`) or hostname + path prefix (`api.example.com/v2`). Omit (or use `[\"*\"]`) to match all URLs.",
+                                                        "type": "array",
+                                                        "items": {
+                                                            "type": "string"
+                                                        }
+                                                    }
+                                                },
+                                                "required": [
+                                                    "type"
+                                                ],
+                                                "additionalProperties": false
+                                            },
+                                            {
+                                                "description": "Captures the given headers from both requests and responses.",
+                                                "type": "object",
+                                                "properties": {
+                                                    "type": {
+                                                        "const": "matchHeaders"
+                                                    },
+                                                    "headers": {
+                                                        "description": "Header names to capture. Compared case-insensitively; the casing provided here is used in the reported attributes.",
+                                                        "type": "array",
+                                                        "items": {
+                                                            "type": "string"
+                                                        }
+                                                    },
+                                                    "forURLs": {
+                                                        "description": "URL patterns to scope this rule to. Supports hostname-only (`api.example.com`) or hostname + path prefix (`api.example.com/v2`). Omit (or use `[\"*\"]`) to match all URLs.",
+                                                        "type": "array",
+                                                        "items": {
+                                                            "type": "string"
+                                                        }
+                                                    }
+                                                },
+                                                "required": [
+                                                    "type",
+                                                    "headers"
+                                                ],
+                                                "additionalProperties": false
+                                            },
+                                            {
+                                                "description": "Captures the given headers from requests only.",
+                                                "type": "object",
+                                                "properties": {
+                                                    "type": {
+                                                        "const": "matchRequestHeaders"
+                                                    },
+                                                    "headers": {
+                                                        "description": "Header names to capture. Compared case-insensitively; the casing provided here is used in the reported attributes.",
+                                                        "type": "array",
+                                                        "items": {
+                                                            "type": "string"
+                                                        }
+                                                    },
+                                                    "forURLs": {
+                                                        "description": "URL patterns to scope this rule to. Supports hostname-only (`api.example.com`) or hostname + path prefix (`api.example.com/v2`). Omit (or use `[\"*\"]`) to match all URLs.",
+                                                        "type": "array",
+                                                        "items": {
+                                                            "type": "string"
+                                                        }
+                                                    }
+                                                },
+                                                "required": [
+                                                    "type",
+                                                    "headers"
+                                                ],
+                                                "additionalProperties": false
+                                            },
+                                            {
+                                                "description": "Captures the given headers from responses only.",
+                                                "type": "object",
+                                                "properties": {
+                                                    "type": {
+                                                        "const": "matchResponseHeaders"
+                                                    },
+                                                    "headers": {
+                                                        "description": "Header names to capture. Compared case-insensitively; the casing provided here is used in the reported attributes.",
+                                                        "type": "array",
+                                                        "items": {
+                                                            "type": "string"
+                                                        }
+                                                    },
+                                                    "forURLs": {
+                                                        "description": "URL patterns to scope this rule to. Supports hostname-only (`api.example.com`) or hostname + path prefix (`api.example.com/v2`). Omit (or use `[\"*\"]`) to match all URLs.",
+                                                        "type": "array",
+                                                        "items": {
+                                                            "type": "string"
+                                                        }
+                                                    }
+                                                },
+                                                "required": [
+                                                    "type",
+                                                    "headers"
+                                                ],
+                                                "additionalProperties": false
+                                            }
+                                        ]
+                                    }
+                                }
+                            ]
+                        },
                         "initialResourceThreshold": {
                             "description": "The amount of time after a view starts where a Resource should be considered when calculating Time to Network-Settled (TNS).",
                             "type": "number"

packages/core/src/DdSdkReactNative.tsx

@@ -518,6 +518,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;
@@ -553,11 +555,19 @@ 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,
-                trackFetchResources
+                trackFetchResources,
+                headerCaptureRules
             });
         }
 

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

@@ -8,6 +8,7 @@ import { version as reactNativeVersion } from 'react-native/package.json';
 import { NativeModules } from 'react-native';
 
 import { DdSdkReactNative } from '../DdSdkReactNative';
+import { InternalLog } from '../InternalLog';
 import type { DdSdkNativeConfiguration } from '../config/features/CoreConfigurationNative';
 import { CoreConfiguration } from '../config/features/CoreConfiguration';
 import { LogsConfiguration } from '../config/features/LogsConfiguration';
@@ -813,10 +814,130 @@ describe('DdSdkReactNative', () => {
                         propagatorTypes: ['datadog']
                     }
                 ],
-                trackFetchResources: true
+                trackFetchResources: true,
+                headerCaptureRules: undefined
             });
         });
 
+        it('does not enable header capture when headerCaptureRules is omitted', async () => {
+            // GIVEN
+            const fakeAppId = '1';
+            const fakeClientToken = '2';
+            const fakeEnvName = 'env';
+            const configuration = new CoreConfiguration(
+                fakeClientToken,
+                fakeEnvName
+            );
+            configuration.rumConfiguration = new RumConfiguration(
+                fakeAppId,
+                false,
+                true
+            );
+
+            NativeModules.DdSdk.initialize.mockResolvedValue(null);
+
+            // WHEN
+            await DdSdkReactNative.initialize(configuration);
+
+            // THEN
+            expect(DdRumResourceTracking.startTracking).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    headerCaptureRules: undefined
+                })
+            );
+        });
+
+        it('enables header capture with the default headerCaptureRules preset', async () => {
+            // GIVEN
+            const fakeAppId = '1';
+            const fakeClientToken = '2';
+            const fakeEnvName = 'env';
+            const configuration = new CoreConfiguration(
+                fakeClientToken,
+                fakeEnvName
+            );
+            configuration.rumConfiguration = new RumConfiguration(
+                fakeAppId,
+                false,
+                true
+            );
+            configuration.rumConfiguration.headerCaptureRules = 'defaults';
+
+            NativeModules.DdSdk.initialize.mockResolvedValue(null);
+
+            // WHEN
+            await DdSdkReactNative.initialize(configuration);
+
+            // THEN
+            expect(DdRumResourceTracking.startTracking).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    headerCaptureRules: 'defaults'
+                })
+            );
+        });
+
+        it('enables header capture with custom headerCaptureRules', async () => {
+            // GIVEN
+            const fakeAppId = '1';
+            const fakeClientToken = '2';
+            const fakeEnvName = 'env';
+            const configuration = new CoreConfiguration(
+                fakeClientToken,
+                fakeEnvName
+            );
+            configuration.rumConfiguration = new RumConfiguration(
+                fakeAppId,
+                false,
+                true
+            );
+            configuration.rumConfiguration.headerCaptureRules = [
+                { type: 'matchHeaders', headers: ['x-request-id'] }
+            ];
+
+            NativeModules.DdSdk.initialize.mockResolvedValue(null);
+
+            // WHEN
+            await DdSdkReactNative.initialize(configuration);
+
+            // THEN
+            expect(DdRumResourceTracking.startTracking).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    headerCaptureRules: [
+                        { type: 'matchHeaders', headers: ['x-request-id'] }
+                    ]
+                })
+            );
+        });
+
+        it('logs a warning and disables header capture when headerCaptureRules is set but trackResources is false', async () => {
+            // GIVEN
+            const fakeAppId = '1';
+            const fakeClientToken = '2';
+            const fakeEnvName = 'env';
+            const configuration = new CoreConfiguration(
+                fakeClientToken,
+                fakeEnvName
+            );
+            configuration.rumConfiguration = new RumConfiguration(
+                fakeAppId,
+                false,
+                false
+            );
+            configuration.rumConfiguration.headerCaptureRules = 'defaults';
+
+            NativeModules.DdSdk.initialize.mockResolvedValue(null);
+
+            // WHEN
+            await DdSdkReactNative.initialize(configuration);
+
+            // THEN
+            expect(DdRumResourceTracking.startTracking).not.toHaveBeenCalled();
+            expect(InternalLog.log).toHaveBeenCalledWith(
+                'headerCaptureRules is set but trackResources is false. Header capture will be disabled.',
+                SdkVerbosity.WARN
+            );
+        });
+
         it('enables error tracking feature when initialize { error tracking config enabled }', async () => {
             // GIVEN
             const fakeAppId = '1';

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,
@@ -212,6 +213,7 @@ describe('DdSdkReactNativeConfiguration', () => {
                         ],
                       },
                     ],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": 0.123,
                     "longTaskThresholdMs": 567,
                     "nativeCrashReportEnabled": true,
@@ -320,6 +322,7 @@ describe('DdSdkReactNativeConfiguration', () => {
                     "customEndpoint": undefined,
                     "errorEventMapper": null,
                     "firstPartyHosts": [],
+                    "headerCaptureRules": undefined,
                     "initialResourceThreshold": 0,
                     "longTaskThresholdMs": false,
                     "nativeCrashReportEnabled": false,

packages/core/src/config/FileBasedConfiguration.ts

@@ -165,6 +165,9 @@ export const getJSONConfiguration = (
                     buildFirstPartyHosts(
                         configuration.rumConfiguration.firstPartyHosts
                     ) || RUM_DEFAULTS.getFirstPartyHosts(),
+                // Validated when compiled at resource tracking start
+                headerCaptureRules:
+                    configuration.rumConfiguration.headerCaptureRules,
                 useAccessibilityLabel:
                     configuration.rumConfiguration.useAccessibilityLabel,
                 trackInteractions:

packages/core/src/config/FileBasedConfiguration.type.ts

@@ -6,6 +6,7 @@
 import type { FirstPartyHost } from '../rum/types';
 
 import type { CoreConfigurationOptions } from './features/CoreConfiguration.type';
+import type { HeaderCaptureRule } from './features/RumConfiguration.type';
 import type {
     BatchProcessingLevel,
     BatchSize,
@@ -40,6 +41,7 @@ export interface JsonConfiguration extends CoreConfigurationOptions {
         actionNameAttribute?: string;
         appHangThreshold?: number;
         firstPartyHosts?: FirstPartyHost[];
+        headerCaptureRules?: 'defaults' | HeaderCaptureRule[];
         initialResourceThreshold?: number;
         trackMemoryWarnings?: boolean;
         nativeCrashReportEnabled?: boolean;