From 97897208997c9dc9d186b77c57c0d8cc1c343c6f Mon Sep 17 00:00:00 2001 From: Rick Foster Date: Thu, 14 Sep 2023 15:54:07 -0700 Subject: [PATCH 1/4] Improve instruction for creating an upload URL --- docs/error-reporting/platform-integrations/source-map.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/error-reporting/platform-integrations/source-map.md b/docs/error-reporting/platform-integrations/source-map.md index 877c3aa330..aae3da57cb 100644 --- a/docs/error-reporting/platform-integrations/source-map.md +++ b/docs/error-reporting/platform-integrations/source-map.md @@ -14,8 +14,7 @@ The following steps guide you through configuring your JavaScript application to ## What You'll Need - A Backtrace account ([log in](https://backtrace.io/login) or sign up for a [free trial license](https://backtrace.io/sign-up)). -- Your subdomain name (used to connect to your Backtrace instance). For example, `https://example-subdomain.sp.backtrace.io`. -- [Symbol submission token and URL](/error-reporting/project-setup/submission-url) +- A symbol submission URL with a `symbol:post` token for the `sourcemap` endpoint. [(Detailed instructions)](/error-reporting/project-setup/submission-url) ## Creating and Uploading Source Maps @@ -84,7 +83,10 @@ You can also use `npx` and skip adding the dependency: Replace `OUTPUT_DIRECTORY` with the path to the directory where your transpiled scripts are stored. -Replace `UPLOAD_OPTIONS` with `--url `, obtained from [the symbol submission URL](#acquire-a-symbol-submission-token-and-url). +Replace `UPLOAD_OPTIONS` with `--url `. +:::tip +Follow [(these instructions)](/error-reporting/project-setup/submission-url) to create a symbol submission URL with a `symbol:post` token for the `sourcemap` endpoint. +::: ### Configuration File From fc927708697937d5df9749a1b0f95fc5e875ab12 Mon Sep 17 00:00:00 2001 From: Rick Foster Date: Wed, 20 Sep 2023 15:28:02 -0700 Subject: [PATCH 2/4] Update source map instructions to use config file --- .../platform-integrations/source-map.md | 135 ++++++++++++------ 1 file changed, 90 insertions(+), 45 deletions(-) diff --git a/docs/error-reporting/platform-integrations/source-map.md b/docs/error-reporting/platform-integrations/source-map.md index aae3da57cb..f4cac00d7e 100644 --- a/docs/error-reporting/platform-integrations/source-map.md +++ b/docs/error-reporting/platform-integrations/source-map.md @@ -14,11 +14,22 @@ The following steps guide you through configuring your JavaScript application to ## What You'll Need - A Backtrace account ([log in](https://backtrace.io/login) or sign up for a [free trial license](https://backtrace.io/sign-up)). -- A symbol submission URL with a `symbol:post` token for the `sourcemap` endpoint. [(Detailed instructions)](/error-reporting/project-setup/submission-url) +- A symbol submission URL with a `symbol:post` token for the `sourcemap` endpoint. [<detailed instructions>](/error-reporting/project-setup/submission-url) ## Creating and Uploading Source Maps -**Step 1: Enable Source Maps for Your Application** +Follow these steps to create and upload source maps with every build of your application: +1. [Enable source maps](#step-1-enable-source-maps-for-your-application) +1. [Install the `backtrace-js` command line tool](#step-2-install-backtrace-js) +1. [Create a configuration file for `backtrace-js`](#step-3-create-a-backtracejsrc-configuration-file) + + +### Step 1: Enable Source Maps for Your Application +:::warning +- Under what conditions are source maps not already enabled? +- Are normal customers completely familiar with source maps, and know whether or not they are produced? +- This is all to ask: Can a user skip this step? Which users can? +::: -**Step 2: Configure @backtrace-labs/javascript-cli** +--- +### Step 2: Install `backtrace-js` + +Install the `backtrace-js` command line tool and update your build scripts to run it. `backtrace-js` can be run from the command line, but it is most efficient to use a configuration file which we will create in the next step. 1. Install `@backtrace-labs/javascript-cli` as a dev dependency: ```bash - npm install --save-dev @backtrace-labs/javascript-cli + npm install -g --save-dev @backtrace-labs/javascript-cli ``` -2. Add the following scripts to your `package.json` file: +2. Add the following script to `package.json` to process and upload source maps: ```json "scripts": { - "backtrace:process": "backtrace-js process OUTPUT_DIRECTORY", - "backtrace:upload": "backtrace-js upload OUTPUT_DIRECTORY UPLOAD_OPTIONS" + // highlight-next-line + "backtrace:sourcemap": "backtrace-js run", } ``` -You can also use `npx` and skip adding the dependency: - -```json -"scripts": { - "backtrace:process": "npx --package @backtrace-labs/javascript-cli backtrace-js process OUTPUT_DIRECTORY", - "backtrace:upload": "npx --package @backtrace-labs/javascript-cli backtrace-js upload OUTPUT_DIRECTORY UPLOAD_OPTIONS" -} -``` - -Replace `OUTPUT_DIRECTORY` with the path to the directory where your transpiled scripts are stored. +3. Update the build step in `package.json` to process and upload source maps with every build: -Replace `UPLOAD_OPTIONS` with `--url `. -:::tip -Follow [(these instructions)](/error-reporting/project-setup/submission-url) to create a symbol submission URL with a `symbol:post` token for the `sourcemap` endpoint. -::: + ```json + "scripts": { + // highlight-next-line + "build": " && npm run backtrace:sourcemap" + } + ``` -### Configuration File +--- +### Step 3: Create a `.backtracejsrc` configuration file -Instead of providing options in script argument lines, you can configure them in the `.backtracejsrc` configuration file: +Create a `.backtracejs` file in the root of your project. -```jsonc +```json { - "path": "OUTPUT_DIRECTORY", - "upload": { - "url": "your upload URL" - } + // highlight-next-line + "path": "", + "run": { + "process": true, + "add-sources": true, + "upload": true + }, + "upload": { + // highlight-next-line + "url": "", + "include-sources": true + } } ``` -For more details, consult `@backtrace-labs/javascript-cli` [README](https://github.com/backtrace-labs/backtrace-javascript/blob/main/tools/cli/README.md). - -**Step 3: Set Up Automatic Processing and Upload** - -To process and upload your artifacts, you must first run `npm run backtrace:process` and then `npm run backtrace:upload`. +- Replace `` with the path to the directory where your transpiled scripts are stored. +- Follow [<these instructions>](/error-reporting/project-setup/submission-url) to create the `` with a `symbol:post` token for the `sourcemap` endpoint. + +See `backtrace-js --help` or go to [`@backtrace-labs/javascript-cli`](https://github.com/backtrace-labs/backtrace-javascript/blob/dev/tools/cli) for additional command line and configuration options. + +:::note Troubleshooting + Source map processing will halt on error with a description. Use a --verbose command line switch to output extended information for troubleshooting. + + __File processing errors__ + + File processing may halt on a specific file for valid reasons. For instance, a source map may not produced for a script file. Processing for such a file can be skipped with an exclude object in `.backtracejsrc` + + ```json + { + "path": "", + // highlight-start + "exclude": [ + // highlight-next-line + "./app1/build/static/js/file.chunk.js" + ] + // highlight-end + "run": { + ... + } +``` -To ensure that this is done automatically, you can add these commands to your production script: + Alternatively, all processing errors can be treated as warnings or other errors levels. + ```json + { + "path": "", + // highlight-start + "asset-error-behavior": "warn", + // highlight-end + "run": { + ... + } + ``` -```json -"scripts": { - "build": "my current build command && npm run backtrace:process && npm run backtrace:upload" -} -``` +::: ## Project Bundlers +:::warning +Can we provide text that says this is only necessary if you use a project bundler? +::: Date: Thu, 21 Sep 2023 08:01:04 -0700 Subject: [PATCH 3/4] Remove global flag for plugin installation --- docs/error-reporting/platform-integrations/source-map.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/error-reporting/platform-integrations/source-map.md b/docs/error-reporting/platform-integrations/source-map.md index f4cac00d7e..e1f40228d6 100644 --- a/docs/error-reporting/platform-integrations/source-map.md +++ b/docs/error-reporting/platform-integrations/source-map.md @@ -193,7 +193,7 @@ If you're using code transpiler plugins (such as Typescript), be sure to enable 1. Install `@backtrace-labs/webpack-plugin` as a developer dependency: ```bash - npm install -g --save-dev @backtrace-labs/webpack-plugin + npm install --save-dev @backtrace-labs/webpack-plugin ``` 2. Add it to your `plugins` array in `webpack.config.js`: @@ -237,7 +237,7 @@ If you're using code transpiler plugins (such as Typescript), be sure to enable 1. Install `@backtrace-labs/rollup-plugin` as a developer dependency: ```bash - npm install -g --save-dev @backtrace-labs/rollup-plugin + npm install --save-dev @backtrace-labs/rollup-plugin ``` 2. Add it to your `plugins` array in `rollup.config.js`: @@ -281,7 +281,7 @@ If you're using code transpiler plugins (such as Typescript), be sure to enable 1. Install `@backtrace-labs/vite-plugin` as a developer dependency: ```bash - npm install -g --save-dev @backtrace-labs/vite-plugin + npm install --save-dev @backtrace-labs/vite-plugin ``` 2. Add it to your `plugins` array in `vite.config.js`: From b78a8639824a369c67c160c210804fcd4bb9e2ba Mon Sep 17 00:00:00 2001 From: Rick Foster Date: Thu, 21 Sep 2023 12:06:41 -0700 Subject: [PATCH 4/4] Provide alt path for integrating source code. --- .../platform-integrations/source-map.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/error-reporting/platform-integrations/source-map.md b/docs/error-reporting/platform-integrations/source-map.md index e1f40228d6..260ed77c91 100644 --- a/docs/error-reporting/platform-integrations/source-map.md +++ b/docs/error-reporting/platform-integrations/source-map.md @@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import useBaseUrl from '@docusaurus/useBaseUrl'; -The following steps guide you through configuring your JavaScript application to automatically upload sourcemap files during the project build. +The Backtrace debugger can highlight specific lines in your source code associated with frames in the callstack. This powerful capability can be enabled by uploading source and source maps. The following steps guide you through configuring your JavaScript application to automatically upload sourcemap files during the project build. ## What You'll Need @@ -25,11 +25,8 @@ Follow these steps to create and upload source maps with every build of your app ### Step 1: Enable Source Maps for Your Application -:::warning -- Under what conditions are source maps not already enabled? -- Are normal customers completely familiar with source maps, and know whether or not they are produced? -- This is all to ask: Can a user skip this step? Which users can? -::: + +Source maps are automatically generated with most JavaScript frameworks. Please follow these instructions if you are using a framework that does not automatically generate source maps. ` with the path to the directory where your transpiled scripts are stored. - Follow [<these instructions>](/error-reporting/project-setup/submission-url) to create the `` with a `symbol:post` token for the `sourcemap` endpoint. +:::info Source Code Upload + Source files can be embedded in source maps and included in the upload to Backtrace. The configuration above is constructed to do this. + + Alternatively, if you do not wish to upload source files directly to Backtrace, you can integrate your source repository. To do so, omit `add-sources` and `include-sources` and follow the steps in the [Source Code](../../project-setup/source-code/) document. +::: + See `backtrace-js --help` or go to [`@backtrace-labs/javascript-cli`](https://github.com/backtrace-labs/backtrace-javascript/blob/dev/tools/cli) for additional command line and configuration options. :::note Troubleshooting @@ -158,9 +161,6 @@ See `backtrace-js --help` or go to [`@backtrace-labs/javascript-cli`](https://gi ::: ## Project Bundlers -:::warning -Can we provide text that says this is only necessary if you use a project bundler? -:::