Upload Javascript source maps

Overview

If your front-end Javascript source code is minified, you need to upload your source maps to Datadog so that your different stack traces can be deobfuscated. For a given error, you then get access to the file path, the line number, as well as a code snippet for each frame of the related stack trace.

Note: Only errors collected by Real User Monitoring (RUM) can be unminified and processed by Error Tracking.

Instrument your code

You must configure your Javascript bundler so that, when minifying your source code, it generates source maps which directly include the related source code in the sourcesContent attribute. In addition, ensure that the size of each source map augmented with the size of the related minified file does not exceed our limit of 50MB. Check below for some configurations for popular Javascript bundlers.

Dropdown

You can generate source maps by using the built-in webpack plugin named SourceMapDevToolPlugin. Check below how to configure it in your webpack.config.js file:

// ...
const webpack = require('webpack');

module.exports = {
  mode: 'production',
  devtool: false,
  plugins: [
    new webpack.SourceMapDevToolPlugin({
      noSources: false,
      filename: '[file].map'
    }),
    // ...
  ],
  optimization: {
    minimize: true,
    // ...
  },
  // ...
};

Note: If you are using TypeScript, make sure to set compilerOptions.sourceMap to true when configuring your tsconfig.json file.

Parcel generates source maps by default when you run the build command: parcel build <entry file>

After building your application, bundlers generate a directory, most of the time named dist, with minified Javascript files colocated with their corresponding source maps. Check an example below:

./dist
    javascript.364758.min.js
    javascript.364758.js.map
    ./subdirectory
        javascript.464388.min.js
        javascript.464388.js.map

If, for example, the sum of the file size of javascript.364758.min.js and javascript.364758.js.map exceeds the 50MB limit, reduce it by configuring your bundler to split the source code into multiple smaller chunks (See how to do this with WebpackJS).

Upload your source maps

The best way to upload source maps is to add an extra-step in your CI pipeline and to run the dedicated command from the Datadog CLI. It scans the dist directory and its subdirectories to automatically upload the source maps with their related minified files. The flow is the following:

Dropdown

Add @datadog/datadog-ci to your package.json file (make sure to use the latest version).
Create a new and dedicated Datadog API key and export it as an environment variable named DATADOG_API_KEY.
Run the following command:

datadog-ci sourcemaps upload /path/to/dist \
	--service=my-service \
	--release-version=v35.2395005 \
	--minified-path-prefix=https://hostname.com/static/js

Add @datadog/datadog-ci to your package.json file (make sure to use the latest version).
Create a new and dedicated Datadog API key and export it as an environment variable named DATADOG_API_KEY.
Configure the CLI to upload files to the EU region by exporting two additonal environment variables: export DATADOG_SITE="datadoghq.eu" and export DATADOG_API_HOST="api.datadoghq.eu".
Run the following command:

datadog-ci sourcemaps upload /path/to/dist \
	--service=my-service \
	--release-version=v35.2395005 \
	--minified-path-prefix=https://hostname.com/static/js

Note: The CLI has been optimized to upload as many source maps as you need in a short amount of time (typically a few seconds) to minimize the overhead on your CI’s performance.

By running this command against the example dist directory (see previous section), Datadog expects your server or your 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. When an error occurs in a session of one of your users, the RUM SDK instantaneously collects it. Whenever the given error originated in a file that were downloaded from one of those urls and is also tagged with version:v35.2395005 and service:my-service, the related source map is used to deobfuscate the stack trace (in this case, the javascript.464388.js.map file).

Note: Only source maps with the .js.map extension work to correctly unminify stack traces in the error tracking UI. Source maps with other extensions, such as .mjs.map, are accepted but do not unminify stack traces.

A given JavaScript source file can be served from different subdomains depending on the environment (for example, staging or production). You can upload the related source map once and make it work for multiple subdomains by using the absolute prefix path instead of the full url (specify /static/js instead of https://hostname.com/static/js).

Troubleshoot errors with ease

A minified stack trace is not helpful as you don’t have access to the file path and the line number. It’s hard to know where something is happening in your code base. In addition, the code snippet is still minified (one long line of transformed code) which makes the troubleshooting process even harder. See below an example of an minified stack trace: