[RUM-18236] Improve api for upload of source maps by debug ID by jhssilva · Pull Request #502 · DataDog/build-plugins

jhssilva · 2026-09-03T06:07:12Z

What and why?

Add direct debug-ID source-map uploads to Datadog Build Plugins. A build can now inject debug IDs and upload the corresponding source maps without configuring a service, release version, or minified path prefix.

The existing nested debug-ID and service/version workflows remain backward compatible.

Documentation: docs(rum): document debug ID source map uploads documentation#39656

How to use it

For Build Plugins to inject debug IDs and upload the source maps:

datadogWebpackPlugin({
  auth: {
    apiKey: process.env.DATADOG_API_KEY,
    site: 'datadoghq.com',
  },
  sourcemaps: {
    debugId: true,
    upload: true,
  },
});

sourcemaps.debugId: true injects a debug ID into each generated JavaScript bundle.
sourcemaps.upload: true uploads the corresponding source maps during the build.
Omitting upload enables injection without direct upload, for example when datadog-ci performs the upload.
auth.apiKey or DATADOG_API_KEY is required only when direct upload is enabled.
bailOnError, dryRun, and maxConcurrency can be configured alongside upload: true.

The existing rum.sourceCodeContext and errorTracking.sourcemaps configurations remain supported. They cannot be combined with the new top-level sourcemaps option.

Existing service/version workflow

The legacy configuration continues to work unchanged:

datadogWebpackPlugin({
  auth: {
    apiKey: process.env.DATADOG_API_KEY,
    site: 'datadoghq.com',
  },
  errorTracking: {
    sourcemaps: {
      service: 'my-application',
      releaseVersion: '1.0.0',
      minifiedPathPrefix: 'https://example.com/static/',
    },
  },
  rum: {
    sourceCodeContext: {
      service: 'my-application',
      version: '1.0.0',
    },
  },
});

Implementation

Add debug-ID upload support for webpack, Vite, Rollup, esbuild, and Rspack.
Add a typed top-level sourcemaps option that distinguishes injection-only and upload-enabled configurations.
Normalize the top-level option to the existing RUM injection and Error Tracking upload implementations.
Represent upload behavior internally with the typed SourcemapsUploadMode discriminator.
Build debug-ID multipart payloads without legacy service/version/path metadata.
Require a debug ID for every artifact uploaded in debug-ID mode.
Preserve the existing nested debug-ID and service/version behavior.

Validation

77 focused unit and integration tests pass across the factory, RUM, and Error Tracking paths.
Package typechecking, formatting, generated documentation/link checks, repository integrity, and open-source compliance pass locally.
A real webpack smoke test using sourcemaps: { debugId: true, upload: true } uploaded a source map to the staging intake with bailOnError: true.

amortemousque · 2026-09-04T08:31:36Z

💬 suggestion: ‏Nice! Only comment about the public API. I’m not sure repeating debugId is ideal, consider a customer using both plugins:

datadogWebpackPlugin({
  auth: { apiKey: process.env.DATADOG_API_KEY, site: 'datadoghq.com' },
  errorTracking: {
    sourcemaps: {
      debugId: true
    },
  },
  rum: {
    sourceCodeContext: {
      debugId: true
    },
  },
});

Could we instead expose something like this?

{
  auth: { apiKey: process.env.DATADOG_API_KEY, site: 'datadoghq.com' },
  sourcemaps: {
   debugId: true,
   upload: true
 }
}

buranmert

i like the idea but i'm wondering how can we make sure RUM and Error Tracking plugins are used together?
(i'm not familiar with how to use build plugins, i assume the user picks whichever plugins they want to use)

amortemousque · 2026-09-07T10:25:44Z

+export type ServiceVersionSourcemapsOptionsWithDefaults = SourcemapsUploadOptionsWithDefaults &
+    Required<
+        Pick<ServiceVersionSourcemapsOptions, 'minifiedPathPrefix' | 'releaseVersion' | 'service'>
+    > & {
+        mode: SourcemapsUploadMode.SERVICE_VERSION;
+    };
+
+export type DebugIdSourcemapsOptionsWithDefaults = SourcemapsUploadOptionsWithDefaults & {
+    mode: SourcemapsUploadMode.DEBUG_ID;
+};


💬 suggestion: ‏Why do we need a new type here? Instead of introducing a mode field, could we use debugId as the discriminant?

12:25 PM

Great suggestion.

Done in 4cbb00d. I removed SourcemapsUploadMode and now use debugId as the discriminant in the normalized types and throughout file selection, payload creation, and upload metrics.

amortemousque · 2026-09-07T10:34:55Z

    return errors;
 };

+const normalizeSourcemapsOptions = (options: Options, errors: string[]): Options => {


💬 suggestion: ‏This function re-implements validation that rum/validate.ts and error-tracking/validate.ts already do (apiKey required, service/version conflicts, enable-flag conflicts), same rules, second place to keep in sync. Could we avoid repeating them

The normalizer is still needed to translate the new top-level sourcemaps option into the existing RUM and Error Tracking plugin configurations. It only validates the top-level shape and cross-plugin contradictions; API-key and service/version/path validation remain in the plugin validators. The explicit enable:false checks must happen here because disabled plugins do not run their validators. Let me know if you would prefer this split to be made more explicit in naming or structure.

amortemousque · 2026-09-07T10:41:52Z

+    // resolves; otherwise an error has been recorded and the caller will
+    // throw before the config is read.
+    if (releaseVersion) {
+        const { debugId: _debugId, ...serviceVersionOptions } = sourcemapsCfg;


❓ question: ‏Couldn't we directly pass sourcemapsCfg instead of adding this spread?

Yes, done in 4cbb00d. The service/version branch now spreads sourcemapsCfg directly, then sets the normalized debugId:false value and resolved releaseVersion.

amortemousque · 2026-09-07T10:42:06Z

-        // throw before the config is read.
-        if (releaseVersion) {
+        if (toReturn.errors.length === 0) {
+            const { debugId: _debugId, ...uploadOptions } = sourcemapsCfg;


❓ question: ‏Couldn't we directly pass sourcemapsCfg instead of adding this spread?

Yes, done in 4cbb00d. The debug-ID branch now spreads sourcemapsCfg directly, preserving debugId:true.

amortemousque · 2026-09-07T10:54:22Z

+type DebugIdSourceCodeContextOptions = {
+    debugId: true;
+    service?: never;
+    version?: never;
+};
+
+type ServiceVersionSourceCodeContextOptions = {
+    debugId?: false;
+    service: string;
    version?: string;
-    debugId?: boolean;
 };


🔨 warning: This assumption is incorrect. A customer can provide source code context with both a debugId and service/version. The service and version identify and allow to filter events from a specific micro-frontend; they are independent of the unminification.

Fixed in 4cbb00d. The debug-ID source-code-context variant now accepts optional service and version, validation preserves them, and the injected context serializes service, version, and ddDebugId together. The legacy service/version variant remains unchanged.

jhssilva · 2026-09-07T16:01:27Z

i like the idea but i'm wondering how can we make sure RUM and Error Tracking plugins are used together? (i'm not familiar with how to use build plugins, i assume the user picks whichever plugins they want to use)

@buranmert @Aymeric replied:

All Datadog plugins are bundled into the same @datadog/webpack-plugin package, so Error Tracking uploads and RUM Debug ID injection can use the same sourcemaps configuration.

amortemousque · 2026-09-08T08:13:40Z

-
+    // Compute deterministic debug IDs whenever possible to prevent the backend from storing
+    // duplicate source maps for identical builds.
+    const debugId =


🥜 nitpick: Nested ternaries are difficult to read. Could we revert to the original code if the behavior is unchanged?

Agreed, the behavior is unchanged. I've reverted this to the original variable declaration and if-statement form to avoid the nested ternary. Thanks!

amortemousque · 2026-09-08T08:19:58Z

        errors.push(`Sourcemap file not found: ${sourcemap.sourcemapFilePath}`);
    }
+    if (debugIdRequired && !debugId) {
+        errors.push(`No debug ID found in minified file: ${sourcemap.minifiedFilePath}`);


💬 suggestion: ‏I don’t think we should abort all uploads when a single file is missing a debug ID. To remain consistent with datadog-ci upload: if all debug IDs are missing, fail with exit code 1; if only some are missing, skip those files and upload the rest.

Addressed 035b29f

amortemousque · 2026-09-09T12:03:59Z

Not fully fan with the validation flow in this file, but it could be improve in followup PRs

jhssilva · 2026-09-09T12:26:29Z

/code blockers

gh-worker-devflow-routing-ef8351 · 2026-09-09T12:26:33Z

View all feedbacks in Devflow UI.

2026-09-09 12:26:32 UTC ℹ️ Start processing command /code blockers

2026-09-09 12:26:33 UTC ℹ️ Devflow:

Checking merge blockers for #502...

2026-09-09 12:26:36 UTC ℹ️ Devflow: /code blockers

Detected 1 merge blocker(s) to address:

🟠 Pending

Merge gate rule reviewers-approval is running: 1 approval missing
All required reviewers must approve this pull request before it can be merged. Learn more in our FAQ.
- Needs approval from Team: build-plugins
Hint: Questions about this check? Reach out in #dx-source-code-management on Slack.

nchapma2

Approving for build-plugins. I don't really know this code at all and in the plugin files, it seems like we could do some cleaning up if debug-ids are the identifier going forward

jhssilva · 2026-09-10T16:41:10Z

/merge

gh-worker-devflow-routing-ef8351 · 2026-09-10T16:41:15Z

View all feedbacks in Devflow UI.

2026-09-10 16:41:15 UTC ℹ️ Start processing command /merge

2026-09-10 16:41:20 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2m (p90).

2026-09-10 16:42:43 UTC ℹ️ MergeQueue: This merge request was merged

jhssilva added 2 commits September 2, 2026 18:40

feat(rum): upload source maps by debug ID

2a10b2d

refactor(rum): configure debug ID uploads in sourcemaps

dadabfa

jhssilva marked this pull request as ready for review September 3, 2026 13:49

jhssilva requested review from a team as code owners September 3, 2026 13:49

jhssilva requested review from amortemousque and sdkennedy2 and removed request for a team September 3, 2026 13:49

jhssilva added 2 commits September 4, 2026 13:56

feat: simplify debug ID sourcemap configuration

66a1f0d

docs(rum): link source map upload options

773f112

jhssilva changed the title ~~[RUM-18236] Upload source maps by debug ID~~ [RUM-18236] Improve api for upload of source maps by debug ID Sep 7, 2026

buranmert reviewed Sep 7, 2026

View reviewed changes

amortemousque reviewed Sep 7, 2026

View reviewed changes

fix(rum): preserve metadata with debug IDs

4cbb00d

jhssilva requested review from amortemousque and buranmert September 8, 2026 07:21

amortemousque reviewed Sep 8, 2026

View reviewed changes

jhssilva added 2 commits September 8, 2026 10:59

refactor(rum): simplify debug ID assignment

c655c0c

fix(error-tracking): skip sourcemaps without debug IDs

035b29f

jhssilva requested a review from amortemousque September 8, 2026 14:40

amortemousque approved these changes Sep 9, 2026

View reviewed changes

amortemousque reviewed Sep 9, 2026

View reviewed changes

amortemousque approved these changes Sep 9, 2026

View reviewed changes

gh-worker-dd-devflow-36fce6 Bot added the mergequeue-status: waiting label Sep 9, 2026

gh-worker-dd-devflow-36fce6 Bot removed the mergequeue-status: waiting label Sep 9, 2026

gh-worker-dd-devflow-36fce6 Bot added the mergequeue-status: removed label Sep 9, 2026

nchapma2 self-requested a review September 10, 2026 16:25

nchapma2 approved these changes Sep 10, 2026

View reviewed changes

gh-worker-dd-devflow-36fce6 Bot added mergequeue-status: queued mergequeue-status: in_progress and removed mergequeue-status: removed mergequeue-status: queued labels Sep 10, 2026

gh-worker-dd-mergequeue-cf854d Bot merged commit 43beae0 into master Sep 10, 2026
7 checks passed

gh-worker-dd-mergequeue-cf854d Bot deleted the hugo.silva/rum-18236-debug-id-upload branch September 10, 2026 16:42

gh-worker-dd-devflow-36fce6 Bot added mergequeue-status: done and removed mergequeue-status: in_progress labels Sep 10, 2026

Uh oh!

Conversation

jhssilva commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What and why?

How to use it

Existing service/version workflow

Implementation

Validation

Uh oh!

amortemousque commented Sep 4, 2026

Uh oh!

buranmert left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhssilva commented Sep 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhssilva commented Sep 9, 2026

Uh oh!

gh-worker-devflow-routing-ef8351 Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟠 Pending

Uh oh!

nchapma2 left a comment

Choose a reason for hiding this comment

Uh oh!

jhssilva commented Sep 10, 2026

Uh oh!

gh-worker-devflow-routing-ef8351 Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jhssilva commented Sep 3, 2026 •

edited

Loading

gh-worker-devflow-routing-ef8351 Bot commented Sep 9, 2026 •

edited

Loading

gh-worker-devflow-routing-ef8351 Bot commented Sep 10, 2026 •

edited

Loading