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..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
@@ -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,28 +20,26 @@ 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');
@@ -49,16 +47,30 @@ 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 >}}
+
This example uses webpack. The configuration object is identical across all supported bundlers. See
Build Plugins for installation instructions for your bundler.
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.
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.
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 "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
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 >}}
+
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