feat(sourcemaps): Add more sourcemaps docs (#6667)

* feat(sourcemaps): Add more sourcemaps docs * Improve docs * Improve docs * Add new diagram * Improve docs * Improve docs * Update src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/upload/cli/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/upload/cli/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/upload/cli/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Update src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx Co-authored-by: Liza Mock <liza.mock@sentry.io> * Added: Diagrams * Modified: Index to include link to page * Removed: Screenshot from source map index --------- Co-authored-by: Jesse Box <me@jessebox.net> Co-authored-by: Liza Mock <liza.mock@sentry.io>
getsentry · Apr 21, 2023 · b22f4be · b22f4be · vercel · Apr 21, 2023
1 parent 2971674
commit b22f4be
Show file tree

Hide file tree

Showing 9 changed files with 73 additions and 12 deletions.
diff --git a/src/platform-includes/sourcemaps/artifact-and-release-bundles/artifact-bundles.png b/src/platform-includes/sourcemaps/artifact-and-release-bundles/artifact-bundles.png
diff --git a/src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx b/src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx
@@ -0,0 +1,56 @@
+This article explains the difference between Artifact and Release bundles, and the implications of using them. Visit [Uploading Source Maps](/platforms/javascript/guides/react/sourcemaps/uploading/) if you're looking for our guides on how to upload source maps.
+
+## Introduction
+
+Sentry currently supports two methods of uploading sourcemaps: **Release bundles** and **Artifact bundles**. A bundle contains all the minified sources and source maps (known as _artifacts_) required for Sentry to unminify the frames of a stack trace.
+
+## Release Bundles
+
+A release bundle is a bundle format that's connected to an existing `release` in Sentry. That's why you **have to create a `release`** before uploading your artifacts.
+
+| Pros                                    | Cons                                                                                              |
+| :-------------------------------------- | :------------------------------------------------------------------------------------------------ |
+| Currently works with every SDK version. | Configuring your build pipeline to upload artifacts can be very challenging.                      |
+|                                         | Requires your project to use Sentry Releases.                                                     |
+|                                         | **In the near future, our bundler plugins and `sentry-cli` will use artifact bundles by default** |
+
+### How Do They Work?
+
+![How Release Bundles Work](release-bundles.png)
+
+Release bundles get their name from using a `release` as a way to index a specific bundle. The `release` is extracted from an incoming error and used to look up the most recent bundle. When a bundle is found, we use the value of `abs_path` in each frame to find the corresponding minified source in the retrieved bundle. Once the minified source is found, we try to discover its source map with a series of heuristics, such as looking at the value of `sourceURLMapping`.
+
+Based on user feedback, we've found that using a stack frames `abs_path` to find its relevant artifacts to be **very unreliable**. Dynamic paths (For example: `https://www.site.com/{some_value}/scripts/script.js`) will likely require addition SDK configuration to unminify stack frames.
+
+## Artifact Bundles
+
+An artifact bundle is our new format that addresses the shortcomings of release bundles by **adding support for Debug IDs** and **removing the need to create a `release`**.
+
+| Pros                                                                                    | Cons                                                                                                                                                           |
+| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| With Debug IDs, configuring your build pipeline to upload artifacts is straightforward. | **Requires you to update the version of our Javascript SDK and bundler plugin ( or `sentry-cli`).**                                                            |
+| Associating a release is still possible, but not required.                              | May cause problems if your application relies on [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) checks . |
+
+### How Do They Work?
+
+![How Release Bundles Work](artifact-bundles.png)
+
+Artifact Bundles solve the challenge of matching paths by using a new identification mechanism known as Debug IDs. Rather than relying on paths we uniquely identify and bind pairs of minified sources and source maps with an Debug ID (UUID). With this, we are able to quickly identify the minified source and corresponding source map without ever needing to check any paths.
+
+<Note>
+
+If you want to learn more about the rationale behind Debug IDs, we suggest taking a look at our [engineering blog](https://sentry.engineering/blog/the-case-for-debug-ids).
+
+</Note>
+
+### Associating a Release with Artifact Bundles
+
+Since you might still want to know which `release` a specific artifact bundle is connected to, we came up with a new way to still connect your bundle to a `release`.
+
+Artifact Bundles support a new kind of association to a `release` (and `dist`), known as a "weak association". In practice, this **doesn't require the creation of a `release`** before uploading source maps, allowing the creation of a `release` as a separate step down the pipeline.
+
+With an associated `release` and optionally `dist` you will be able to quickly go to the Artifact Bundle from your `release` in Sentry, without having to worry about which artifact bundle was used for your errors.
+
+## Summary
+
+If you've had trouble uploading source maps in the past, we recommend you try artifact bundles with Debug IDs, but if your application already uses them successfully, we recommend you continue to use release bundles .
diff --git a/src/platform-includes/sourcemaps/artifact-and-release-bundles/release-bundles.png b/src/platform-includes/sourcemaps/artifact-and-release-bundles/release-bundles.png
diff --git a/src/platform-includes/sourcemaps/overview/javascript.mdx b/src/platform-includes/sourcemaps/overview/javascript.mdx
@@ -1,4 +1,4 @@
-## Uploading Source Maps to Sentry
+## Uploading Source Maps
 
 We've compiled a list of guides on how to upload source maps to Sentry for the most popular JavaScript build tools:
 
@@ -23,4 +23,8 @@ Though we strongly recommend uploading source maps as part of your build process
 
 </Note>
 
+## Artifact vs Release Bundles
+
+A bundle is how Sentry stores and uses your source maps to un-minify the stack traces of incoming errors. With our new bundle format being recently released, <PlatformLink to="/sourcemaps/artifact-and-release-bundles">visit this page</PlatformLink> to understand how Artifact Bundles address the headaches that can come with using Release Bundles.
+
 </PlatformSection>
diff --git a/src/platform-includes/sourcemaps/primer/javascript.mdx b/src/platform-includes/sourcemaps/primer/javascript.mdx
@@ -1,3 +1 @@
 To enable readable stack traces in your Sentry errors, you need to upload your source maps to Sentry.
-
-![Minified stack trace vs. readable stack trace](readable-stacktraces.png)
diff --git a/src/platform-includes/sourcemaps/primer/javascript.nextjs.mdx b/src/platform-includes/sourcemaps/primer/javascript.nextjs.mdx
@@ -1,5 +1,3 @@
 `@sentry/nextjs` will generate and upload source maps automatically, in order to enable errors to have readable stacktraces.
 
 To upload source maps, the `@sentry/nextjs` SDK uses the [Sentry Webpack Plugin](https://github.com/getsentry/sentry-webpack-plugin) under the hood. See the [Manual Configuration](../manual-setup/#configure-source-maps) page and the Sentry [Webpack Plugin documentation](https://github.com/getsentry/sentry-webpack-plugin#cli-configuration) for more details. If you are using Vercel, then you can also use the [Vercel integration](/product/integrations/deployment/vercel/) to upload source maps during deployments automatically.
-
-![Minified stack trace vs. readable stack trace](readable-stacktraces.png)
diff --git a/src/platform-includes/sourcemaps/upload/cli/javascript.mdx b/src/platform-includes/sourcemaps/upload/cli/javascript.mdx
@@ -49,9 +49,7 @@ Uploading artifact bundles requires:
 
 </Note>
 
-If you decide to upload as an artifact bundle you should use Debug IDs. Debug IDs are unique identifiers generated by the `sentry-cli` that bind together minified sources and their respective source maps. Each pair of `(minified source, source map)` contain the same Debug ID, which is injected into specific parts of each file.
-
-The generated Debug IDs are used by Sentry during processing to determine which source map file should be used to symbolicate an event's stackframes.
+If you decide to upload source maps as an artifact bundle, you should use Debug IDs, which are described in detail in [artifact bundles vs. release bundles](ADD LINK).
 
 <Note>
 
@@ -81,7 +79,7 @@ module.exports = {
 
 ### 2. Inject Debug IDs Into Artifacts
 
-During injection, `sentry-cli` will evaluate all minified sources and respective source maps (known as build artifacts), adding the Debug IDs required to correctly symbolicate an event.
+During injection, `sentry-cli` will evaluate all minified sources and respective source maps (known as build artifacts), adding the Debug IDs required to correctly unminify an event.
 
 To inject Debug IDs, use the new `inject` command:
 
@@ -129,7 +127,7 @@ Open up Sentry and navigate to **Project Settings > Source Maps**. If you choose
 
 #### Associating `release` with Artifact Bundle (Optional)
 
-If you are having troubles with Debug IDs, we suggest that you associate a release to an artifact bundle. _The release association will help Sentry figure out which artifact bundle(s) to use for symbolication when Debug IDs are not present._
+If you're having trouble with Debug IDs, we suggest that you associate a release with an artifact bundle. _The release association will help Sentry figure out which artifact bundle(s) to use for unminification when Debug IDs are not present._
 
 First, you must provide a `release` property in your SDK options.
 
@@ -177,7 +175,7 @@ Sentry can also use [releases](/product/releases/) to match uploaded source maps
 
 <Note>
 
-We strongly suggest to use the new Debug IDs system for uploading your artifacts since it provides more reliable symbolication and the old release-based system will be faded out in the future.
+We strongly suggest that you use the new Debug ID system for uploading your artifacts since it provides more reliable unminification and the old release-based system will be faded out in the future.
 
 </Note>
 

diff --git a/src/platforms/javascript/common/sourcemaps/artifact-and-release-bundles.mdx b/src/platforms/javascript/common/sourcemaps/artifact-and-release-bundles.mdx
@@ -0,0 +1,7 @@
+---
+title: Artifact vs. Release Bundles
+description: "Learn about the differences between artifact bundles and release bundles."
+sidebar_order: 6
+---
+
+<PlatformContent includePath="sourcemaps/artifact-and-release-bundles" />
diff --git a/src/platforms/javascript/common/sourcemaps/validating.mdx b/src/platforms/javascript/common/sourcemaps/validating.mdx
@@ -1,7 +1,7 @@
 ---
 title: Validating Files
 description: "Learn about Sentry's online validation tool that can be used to test your source maps against your hosted source."
-sidebar_order: 6
+sidebar_order: 3
 ---
 
 <PlatformContent includePath="sourcemaps/validating" />