Upload Javascript source maps

Overview

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

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.

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

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

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

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:

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

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 very short amount of time (typically a few seconds) to minimize the overhead on your CI’s performance.

By running this command against our example dist directory (see previous section), Datadog will expect 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 will be 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.

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:

On the contrary, an unminified stack trace gives you all the context you need for a fast and seamless troubleshooting:

Further Reading

Additional helpful documentation, links, and articles:

Get started with Error TrackingDOCUMENTATION Visualize your Error Tracking data in the ExplorerDOCUMENTATION