Skip to content

sourcemaps

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

sourcemaps

README.md

Sourcemaps command

Upload JavaScript sourcemaps to Datadog to un-minify your errors.

Setup

You need to have DD_API_KEY in your environment.

# Environment setup
export DD_API_KEY="<API KEY>"

It is possible to configure the tool to use Datadog EU by defining the DD_SITE environment variable to datadoghq.eu. By default the requests are sent to Datadog US.

It is also possible to override the full URL for the intake endpoint by defining the DATADOG_SOURCEMAP_INTAKE_URL environment variable.

Commands

inject

This command injects a deterministic debug ID into each JavaScript bundle and adjusts its sourcemap so existing mappings continue to point to the original source positions. Run it after building and before deploying the bundles:

datadog-ci sourcemaps inject ./build

The command modifies the JavaScript bundles and sourcemaps in place. Deploy and upload those same modified artifacts:

datadog-ci sourcemaps inject ./build
datadog-ci sourcemaps upload ./build --debug-id

Bundles that already contain a debug ID are not reinjected. The command still adds or corrects the sourcemap's top-level debug_id field so it matches the bundle. Use --dry-run to preview injection without modifying files, and --max-concurrency to control concurrent artifact discovery.

Valid sourcemaps with an empty mappings field contain no original positions to deobfuscate. The command leaves those sourcemaps and their JavaScript bundles unchanged and reports them as skipped.

The inject command always records the ID in the sourcemap's top-level debug_id field. The upload command reads the authoritative ID from the JavaScript bundle and sends it as upload metadata; upload matching does not depend on the sourcemap field, so artifacts produced directly by Datadog build plugins remain compatible.

Run your application's normal build again before reinjecting whenever its source code or build configuration changes. The build may reuse the same output filenames, but it must recreate the JavaScript bundles and sourcemaps without the previous injection (a clean build is recommended). Then run sourcemaps inject and sourcemaps upload --debug-id again. Changed bundle contents receive a new debug ID, while unchanged rebuilt bundles reproduce the same deterministic ID. Do not modify generated artifacts between injection, upload, and deployment: rerunning inject preserves an existing debug ID and does not detect post-injection changes.

Injection changes the JavaScript bundle bytes. Run it before any byte-dependent post-processing such as generating Subresource Integrity (SRI) hashes, compressed .gz/.br assets, signatures, or checksum manifests. If your build creates those outputs automatically, regenerate them after injection. Upload and deploy the exact same injected JavaScript and sourcemap files.

For example, using your project's own build script:

npm run clean # If your build does not clean its output itself.
npm run build
datadog-ci sourcemaps inject ./build
# Regenerate compression, SRI, signatures, or checksums here when applicable.
datadog-ci sourcemaps upload ./build --debug-id

upload

This command will upload all JavaScript sourcemaps and their corresponding JavaScript bundles to Datadog in order to un-minify front-end stack traces received by Datadog.

With --debug-id, this command uploads only bundles that already contain a debug ID. It does not modify build artifacts; run sourcemaps inject first when debug IDs are missing.

To upload the sourcemaps in the build folder, this command should be run:

datadog-ci sourcemaps upload ./build --service my-service --minified-path-prefix https://static.datadog.com --release-version 1.234

  • The first positional argument is the directory in which sourcemaps are located. The CLI will look for all .js.map files in this folder and subfolders recursively. The corresponding JS file should be located in the same folder as the sourcemaps it applies to (for example, common.min.js.map and common.min.js should be in the same directory). The folder structure should match the structure of the served static files.

  • --service (required) should be set as the name of the service you're uploading sourcemaps for, and Datadog will use this service name to find the corresponding sourcemaps based on the service tag set on the RUM SDK.

  • --release-version (required) is similar and will be used to match the version tag set on the RUM SDK.

  • --minified-path-prefix (required) should be a prefix common to all your JS source files, depending on the URL they are served from. The prefix can be a full URL or an absolute path. Example: if you're uploading dist/file.js to https://example.com/static/file.js, you can use datadog-ci sourcemaps upload ./dist --minified-path-prefix https://example.com/static/ or datadog-ci sourcemaps upload ./dist --minified-path-prefix /static/. --minified-path-prefix / is a valid input when you upload JS at the root directory of the server.

In addition, some optional parameters are available:

  • --max-concurrency (default: 20): number of concurrent upload to the API.
  • --disable-git (default: false): prevents the command from invoking git in the current working directory and sending repository-related data to Datadog (such as the hash, remote URL, and paths within the repository of sources referenced in the sourcemap).
  • --quiet (default: false): suppresses individual line output for each upload. Success and error logs are never suppressed.
  • --dry-run (default: false): it will run the command without the final step of upload. All other checks are performed.
  • --project-path (default: empty): the path of the project where the sourcemaps were built. This will be stripped off from sources paths referenced in the sourcemap so they can be properly matched against tracked files paths. See details in the dedicated section.
  • --repository-url (default: empty): overrides the repository remote with a custom URL, for example, https://github.com/my-company/my-project. Can also be set via the DD_GIT_REPOSITORY_URL environment variable.
  • --commit-sha (default: empty): overrides the git commit SHA. Can also be set via the DD_GIT_COMMIT_SHA environment variable.

Link errors with your source code

Errors in Datadog UI can be enriched with direct links to your repository if these requirements are met:

  • git executable is installed
  • datadog-ci is run within the git repository
  • --disable-git is not set

When these requirements are met, the upload command reports Git information such as:

  • the current commit hash
  • the repository URL
  • for each sourcemap, the list of file paths that are tracked in the repository. Only tracked file paths that could be related to a sourcemap are gathered. For example, for a sourcemap referencing ["webpack:///./src/folder/example.ts"] inside its sources attribute, the command will gather all file paths with example.ts as filename.

Override repository URL

The repository URL is inferred

  • from the remote named origin if present
  • from the first remote otherwise

The value can be overridden with --repository-url.

Example: With a remote git@github.com:Datadog/example.git, links pointing to https://github.com/Datadog/example are generated. This behavior can be overridden with links to https://gitlab.com/Datadog/example with the flag --repository-url=https://gitlab.com/Datadog/example.

Bypassing git invocations

If your build environment does not have access to the .git/ folder, you can bypass git invocations by providing both --repository-url and --commit-sha (or DD_GIT_REPOSITORY_URL and DD_GIT_COMMIT_SHA).

In this mode:

  • The source files are directly extracted from the sources field of each sourcemap, which means untracked files may be sent to Datadog.
  • The repository root is assumed to be the folder from which datadog-ci is run.

Setting the project path

If the file paths referenced by your sourcemaps have a prefix before the part relative to the repository root, you need to specify the --project-path argument.

For example, if your repository contains a file at src/foo/example.js, then:

  • if the path referenced in the sourcemap is webpack://src/foo/example.js, you don't need to use --project-path.
  • if the path referenced in the sourcemap is webpack://MyProject/src/foo/example.js, you need to use --project-path MyProject/ for files to be correctly linked to your repository.

Supported repositories

The only repository URLs supported are the ones whose host contains: github, gitlab, bitbucket, or dev.azure. This allows Datadog to create proper URLs such as:

Provider URL
GitHub / GitLab https://<repository-url>/blob/<commit-hash>/<tracked-file-path>#L<line>
Bitbucket https://<repository-url>/src/<commit-hash>/<tracked-file-path>#lines-<line>
Azure DevOps https://<repository-url>?version=GC<commit-hash>&path=<tracked-file-path>&line=<line>&lineEnd=<line + 1>&lineStartColumn=1&lineEndColumn=1

End-to-end testing process

To verify this command works as expected, you can trigger a test run and verify it returns 0:

export DD_API_KEY='<API key>'
export DATADOG_APP_KEY='<application key>'

TEMP_DIR=$(mktemp -d)
echo '{}' > $TEMP_DIR/fake.js
echo '{"version":3,"file":"out.js","sourceRoot":"","sources":["fake.js"],"names":["src"],"mappings":"AAgBC"}' > $TEMP_DIR/fake.js.map
yarn launch sourcemaps upload $TEMP_DIR/ --service test_datadog-ci --release-version 0.0.1 --minified-path-prefix https://fake.website
rm -rf $TEMP_DIR

Successful output should look like this:

Starting upload with concurrency 20.
Will look for sourcemaps in /var/folders/s_/ds1hc9g54k7ct8x7p3kwsq1h0000gn/T/tmp.fqWhNgGdn6/
Will match JS files for errors on files starting with https://fake.website
version: 0.0.1 service: test_datadog-ci project path:
Uploading sourcemap /var/folders/s_/ds1hc9g54k7ct8x7p3kwsq1h0000gn/T/tmp.fqWhNgGdn6/fake.js.map for JS file available at https://fake.website/fake.js
✅ Uploaded 1 files in 0.68 seconds.

Further reading

Additional helpful documentation, links, and articles: