Set up JavaScript source mapping 🔗
This page explains how to set up JavaScript source mapping, which allows Splunk RUM to convert stack frames from browser application errors back into a human-readable form so that you can see the exact line of source code related to an error.
Setting up JavaScript source mapping involves these steps:
(Optional) Adding the
sourcesContentproperty to the source maps that are generated by your build tool.Injecting a code snippet into your minified files using either the
splunk-rumCLI or the Splunk Webpack build plugin.Uploading your source maps to Splunk RUM.
Deploying your minified files to your production environment.
注釈
Splunk recommends that you follow the steps on this page to upload your source maps to Splunk RUM before you distribute corresponding binaries. To ensure this, the best practice is to integrate these steps into your CI pipeline so that whenever you build your application, your pipeline automatically uploads the corresponding source maps to Splunk RUM. Alternatively, you can upload source maps on demand.
Splunk RUM stores your source maps permanently. You cannot delete them from Splunk RUM at this time.
前提条件 🔗
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.
Option 1: Use the splunk-rum CLI 🔗
Set up your build environment:
Verify that your production build tool is configured to generate source maps.
Run the production build for your project.
Verify that your production bundles and source maps were written to the same output directory:
For example, if the output directory was
./dist, runls distand verify that both the.jsand.js.mapfiles were created:$ ls ./dist mainBundle.js mainBundle.js.map
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>
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 Splunk ブラウザ RUM インストルメンテーションを設定する.注釈
If you didn’t set the
SPLUNK_REALMandSPLUNK_ACCESS_TOKENenvironment 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>
構文 🔗
splunk-rum [command] [parameters]
Command descriptions 🔗
Command |
説明 |
|---|---|
|
Search Parameters:
|
|
Recursively search Run this command after you run the Parameters:
|
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.
Add the Splunk RUM Webpack plugin to your
package.jsonas a dev dependency:npm install @splunk/rum-build-plugins --save-dev
Configure your
webpack.config.jsto generate source maps. See Devtool | webpack.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 Splunk ブラウザ RUM インストルメンテーションを設定する.If you don’t want source maps to be uploaded while you’re doing local builds for your own local development, set
disableUploadto 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> } }), ] }
Verify that whenever you build your application, its minified files are automatically injected with the
sourceMapIdproperty, 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.
注釈
Make sure that the source maps that you upload to Splunk RUM match the minified files you deploy to production. To ensure this, the best practice is to integrate the splunk-rum commands into your build pipeline so that whenever you build an application, you also re-upload its source maps.