From a84b92c494309003cbe5da2936ab04fe14fd3aa5 Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Wed, 2 Sep 2026 14:19:03 +0200 Subject: [PATCH 01/10] docs(rum): document debug ID source map uploads --- .../guide/upload-javascript-source-maps.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index ee4c7195962..93989431934 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -118,6 +118,9 @@ If the sum of the file size for javascript.364758.min.js and 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 "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 +167,59 @@ Only source maps with the `.js.map` extension work to correctly unminify stack t
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 /static/js instead of https://hostname.com/static/js.
+{{% /tab %}} +{{% tab "Debug ID" %}} + +Debug IDs associate a JavaScript bundle with its source map without relying on the bundle URL, service, or release version. + +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. Add debug IDs to your build output using either a Datadog Build Plugin or `datadog-ci`: + + - To inject debug IDs during the build, configure the [Datadog Build Plugin][8]: + + ```javascript + rum: { + sourceCodeContext: { + debugId: true, + }, + } + ``` + + - To inject debug IDs after the build, run: + + ```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 + ``` + +If a Datadog Build Plugin already injected debug IDs, you do not need to run `datadog-ci sourcemaps inject`. 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. + +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. + +{{% /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 @@ -193,3 +249,6 @@ On the other hand, an unminified stack trace provides you with all the context y [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 +[6]: https://app.datadoghq.com/organization-settings/api-keys +[7]: /getting_started/site/ +[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/ From 2aecf58580d86c14fd42016a75becb642e8cc08e Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Wed, 2 Sep 2026 15:28:46 +0200 Subject: [PATCH 02/10] docs(rum): fix debug ID tab links --- .../guide/upload-javascript-source-maps.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index 93989431934..3daac70046d 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -173,11 +173,11 @@ Only source maps with the `.js.map` extension work to correctly unminify stack t Debug IDs associate a JavaScript bundle with its source map without relying on the bundle URL, service, or release version. 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]. +2. [Create a dedicated Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) 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](/getting_started/site/). 4. Add debug IDs to your build output using either a Datadog Build Plugin or `datadog-ci`: - - To inject debug IDs during the build, configure the [Datadog Build Plugin][8]: + - To inject debug IDs during the build, configure the [Datadog Build Plugin](/real_user_monitoring/application_monitoring/browser/build_plugins/): ```javascript rum: { @@ -249,6 +249,3 @@ On the other hand, an unminified stack trace provides you with all the context y [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 -[6]: https://app.datadoghq.com/organization-settings/api-keys -[7]: /getting_started/site/ -[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/ From 18fd736dac537d89d228382ba95e1d52468f9c26 Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Wed, 2 Sep 2026 15:47:26 +0200 Subject: [PATCH 03/10] docs(rum): align debug ID link style --- .../guide/upload-javascript-source-maps.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index 3daac70046d..371534b39ec 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -173,11 +173,11 @@ Only source maps with the `.js.map` extension work to correctly unminify stack t Debug IDs associate a JavaScript bundle with its source map without relying on the bundle URL, service, or release version. 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](https://app.datadoghq.com/organization-settings/api-keys) 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](/getting_started/site/). +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. Add debug IDs to your build output using either a Datadog Build Plugin or `datadog-ci`: - - To inject debug IDs during the build, configure the [Datadog Build Plugin](/real_user_monitoring/application_monitoring/browser/build_plugins/): + - To inject debug IDs during the build, configure the [Datadog Build Plugin][8]: ```javascript rum: { @@ -217,6 +217,10 @@ 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. +[6]: https://app.datadoghq.com/organization-settings/api-keys +[7]: /getting_started/site/ +[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/ + {{% /tab %}} {{< /tabs >}} From e3357724a0d8e90873e7214063dbafc7508915da Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Wed, 2 Sep 2026 16:19:32 +0200 Subject: [PATCH 04/10] docs(rum): clarify build plugin debug ID uploads --- .../guide/upload-javascript-source-maps.md | 57 +++++++++++++------ 1 file changed, 39 insertions(+), 18 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index 371534b39ec..5acbd7c70cf 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -172,26 +172,47 @@ Only source maps with the `.js.map` extension work to correctly unminify stack t Debug IDs associate a JavaScript bundle with its source map without relying on the bundle URL, service, or release version. -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. Add debug IDs to your build output using either a Datadog Build Plugin or `datadog-ci`: +Choose one of the following upload methods. - - To inject debug IDs during the build, configure the [Datadog Build Plugin][8]: +#### Datadog Build Plugins - ```javascript - rum: { - sourceCodeContext: { - debugId: true, - }, - } - ``` +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. - - To inject debug IDs after the build, run: +Configure both source map uploads and debug ID injection in your build plugin: + +```javascript +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: { + debugId: true, + }, + }, +}); +``` - ```bash - datadog-ci sourcemaps inject /path/to/dist - ``` +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: @@ -199,7 +220,7 @@ Debug IDs associate a JavaScript bundle with its source map without relying on t datadog-ci sourcemaps upload /path/to/dist --debug-id ``` -If a Datadog Build Plugin already injected debug IDs, you do not need to run `datadog-ci sourcemaps inject`. Do not pass `--service`, `--release-version`, or `--minified-path-prefix` with `--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. @@ -219,7 +240,7 @@ The `find` command only inspects local `*.js.map` files. It does not confirm whe [6]: https://app.datadoghq.com/organization-settings/api-keys [7]: /getting_started/site/ -[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/ +[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/source_maps/ {{% /tab %}} {{< /tabs >}} From c961f2c3414649dee849aa3cb2300e718d355ba1 Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Thu, 3 Sep 2026 09:45:08 +0200 Subject: [PATCH 05/10] docs(rum): document direct debug ID uploads --- .../build_plugins/source_code_context.md | 25 ++++------ .../browser/build_plugins/source_maps.md | 49 +++++++++++++++---- .../guide/upload-javascript-source-maps.md | 12 ++--- 3 files changed, 54 insertions(+), 32 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md index d5853cb7979..a46f0960662 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md +++ b/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,14 +20,14 @@ 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 that 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 @@ -36,12 +36,14 @@ Configure the `rum.sourceCodeContext` object in your build plugin options: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| -| `rum.sourceCodeContext.service` | String | Yes | None | Service name. Must match the RUM SDK `service` initialization parameter. | +| `rum.sourceCodeContext.debugId` | Boolean | No | `false` | Inject a deterministic debug ID into each JavaScript bundle. | +| `rum.sourceCodeContext.upload` | Boolean | No | `false` | Upload source maps by debug ID during the build. Requires `debugId: true` and a Datadog API key. | +| `rum.sourceCodeContext.service` | String | Yes, unless `debugId` is enabled | 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. | ## Example -The following example shows source code context combined with source maps, a common pairing: +The following example injects debug IDs and uploads source maps directly from the build plugin: ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); @@ -52,17 +54,10 @@ module.exports = { auth: { apiKey: process.env.DATADOG_API_KEY, }, - errorTracking: { - sourcemaps: { - service: 'my-application', - releaseVersion: '1.0.0', - minifiedPathPrefix: 'https://example.com/static/', - }, - }, rum: { sourceCodeContext: { - service: 'my-application', - version: '1.0.0', + debugId: true, + upload: true, }, }, }), diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md index 4b8e773e628..a07ac0451a7 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md @@ -19,18 +19,53 @@ 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. Source maps can be associated 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. + +### Debug ID + +Configure `rum.sourceCodeContext.debugId` and `rum.sourceCodeContext.upload` 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 + }, + rum: { + sourceCodeContext: { + debugId: true, + upload: true, + }, + }, + }), + ], +}; +``` + +Debug ID uploads do not require a service, release version, or minified path prefix. Set `upload` to `false` or omit it to inject debug IDs without uploading source maps from the build plugin. + +### Service and version + +Configure the `errorTracking.sourcemaps` object to upload source maps using service and version matching: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -41,11 +76,7 @@ Configure the `errorTracking.sourcemaps` object in your build plugin options: | `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. | -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. - -## Example +#### Example ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); @@ -71,7 +102,7 @@ module.exports = {
This example uses webpack. The configuration object is identical across all supported bundlers — only the import and plugin function name differ. See Build Plugins for installation instructions for your bundler.
-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. +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. ## Further reading diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index 5acbd7c70cf..f9348864d30 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -178,7 +178,7 @@ Choose one of the following upload methods. 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. -Configure both source map uploads and debug ID injection in your build plugin: +Enable debug ID injection and source map uploads in your build plugin: ```javascript datadogWebpackPlugin({ @@ -186,21 +186,17 @@ datadogWebpackPlugin({ 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: { debugId: true, + upload: true, }, }, }); ``` +The plugin uploads each source map with the debug ID injected into its corresponding JavaScript bundle. You do not need to configure a service, release version, or minified path prefix. + This example uses webpack. See [Datadog Build Plugins][8] for installation and configuration instructions for other supported bundlers. #### `datadog-ci` From 79a6ebe6403f61b7d611656cfc025d1e6b366647 Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Thu, 3 Sep 2026 14:49:27 +0200 Subject: [PATCH 06/10] docs(rum): use debug ID upload configuration --- .../browser/build_plugins/source_code_context.md | 9 +++++++-- .../browser/build_plugins/source_maps.md | 12 +++++++++--- .../guide/upload-javascript-source-maps.md | 6 +++++- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md index a46f0960662..4f709df16c6 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md @@ -34,10 +34,11 @@ At build time, the plugin injects a snippet that writes metadata to `window.DD_S Configure the `rum.sourceCodeContext` object in your build plugin options: +Choose either debug ID matching or service and version matching. The two configurations are mutually exclusive. + | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `rum.sourceCodeContext.debugId` | Boolean | No | `false` | Inject a deterministic debug ID into each JavaScript bundle. | -| `rum.sourceCodeContext.upload` | Boolean | No | `false` | Upload source maps by debug ID during the build. Requires `debugId: true` and a Datadog API key. | | `rum.sourceCodeContext.service` | String | Yes, unless `debugId` is enabled | 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. | @@ -54,10 +55,14 @@ module.exports = { auth: { apiKey: process.env.DATADOG_API_KEY, }, + errorTracking: { + sourcemaps: { + debugId: true, + }, + }, rum: { sourceCodeContext: { debugId: true, - upload: true, }, }, }), diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md index a07ac0451a7..d8a4e10f0a7 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md @@ -36,9 +36,11 @@ 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. + ### Debug ID -Configure `rum.sourceCodeContext.debugId` and `rum.sourceCodeContext.upload` to inject debug IDs and upload source maps during the build: +Configure `rum.sourceCodeContext.debugId` to inject debug IDs and `errorTracking.sourcemaps.debugId` to upload source maps during the build: ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); @@ -50,10 +52,14 @@ module.exports = { apiKey: process.env.DATADOG_API_KEY, site: 'datadoghq.com', // Optional: defaults to datadoghq.com }, + errorTracking: { + sourcemaps: { + debugId: true, + }, + }, rum: { sourceCodeContext: { debugId: true, - upload: true, }, }, }), @@ -61,7 +67,7 @@ module.exports = { }; ``` -Debug ID uploads do not require a service, release version, or minified path prefix. Set `upload` to `false` or omit it to inject debug IDs without uploading source maps from the build plugin. +Debug ID uploads do not require a service, release version, or minified path prefix. Omit `errorTracking.sourcemaps` to inject debug IDs without uploading source maps from the build plugin. ### Service and version diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index f9348864d30..22f2edce3ed 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -186,10 +186,14 @@ datadogWebpackPlugin({ apiKey: process.env.DATADOG_API_KEY, site: 'datadoghq.com', }, + errorTracking: { + sourcemaps: { + debugId: true, + }, + }, rum: { sourceCodeContext: { debugId: true, - upload: true, }, }, }); From 382163bcb990c7eefac6a1b1a9996e0e6938298e Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Thu, 3 Sep 2026 18:32:52 +0200 Subject: [PATCH 07/10] docs(rum): separate source context matching options --- .../build_plugins/source_code_context.md | 49 +++++++++++++++---- 1 file changed, 40 insertions(+), 9 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md index 4f709df16c6..688e22faa01 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md @@ -32,19 +32,16 @@ At build time, the plugin injects a snippet that writes metadata to `window.DD_S ## Configuration -Configure the `rum.sourceCodeContext` object in your build plugin options: +Configure `rum.sourceCodeContext` using one of the following methods. The two configurations are mutually exclusive. -Choose either debug ID matching or service and version matching. The two configurations are mutually exclusive. +{{< tabs >}} +{{% tab "Debug ID (Recommended)" %}} -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|---------|-------------| -| `rum.sourceCodeContext.debugId` | Boolean | No | `false` | Inject a deterministic debug ID into each JavaScript bundle. | -| `rum.sourceCodeContext.service` | String | Yes, unless `debugId` is enabled | 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. | +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. -## Example +Set `debugId` to `true` in `rum.sourceCodeContext` to inject a debug ID into each JavaScript bundle. -The following example injects debug IDs and uploads source maps directly from the build plugin: +The following example also configures `errorTracking.sourcemaps.debugId` so that the build plugin uploads the source maps: ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); @@ -70,6 +67,40 @@ module.exports = { }; ``` +If you upload source maps with another tool, such as `datadog-ci`, omit `auth` and `errorTracking.sourcemaps` from this configuration. + +{{% /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', + version: '1.0.0', + }, + }, + }), + ], +}; +``` + +The `service` and `version` values must match the metadata used when uploading the source maps. + +{{% /tab %}} +{{< /tabs >}} +
This example uses webpack. The configuration object is identical across all supported bundlers. See Build Plugins for installation instructions for your bundler.
## Further reading From 0553265ebba05ba647d6fcee26948612a19baffe Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Fri, 4 Sep 2026 09:34:41 +0200 Subject: [PATCH 08/10] docs(rum): clarify debug ID documentation flows --- .../build_plugins/source_code_context.md | 12 -- .../browser/build_plugins/source_maps.md | 42 ++++-- .../guide/upload-javascript-source-maps.md | 130 +++++++++--------- 3 files changed, 95 insertions(+), 89 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md index 688e22faa01..63fc8319623 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md @@ -41,22 +41,12 @@ Debug IDs associate each JavaScript bundle with its source map without relying o Set `debugId` to `true` in `rum.sourceCodeContext` to inject a debug ID into each JavaScript bundle. -The following example also configures `errorTracking.sourcemaps.debugId` so that the build plugin uploads the source maps: - ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); module.exports = { plugins: [ datadogWebpackPlugin({ - auth: { - apiKey: process.env.DATADOG_API_KEY, - }, - errorTracking: { - sourcemaps: { - debugId: true, - }, - }, rum: { sourceCodeContext: { debugId: true, @@ -67,8 +57,6 @@ module.exports = { }; ``` -If you upload source maps with another tool, such as `datadog-ci`, omit `auth` and `errorTracking.sourcemaps` from this configuration. - {{% /tab %}} {{% tab "Service and version" %}} diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md index d8a4e10f0a7..f201e6a7ca1 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md @@ -38,9 +38,21 @@ The following environment variables override configuration values: Choose either debug ID uploads or service and version uploads. Do not configure both upload methods in the same build. -### Debug ID +{{< tabs >}} +{{% tab "Debug ID (Recommended)" %}} -Configure `rum.sourceCodeContext.debugId` to inject debug IDs and `errorTracking.sourcemaps.debugId` to upload source maps during the build: +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 `errorTracking.sourcemaps`: + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `debugId` | Boolean | Yes | None | Set to `true` to upload source maps using 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. | + +Also configure `rum.sourceCodeContext.debugId` to inject debug IDs during the build: ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); @@ -67,22 +79,21 @@ module.exports = { }; ``` -Debug ID uploads do not require a service, release version, or minified path prefix. Omit `errorTracking.sourcemaps` to inject debug IDs without uploading source maps from the build plugin. +Debug ID uploads do not require a service, release version, or minified path prefix. -### Service and version +{{% /tab %}} +{{% tab "Service and version" %}} Configure the `errorTracking.sourcemaps` object to upload source maps using service and version matching: | 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. | - -#### Example +| `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'); @@ -106,10 +117,13 @@ module.exports = { }; ``` -
This example uses webpack. The configuration object is identical across all supported bundlers — only the import and plugin function name differ. See Build Plugins for installation instructions for your bundler.
- 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 >}} + +
These examples use webpack. The configuration object is identical across all supported bundlers — only the import and plugin function name differ. See Build Plugins for installation instructions for your bundler.
+ ## Further reading {{< partial name="whats-next/whats-next.html" >}} diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index 22f2edce3ed..87be510188a 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -119,56 +119,7 @@ If the sum of the file size for javascript.364758.min.js and 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 "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`. -3. Run the following command once per service in your application: - - ```bash - datadog-ci sourcemaps upload /path/to/dist \ - --service my-service \ - --release-version v35.2395005 \ - --minified-path-prefix https://hostname.com/static/js - ``` - - -[1]: https://app.datadoghq.com/organization-settings/api-keys -{{< /site-region >}} - -{{< site-region region="eu,us3,us5,gov,gov2,ap1,ap2,uk1" >}} -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`. -3. Configure the CLI to upload files to the {{}} site by exporting two environment variables: `export DATADOG_SITE=`{{}} and `export DATADOG_API_HOST=api.`{{}}. -4. Run the following command once per service in your application: - ```bash - datadog-ci sourcemaps upload /path/to/dist \ - --service my-service \ - --release-version v35.2395005 \ - --minified-path-prefix https://hostname.com/static/js - ``` - - -[1]: https://app.datadoghq.com/organization-settings/api-keys -{{< /site-region >}} - -To minimize overhead on your CI's performance, the CLI is optimized to upload as many source maps as you need in a short amount of time (typically a few seconds). - -**Note**: Re-uploading a source map does not override the existing one if the version has not changed. - -The `--service` and `--release-version` parameters must match the `service` and `version` tags on your Error Tracking events, RUM events, and browser logs. For more information on how to setup these tags, refer to the [Browser SDK initialization documentation][2] or [Browser Logs Collection documentation][3]. - -
If you have defined multiple services in your application, run the CI command as many times as there are services, even if you have one set of sourcemaps for the entire application.
- -By running the command against the example `dist` directory, Datadog expects your server or CDN to deliver the JavaScript files at `https://hostname.com/static/js/javascript.364758.min.js` and `https://hostname.com/static/js/subdirectory/javascript.464388.min.js`. - -Only source maps with the `.js.map` extension work to correctly unminify stack traces. Source maps with other extensions such as `.mjs.map` are accepted but do not unminify stack traces. - -
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 /static/js instead of https://hostname.com/static/js.
- -{{% /tab %}} -{{% tab "Debug ID" %}} +{{% tab "Debug ID (Recommended)" %}} Debug IDs associate a JavaScript bundle with its source map without relying on the bundle URL, service, or release version. @@ -199,7 +150,7 @@ datadogWebpackPlugin({ }); ``` -The plugin uploads each source map with the debug ID injected into its corresponding JavaScript bundle. You do not need to configure a service, release version, or minified path prefix. +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. @@ -224,23 +175,58 @@ Do not pass `--service`, `--release-version`, or `--minified-path-prefix` with ` 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. -To find the local source map for a specific debug ID, run: +[6]: https://app.datadoghq.com/organization-settings/api-keys +[7]: /getting_started/site/ +[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/source_maps/ -```bash -datadog-ci sourcemaps find /path/to/dist --debug-id 12345678-1234-1234-1234-123456789abc -``` +{{% /tab %}} +{{% tab "Service and version" %}} -To find source maps that do not contain a debug ID, run: +{{< 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`. +3. Run the following command once per service in your application: -```bash -datadog-ci sourcemaps find /path/to/dist --missing-debug-id -``` + ```bash + datadog-ci sourcemaps upload /path/to/dist \ + --service my-service \ + --release-version v35.2395005 \ + --minified-path-prefix https://hostname.com/static/js + ``` -The `find` command only inspects local `*.js.map` files. It does not confirm whether Datadog received an artifact. -[6]: https://app.datadoghq.com/organization-settings/api-keys -[7]: /getting_started/site/ -[8]: /real_user_monitoring/application_monitoring/browser/build_plugins/source_maps/ +[1]: https://app.datadoghq.com/organization-settings/api-keys +{{< /site-region >}} + +{{< site-region region="eu,us3,us5,gov,gov2,ap1,ap2,uk1" >}} +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`. +3. Configure the CLI to upload files to the {{}} site by exporting two environment variables: `export DATADOG_SITE=`{{}} and `export DATADOG_API_HOST=api.`{{}}. +4. Run the following command once per service in your application: + ```bash + datadog-ci sourcemaps upload /path/to/dist \ + --service my-service \ + --release-version v35.2395005 \ + --minified-path-prefix https://hostname.com/static/js + ``` + + +[1]: https://app.datadoghq.com/organization-settings/api-keys +{{< /site-region >}} + +To minimize overhead on your CI's performance, the CLI is optimized to upload as many source maps as you need in a short amount of time (typically a few seconds). + +**Note**: Re-uploading a source map does not override the existing one if the version has not changed. + +The `--service` and `--release-version` parameters must match the `service` and `version` tags on your Error Tracking events, RUM events, and browser logs. For more information on how to setup these tags, refer to the [Browser SDK initialization documentation][2] or [Browser Logs Collection documentation][3]. + +
If you have defined multiple services in your application, run the CI command as many times as there are services, even if you have one set of sourcemaps for the entire application.
+ +By running the command against the example `dist` directory, Datadog expects your server or CDN to deliver the JavaScript files at `https://hostname.com/static/js/javascript.364758.min.js` and `https://hostname.com/static/js/subdirectory/javascript.464388.min.js`. + +Only source maps with the `.js.map` extension work to correctly unminify stack traces. Source maps with other extensions such as `.mjs.map` are accepted but do not unminify stack traces. + +
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 /static/js instead of https://hostname.com/static/js.
{{% /tab %}} {{< /tabs >}} @@ -253,6 +239,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. From 694e2d579077a6dc11c9140f46ae4695892fca0e Mon Sep 17 00:00:00 2001 From: Hugo Silva Date: Fri, 4 Sep 2026 13:57:12 +0200 Subject: [PATCH 09/10] docs(rum): simplify debug ID sourcemap setup --- .../build_plugins/source_code_context.md | 10 ++++----- .../browser/build_plugins/source_maps.md | 21 +++++++------------ .../guide/upload-javascript-source-maps.md | 12 +++-------- 3 files changed, 14 insertions(+), 29 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md index 63fc8319623..879784d6b1d 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md @@ -32,14 +32,14 @@ At build time, the plugin injects a snippet that writes metadata to `window.DD_S ## Configuration -Configure `rum.sourceCodeContext` using one of the following methods. The two configurations are mutually exclusive. +Choose one of the following source code context methods. The two configurations are mutually exclusive. {{< 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. -Set `debugId` to `true` in `rum.sourceCodeContext` to inject a debug ID into each JavaScript bundle. +Set `debugId` to `true` in `sourcemaps` to inject a debug ID into each JavaScript bundle. ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); @@ -47,10 +47,8 @@ const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); module.exports = { plugins: [ datadogWebpackPlugin({ - rum: { - sourceCodeContext: { - debugId: true, - }, + sourcemaps: { + debugId: true, }, }), ], diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md index f201e6a7ca1..509796ea2ab 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md @@ -43,16 +43,17 @@ Choose either debug ID uploads or service and version uploads. Do not configure 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 `errorTracking.sourcemaps`: +Configure the following options in `sourcemaps`: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| -| `debugId` | Boolean | Yes | None | Set to `true` to upload source maps using debug IDs. | +| `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. | -Also configure `rum.sourceCodeContext.debugId` to inject debug IDs during the build: +Set `debugId` and `upload` to `true` to inject debug IDs and upload source maps during the build: ```javascript const { datadogWebpackPlugin } = require('@datadog/webpack-plugin'); @@ -64,23 +65,15 @@ module.exports = { apiKey: process.env.DATADOG_API_KEY, site: 'datadoghq.com', // Optional: defaults to datadoghq.com }, - errorTracking: { - sourcemaps: { - debugId: true, - }, - }, - rum: { - sourceCodeContext: { - debugId: true, - }, + sourcemaps: { + debugId: true, + upload: true, }, }), ], }; ``` -Debug ID uploads do not require a service, release version, or minified path prefix. - {{% /tab %}} {{% tab "Service and version" %}} diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index 87be510188a..a3ef268d025 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -137,15 +137,9 @@ datadogWebpackPlugin({ apiKey: process.env.DATADOG_API_KEY, site: 'datadoghq.com', }, - errorTracking: { - sourcemaps: { - debugId: true, - }, - }, - rum: { - sourceCodeContext: { - debugId: true, - }, + sourcemaps: { + debugId: true, + upload: true, }, }); ``` From b861e33517ff131ea61f29df71941db0d8946507 Mon Sep 17 00:00:00 2001 From: Heston Hoffman Date: Fri, 4 Sep 2026 10:24:56 -0700 Subject: [PATCH 10/10] docs(rum): fix tab-scoped link refs and split long sentences Moves the service/version link definitions into the tab that uses them so they resolve, and shortens two run-on sentences in the debug ID source map pages. --- .../browser/build_plugins/source_code_context.md | 2 +- .../browser/build_plugins/source_maps.md | 2 +- .../guide/upload-javascript-source-maps.md | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md index 879784d6b1d..ffbfecccd6b 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_code_context.md @@ -20,7 +20,7 @@ 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 a debug ID or with `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 this metadata to associate stack frames with [uploaded source maps][2]. diff --git a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md index 509796ea2ab..47170666b1d 100644 --- a/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md +++ b/hugo/content/en/real_user_monitoring/application_monitoring/browser/build_plugins/source_maps.md @@ -19,7 +19,7 @@ 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. Source maps can be associated with events by debug ID or by service and version. +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 diff --git a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md index a3ef268d025..30332729e2a 100644 --- a/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md +++ b/hugo/content/en/real_user_monitoring/guide/upload-javascript-source-maps.md @@ -222,6 +222,9 @@ Only source maps with the `.js.map` extension work to correctly unminify stack t
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 /static/js instead of https://hostname.com/static/js.
+[2]: /real_user_monitoring/application_monitoring/browser/setup/#initialization-parameters +[3]: /logs/log_collection/javascript/#initialization-parameters + {{% /tab %}} {{< /tabs >}} @@ -268,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