docs(rum): document debug ID source map uploads

hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md

@@ -1,6 +1,6 @@
 ---
 title: Source Code Context
-description: "Display source code inline in Error Tracking stack traces by injecting service and version metadata at build time."
+description: "Display source code inline in Error Tracking stack traces by injecting debug ID or service and version metadata at build time."
 algolia:
   tags: ['source code context', 'build plugins', 'error tracking', 'stack traces']
 further_reading:
@@ -20,45 +20,57 @@ further_reading:
 
 ## Overview
 
-When viewing errors in [Error Tracking][1], Datadog can display the source code lines surrounding each frame in the stack trace. The Source Code Context build plugin enables this feature by injecting a small runtime snippet into your bundle that associates stack traces with your `service` and `version` metadata.
+When viewing errors in [Error Tracking][1], Datadog can display the source code lines surrounding each frame in the stack trace. The Source Code Context build plugin enables this feature by injecting a small runtime snippet into your bundle. This snippet associates stack traces with a debug ID or with `service` and `version` metadata.
 
-At build time, the plugin injects a snippet that writes metadata to `window.DD_SOURCE_CODE_CONTEXT`. At runtime, the RUM SDK reads `window.DD_SOURCE_CODE_CONTEXT` to tag errors with the correct service and version for source code resolution. This works in conjunction with [uploaded source maps][2] — source maps provide the file mapping, and `window.DD_SOURCE_CODE_CONTEXT` provides the service and version association.
+At build time, the plugin injects a snippet that writes metadata to `window.DD_SOURCE_CODE_CONTEXT`. At runtime, the RUM SDK reads this metadata to associate stack frames with [uploaded source maps][2].
 
 ## Prerequisites
 
 - Source maps uploaded to Datadog, either through the [Source Maps build plugin][3] or [manually][2].
-- The RUM SDK initialized with matching `service` and `version` parameters.
+- For service and version matching, initialize the RUM SDK with matching `service` and `version` parameters.
 - The Datadog build plugin installed and registered with your bundler. See [Build Plugins][4] for installation instructions.
 
 ## Configuration
 
-Configure the `rum.sourceCodeContext` object in your build plugin options:
+Choose one of the following source code context methods. The two configurations are mutually exclusive.
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `rum.sourceCodeContext.service` | String | Yes | None | Service name. Must match the RUM SDK `service` initialization parameter. |
-| `rum.sourceCodeContext.version` | String | No | None | Release version. If omitted, source code context is not associated with a specific version. If set, must match the RUM SDK `version` initialization parameter. |
+{{< tabs >}}
+{{% tab "Debug ID (Recommended)" %}}
 
-## Example
+Debug IDs associate each JavaScript bundle with its source map without relying on the bundle URL, service, or version. Use this method for new configurations.
 
-The following example shows source code context combined with source maps, a common pairing:
+Set `debugId` to `true` in `sourcemaps` to inject a debug ID into each JavaScript bundle.
 
 ```javascript
 const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');
 
 module.exports = {
   plugins: [
     datadogWebpackPlugin({
-      auth: {
-        apiKey: process.env.DATADOG_API_KEY,
-      },
-      errorTracking: {
-        sourcemaps: {
-          service: 'my-application',
-          releaseVersion: '1.0.0',
-          minifiedPathPrefix: 'https://example.com/static/',
-        },
+      sourcemaps: {
+        debugId: true,
       },
+    }),
+  ],
+};
+```
+
+{{% /tab %}}
+{{% tab "Service and version" %}}
+
+Service and version matching associates stack frames with source maps using metadata from the RUM SDK and the uploaded source maps.
+
+Configure the following options in `rum.sourceCodeContext`:
+
+- `service` (String, required): The service name. It must match the RUM SDK `service` initialization parameter.
+- `version` (String, optional): The release version. If set, it must match the RUM SDK `version` initialization parameter. If omitted, source code context is not associated with a specific version.
+
+```javascript
+const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');
+
+module.exports = {
+  plugins: [
+    datadogWebpackPlugin({
       rum: {
         sourceCodeContext: {
           service: 'my-application',
@@ -70,6 +82,11 @@ module.exports = {
 };
 ```
 
+The `service` and `version` values must match the metadata used when uploading the source maps.
+
+{{% /tab %}}
+{{< /tabs >}}
+
 <div class="alert alert-info">This example uses webpack. The configuration object is identical across all supported bundlers. See <a href="/real_user_monitoring/application_monitoring/browser/build_plugins/">Build Plugins</a> for installation instructions for your bundler.</div>
 
 ## Further reading

hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md

@@ -19,33 +19,74 @@ further_reading:
 
 The Source Maps build plugin automatically uploads JavaScript source maps to Datadog during your build, enabling deobfuscated stack traces in [Error Tracking][1] and [RUM][2]. This replaces the need to manually run `datadog-ci sourcemaps upload` or configure CI/CD pipelines for source map uploads.
 
-The plugin hooks into the build process, discovers all `.js` files with corresponding `.map` source map files from the build output, and uploads them to Datadog with git metadata.
+The plugin hooks into the build process, discovers all `.js` files with corresponding `.map` source map files from the build output, and uploads them to Datadog with git metadata. It can associate source maps with events by debug ID or by service and version.
 
 ## Prerequisites
 
 - A Datadog API key, set with `auth.apiKey` or the `DATADOG_API_KEY` environment variable.
 - Source maps enabled in your bundler configuration. The plugin uploads source maps but does not generate them. See [Upload JavaScript Source Maps][3] for bundler-specific source map generation setup.
-- The RUM SDK initialized with `service` and `version` parameters that match the plugin's `service` and `releaseVersion` configuration.
+- For debug ID uploads, enable debug ID injection in the build plugin.
+- For service and version uploads, initialize the RUM SDK with `service` and `version` parameters that match the plugin configuration.
 - The Datadog build plugin installed and registered with your bundler. See [Build Plugins][4] for installation instructions.
 
 ## Configuration
 
-Configure the `errorTracking.sourcemaps` object in your build plugin options:
+The following environment variables override configuration values:
+
+- `DATADOG_SITE` or `DD_SITE`: Overrides `auth.site` for the intake URL.
+- `DATADOG_SOURCEMAP_INTAKE_URL`: Overrides the full intake URL directly.
+
+Choose either debug ID uploads or service and version uploads. Do not configure both upload methods in the same build.
+
+{{< tabs >}}
+{{% tab "Debug ID (Recommended)" %}}
+
+Debug IDs associate each JavaScript bundle with its source map without relying on the bundle URL, service, or version. Use this method for new configurations.
+
+Configure the following options in `sourcemaps`:
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| `errorTracking.sourcemaps.service` | String | Yes | None | Service name. Must match the RUM SDK `service` initialization parameter. |
-| `errorTracking.sourcemaps.releaseVersion` | String | Yes | None | Release version. Must match the RUM SDK `version` initialization parameter. |
-| `errorTracking.sourcemaps.minifiedPathPrefix` | String | Yes | None | URL or root-relative path prefix for your minified JavaScript files are served. For example, `https://example.com/static/` or `/static/`. |
-| `errorTracking.sourcemaps.bailOnError` | Boolean | No | `false` | If `true`, the build fails when a source map upload error occurs. |
-| `errorTracking.sourcemaps.dryRun` | Boolean | No | `false` | If `true`, the plugin runs through the upload process without sending data to Datadog. Use this to verify your configuration. |
-| `errorTracking.sourcemaps.maxConcurrency` | Number | No | `20` | Maximum number of concurrent source map uploads. |
+| `debugId` | Boolean | Yes | None | Set to `true` to inject a debug ID into each JavaScript bundle. |
+| `upload` | Boolean | Yes, to upload | `false` | Set to `true` to upload source maps during the build. If omitted, the plugin only injects debug IDs. |
+| `bailOnError` | Boolean | No | `false` | If `true`, the build fails when a source map upload error occurs. |
+| `dryRun` | Boolean | No | `false` | If `true`, the plugin runs through the upload process without sending data to Datadog. Use this to verify your configuration. |
+| `maxConcurrency` | Number | No | `20` | Maximum number of concurrent source map uploads. |
 
-The following environment variables override configuration values:
-- `DATADOG_SITE` or `DD_SITE`: Overrides `auth.site` for the intake URL.
-- `DATADOG_SOURCEMAP_INTAKE_URL`: Overrides the full intake URL directly.
+Set `debugId` and `upload` to `true` to inject debug IDs and upload source maps during the build:
+
+```javascript
+const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');
+
+module.exports = {
+  plugins: [
+    datadogWebpackPlugin({
+      auth: {
+        apiKey: process.env.DATADOG_API_KEY,
+        site: 'datadoghq.com', // Optional: defaults to datadoghq.com
+      },
+      sourcemaps: {
+        debugId: true,
+        upload: true,
+      },
+    }),
+  ],
+};
+```
+
+{{% /tab %}}
+{{% tab "Service and version" %}}
 
-## Example
+Configure the `errorTracking.sourcemaps` object to upload source maps using service and version matching:
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `service` | String | Yes | None | Service name. Must match the RUM SDK `service` initialization parameter. |
+| `releaseVersion` | String | Yes, unless `metadata.version` is set | None | Release version. Must match the RUM SDK `version` initialization parameter. |
+| `minifiedPathPrefix` | String | Yes | None | URL or root-relative path prefix where your minified JavaScript files are served. For example, `https://example.com/static/` or `/static/`. |
+| `bailOnError` | Boolean | No | `false` | If `true`, the build fails when a source map upload error occurs. |
+| `dryRun` | Boolean | No | `false` | If `true`, the plugin runs through the upload process without sending data to Datadog. Use this to verify your configuration. |
+| `maxConcurrency` | Number | No | `20` | Maximum number of concurrent source map uploads. |
 
 ```javascript
 const { datadogWebpackPlugin } = require('@datadog/webpack-plugin');
@@ -69,9 +110,12 @@ module.exports = {
 };
 ```
 
-<div class="alert alert-info">This example uses webpack. The configuration object is identical across all supported bundlers — only the import and plugin function name differ. See <a href="/real_user_monitoring/application_monitoring/browser/build_plugins/">Build Plugins</a> for installation instructions for your bundler.</div>
+To also display inline source code in Error Tracking stack traces, pair service and version source map uploads with the [Source Code Context][5] plugin.
+
+{{% /tab %}}
+{{< /tabs >}}
 
-To also display inline source code in Error Tracking stack traces, pair source map uploads with the [Source Code Context][5] plugin. Source maps provide the file mapping; source code context provides the service and version association.
+<div class="alert alert-info">These examples use webpack. The configuration object is identical across all supported bundlers — only the import and plugin function name differ. See <a href="/real_user_monitoring/application_monitoring/browser/build_plugins/">Build Plugins</a> for installation instructions for your bundler.</div>
 
 ## Further reading
 

hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md

@@ -118,6 +118,64 @@ If the sum of the file size for <code>javascript.364758.min.js</code> and <code>
 
 The best way to upload source maps is to add an extra step in your CI pipeline and run the dedicated command from the [Datadog CLI][1]. It scans the `dist` directory and subdirectories to automatically upload source maps with relevant minified files.
 
+{{< tabs >}}
+{{% tab "Debug ID (Recommended)" %}}
+
+Debug IDs associate a JavaScript bundle with its source map without relying on the bundle URL, service, or release version.
+
+Choose one of the following upload methods.
+
+#### Datadog Build Plugins
+
+Datadog Build Plugins can inject debug IDs and upload source maps directly during the build. You do not need to install or run `datadog-ci` separately.
+
+Enable debug ID injection and source map uploads in your build plugin:
+
+```javascript
+datadogWebpackPlugin({
+  auth: {
+    apiKey: process.env.DATADOG_API_KEY,
+    site: 'datadoghq.com',
+  },
+  sourcemaps: {
+    debugId: true,
+    upload: true,
+  },
+});
+```
+
+The plugin uploads each source map with the debug ID injected into its corresponding JavaScript bundle.
+
+This example uses webpack. See [Datadog Build Plugins][8] for installation and configuration instructions for other supported bundlers.
+
+#### `datadog-ci`
+
+1. Add `@datadog/datadog-ci` to your `package.json` file (make sure you're using the latest version).
+2. [Create a dedicated Datadog API key][6] and export it as an environment variable named `DD_API_KEY`.
+3. For sites other than US1, configure the CLI by exporting `DD_SITE` with your [Datadog site][7].
+4. Inject debug IDs after the build:
+
+   ```bash
+   datadog-ci sourcemaps inject /path/to/dist
+   ```
+
+5. Upload the source maps and corresponding JavaScript bundles:
+
+   ```bash
+   datadog-ci sourcemaps upload /path/to/dist --debug-id
+   ```
+
+Do not pass `--service`, `--release-version`, or `--minified-path-prefix` with `--debug-id`.
+
+The `inject` command modifies JavaScript bundles and source maps in place. Run it after the build and before generating byte-dependent artifacts such as SRI hashes, compressed assets, signatures, or checksum manifests. Deploy the same modified artifacts that you upload.
+
+[6]: https://app.datadoghq.com/organization-settings/api-keys
+[7]: /getting_started/site/
+[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/source_maps/
+
+{{% /tab %}}
+{{% tab "Service and version" %}}
+
 {{< site-region region="us" >}}
 1. Add `@datadog/datadog-ci` to your `package.json` file (make sure you're using the latest version).
 2. [Create a dedicated Datadog API key][1] and export it as an environment variable named `DD_API_KEY`.
@@ -164,6 +222,12 @@ Only source maps with the `.js.map` extension work to correctly unminify stack t
 
 <div class="alert alert-info">If you are serving the same JavaScript source files from different subdomains, upload the related source map once and make it work for multiple subdomains by using the absolute prefix path instead of the full URL. For example, specify <code>/static/js</code> instead of <code>https://hostname.com/static/js</code>.</div>
 
+[2]: /real_user_monitoring/application_monitoring/browser/setup/#initialization-parameters
+[3]: /logs/log_collection/javascript/#initialization-parameters
+
+{{% /tab %}}
+{{< /tabs >}}
+
 See all uploaded symbols and manage your source maps on the [{{< ui >}}Explore RUM Debug Symbols{{< /ui >}}][5] page.
 
 ### Link stack frames to your source code
@@ -172,6 +236,24 @@ If you run `datadog-ci sourcemaps upload` within a Git working directory, Datado
 
 Datadog displays links to your source code on unminified stack frames.
 
+## Troubleshooting debug ID uploads
+
+### Inspect local source maps
+
+To find the local source map for a specific debug ID, run:
+
+```bash
+datadog-ci sourcemaps find /path/to/dist --debug-id 12345678-1234-1234-1234-123456789abc
+```
+
+To find source maps that do not contain a debug ID, run:
+
+```bash
+datadog-ci sourcemaps find /path/to/dist --missing-debug-id
+```
+
+The `find` command only inspects local `*.js.map` files. It does not confirm whether Datadog received an artifact.
+
 ## Troubleshoot errors with ease
 
 Without access to the file path and the line number, a minified stack trace is not helpful in troubleshooting your code base. Also, the code snippet is minified (which means there is one long line of transformed code), making the troubleshooting process more difficult.
@@ -189,7 +271,5 @@ On the other hand, an unminified stack trace provides you with all the context y
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://github.com/DataDog/datadog-ci/tree/master/packages/base/src/commands/sourcemaps
-[2]: https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/setup/#initialization-parameters
-[3]: https://docs.datadoghq.com/logs/log_collection/javascript/#initialization-parameters
 [4]: https://github.com/DataDog/datadog-ci/tree/master/packages/base/src/commands/sourcemaps#link-errors-with-your-source-code
 [5]: https://app.datadoghq.com/source-code/setup/rum