Prerequisites

• Update your browser RUM agent (splunk-otel-web.js) to v0.20.2 or later. Otherwise, Splunk RUM can't symbolicate stack traces from browser apps.

• Install the splunk-rum CLI.

Option 1: Use the splunk-rum CLI

1. Set up your build environment:

   Tip: These examples cover common build tools. If your tools differ, you can still use the splunk-rum CLI; adapt the examples as a general guide for your setup.

   1. Verify that your production build tool is configured to generate source maps.

      Refer to the documentation of your JavaScript bundler or framework for how to enable source maps for your bundler tool. For example:

      • If you're using the Webpack bundler, add a configuration like devtool: "source-map" to your project’s webpack.config.js file.

      • If you're using the Next.js framework, add productionBrowserSourceMaps: true to your project’s next.config.ts file.

   2. Build your project in production mode.

      In other words, run your bundler or framework’s command to build your project in production mode (not development mode).

      • For the Webpack bunder, run the command webpack

      • For the Next.js framework, run the command next build

      • If your package.json already has a script defined for building your application in production mode, run that script. For example, for the following package.json:

        // package.json
        {
          ...
          "scripts": {
            "build": "webpack",
            "dev": "webpack --mode=development"
            ...
          }
          ...
        }
        

        Run the build script (not the dev script):

        npm run build
        

   3. Verify that your production bundles and source maps were written to the same output directory.

      In other words, determine what directory your bundler or framework uses for the output directory, then inspect the contents of this directory. For example:

      • If you're using Webpack, look in dist (the default output directory).

      • If you're using Next.js, look in a directory inside .next.

      The output directory is what you will provide with the --path option on splunk-rum commands.

      If the output folder for your build command is the ./dist directory, then inspect that directory’s contents to verify that both .js and .js.map files were created:

      # verify that both .js and .js.map files appear here
      find ./dist -type f | sort
      

      This verifies that the production build command is properly configured to generate both both .js and .js.map files inside the output directory ./dist.

2. Find all source map/minified file pairs in the directory you specify, compute a source map ID for each pair, and inject that source map ID into each minified file as a code snippet:

   splunk-rum sourcemaps inject --path path-to-production-files

3. Upload the source maps in the directory you specify to Splunk RUM. In this command, use the same values for application name (applicationName) and application version (applicationVersion) that you used in Configure the Splunk Browser RUM instrumentation.

   Note: If you didn't set the SPLUNK_REALM and SPLUNK_ACCESS_TOKEN environment variables, you must also add the --realm value and --token your-splunk-org-access-token parameters to this command.

   splunk-rum sourcemaps upload \
   --app-name applicationName \
   --app-version applicationVersion \
   --path path-to-production-files

Syntax

splunk-rum [command] [parameters]

Command descriptions

Option 2: Use the Webpack build plugin

If your project uses Webpack 5 as its bundling tool, you can add the Splunk RUM Webpack build plugin to your project to make it easier to support source mapping. This plugin is a separate npm artifact in the splunk-otel-js-web repository.

If your project uses a different bunding tool or a different version of Webpack, use the splunk-rum CLI instead.

1. Add the Splunk RUM Webpack plugin to your package.json as a dev dependency:

   npm install @splunk/rum-build-plugins --save-dev

2. Configure your webpack.config.js to generate source maps. See Devtool | webpack.

3. Add the Splunk RUM Webpack plugin to your list of plugins by adding the following lines to your webpack.config.js, where <applicationName> and <applicationVersion> are the same values that you used in Configure the Splunk Browser RUM instrumentation.

   If you don't want source maps to be uploaded while you're doing local builds for your own local development, set disableUpload to true.

   const { SplunkRumWebpackPlugin } = require('@splunk/rum-build-plugins')
   module.exports = {
     ...
       plugins: [
           ...,
           new SplunkRumWebpackPlugin({
               applicationName: 'applicationName',
               version: 'applicationVersion',
               sourceMaps: {
                   token: 'your-splunk-org-access-token',
                   realm: 'your-splunk-observability-realm',
                   // Optional: conditionally set 'disabledUpload' so that file uploads
                   // are only performed during your production builds on your CI pipeline
                   disableUpload: <boolean>
               }
             }),
         ]
     }

4. Verify that whenever you build your application, its minified files are automatically injected with the sourceMapId property, and that its source maps are automatically uploaded to Splunk RUM.

(Optional) Add the sourcesContent property to your source map

You can add the sourcesContent property to your source map files so that Splunk RUM can pull and display the code snippet that contributed to each JavaScript error. To add this property, configure your bundler tool to generate source maps that have this property. Alternatively, if you don't want Splunk RUM to have your source code, configure your bundler tool to generate source maps that omit this property.

Deploy the injected JavaScript files to your production environment

Once you've uploaded your application's source maps and deployed its injected minified files to your production environment, Splunk RUM automatically converts this application's stack traces into human-readable form.