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 new file mode 100644 index 0000000000000..2d4033d2439e3 Binary files /dev/null and b/src/platform-includes/sourcemaps/artifact-and-release-bundles/artifact-bundles.png differ diff --git a/src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx b/src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx new file mode 100644 index 0000000000000..d402259d60db5 --- /dev/null +++ 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. + + + +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). + + + +### 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 new file mode 100644 index 0000000000000..526ffd3794d1b Binary files /dev/null and b/src/platform-includes/sourcemaps/artifact-and-release-bundles/release-bundles.png differ diff --git a/src/platform-includes/sourcemaps/overview/javascript.mdx b/src/platform-includes/sourcemaps/overview/javascript.mdx index bc95354c1fecf..615c7f14ec608 100644 --- 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 +## 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, visit this page to understand how Artifact Bundles address the headaches that can come with using Release Bundles. + diff --git a/src/platform-includes/sourcemaps/primer/javascript.mdx b/src/platform-includes/sourcemaps/primer/javascript.mdx index 253e41ae5b743..c11f9402b2629 100644 --- 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 index 821c1c0d4207f..0eee19fde961b 100644 --- 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 index 25655857c0913..337613a8b52b5 100644 --- 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: -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). @@ -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 -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. diff --git a/src/platforms/javascript/common/sourcemaps/artifact-and-release-bundles.mdx b/src/platforms/javascript/common/sourcemaps/artifact-and-release-bundles.mdx new file mode 100644 index 0000000000000..dcbeb3237bb02 --- /dev/null +++ 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 +--- + + diff --git a/src/platforms/javascript/common/sourcemaps/validating.mdx b/src/platforms/javascript/common/sourcemaps/validating.mdx index ac04356ade596..ec76da0c75ee3 100644 --- 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 ---