✨ Support { includeDefaults: true } in trackResourceHeaders

Allow including the default tracked resource headers within a custom
trackResourceHeaders array via a `{ includeDefaults: true }` entry,
removing the need to spread DEFAULT_TRACKED_RESOURCE_HEADERS manually.

Deprecate the DEFAULT_TRACKED_RESOURCE_HEADERS field on the DD_RUM public
API in favor of the new sentinel (kept to avoid a breaking change).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: bdibon

packages/browser-rum-core/src/boot/rumPublicApi.ts

@@ -586,7 +586,9 @@ export interface RumPublicApi extends PublicApi {
   failFeatureOperation: (name: string, failureReason: FailureReason, options?: FeatureOperationOptions) => void
 
   /**
-   * List of default headers used by the {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders} option. See configuration example for extending them.
+   * List of default headers used by the {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders} option.
+   *
+   * @deprecated Use `{ includeDefaults: true }` as an entry in the `trackResourceHeaders` array instead.
    */
   DEFAULT_TRACKED_RESOURCE_HEADERS: typeof DEFAULT_TRACKED_RESOURCE_HEADERS
 }

packages/browser-rum-core/src/domain/configuration/configuration.spec.ts

@@ -434,6 +434,24 @@ describe('validateAndBuildRumConfiguration', () => {
         expect(result).toEqual(DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name })))
       })
 
+      it('expands { includeDefaults: true } to the default headers', () => {
+        const result = validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          trackResourceHeaders: [{ includeDefaults: true }],
+        })!.trackResourceHeaders
+
+        expect(result).toEqual(DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name })))
+      })
+
+      it('combines { includeDefaults: true } with custom matchers in array order', () => {
+        const result = validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          trackResourceHeaders: [{ includeDefaults: true }, { name: 'x-custom' }],
+        })!.trackResourceHeaders
+
+        expect(result).toEqual([...DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name })), { name: 'x-custom' }])
+      })
+
       it('accepts a MatchHeader with only name', () => {
         const result = validateAndBuildRumConfiguration({
           ...DEFAULT_INIT_CONFIGURATION,

packages/browser-rum-core/src/domain/configuration/configuration.ts

@@ -284,6 +284,8 @@ export interface RumInitConfiguration extends InitConfiguration {
    * (`url`), value extraction (`extractor`), and `location`. By default, both request and
    * response headers are captured; set `location` to `'request'` or `'response'` to restrict
    * to one.
+   * - `{ includeDefaults: true }` (as an array entry): expands to {@link DEFAULT_TRACKED_RESOURCE_HEADERS}
+   * in place, so the defaults can be combined with custom matchers without listing them manually.
    *
    * Headers whose names match a built-in sensitive-data pattern are always dropped, regardless
    * of the configured matchers. The pattern blocks headers whose names contain: `token`, `cookie`,
@@ -294,18 +296,15 @@ export interface RumInitConfiguration extends InitConfiguration {
    * @defaultValue false (disabled)
    * @example
    * // Collect default headers plus custom ones for all URLs
-   * trackResourceHeaders: [
-   *   ...DEFAULT_TRACKED_RESOURCE_HEADERS.map((h) => ({ name: h })),
-   *   { name: 'x-request-id' },
-   * ]
+   * trackResourceHeaders: [{ includeDefaults: true }, { name: 'x-request-id' }]
    * @example
    * // URL-scoped rule: capture specific response headers only for calls to /api
    * trackResourceHeaders: [{ url: /\/api\//, name: 'cache-control', location: 'response' }]
    * @example
    * // Extract a partial value from a header
    * trackResourceHeaders: [{ url: /\/api\//, name: 'server-timing', extractor: /dur=(\d+)/, location: 'response' }]
    */
-  trackResourceHeaders?: boolean | MatchHeader[] | undefined
+  trackResourceHeaders?: boolean | Array<MatchHeader | { includeDefaults: true }> | undefined
 
   /**
    * Enables collection of long task events.
@@ -576,6 +575,10 @@ function validateAndBuildGraphQlOptions(initConfiguration: RumInitConfiguration)
 
 const VALID_HEADER_LOCATIONS = ['request', 'response', 'any']
 
+function shouldIncludeDefaultHeaders(item: MatchHeader | { includeDefaults: true }) {
+  return isIndexableObject(item) && item.includeDefaults === true
+}
+
 function validateAndBuildTrackResourceHeaders(initConfiguration: RumInitConfiguration): MatchHeader[] {
   const option = initConfiguration.trackResourceHeaders
 
@@ -600,6 +603,10 @@ function validateAndBuildTrackResourceHeaders(initConfiguration: RumInitConfigur
   const result: MatchHeader[] = []
 
   option.forEach((item, index) => {
+    if (shouldIncludeDefaultHeaders(item)) {
+      DEFAULT_TRACKED_RESOURCE_HEADERS.forEach((name) => result.push({ name }))
+      return
+    }
     if (!isIndexableObject(item) || !isMatchOption(item.name)) {
       display.warn(`trackResourceHeaders[${index}] should be a MatchHeader object with a 'name' property`)
       return