-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(sourcemaps): Add more sourcemaps docs #6667
Merged
Merged
Changes from all commits
Commits
Show all changes
20 commits
Select commit
Hold shift + click to select a range
704c5fc
feat(sourcemaps): Add more sourcemaps docs
iambriccardo 84f9c74
Improve docs
iambriccardo ea737be
Improve docs
iambriccardo 37bbb7e
Add new diagram
iambriccardo 9c9ca83
Improve docs
iambriccardo 4327abe
Improve docs
iambriccardo 4213a2a
Update src/platform-includes/sourcemaps/artifact-and-release-bundles/…
Jesse-Box e3c968e
Update src/platform-includes/sourcemaps/artifact-and-release-bundles/…
Jesse-Box e934c4e
Update src/platform-includes/sourcemaps/artifact-and-release-bundles/…
Jesse-Box 97a8fdc
Update src/platform-includes/sourcemaps/artifact-and-release-bundles/…
Jesse-Box c6d649a
Update src/platform-includes/sourcemaps/artifact-and-release-bundles/…
Jesse-Box a6eea1e
Update src/platform-includes/sourcemaps/artifact-and-release-bundles/…
Jesse-Box 3424661
Update src/platform-includes/sourcemaps/upload/cli/javascript.mdx
Jesse-Box 3221912
Update src/platform-includes/sourcemaps/upload/cli/javascript.mdx
Jesse-Box b4821b8
Update src/platform-includes/sourcemaps/upload/cli/javascript.mdx
Jesse-Box 802c425
Update src/platform-includes/sourcemaps/artifact-and-release-bundles/…
Jesse-Box 078933e
Added: Diagrams
Jesse-Box 4bb43c8
Modified: Index to include link to page
Jesse-Box a171978
Removed: Screenshot from source map index
Jesse-Box 75457f1
Merge branch 'master' into riccardo/feat/improve-sourcemaps-docs
Jesse-Box File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Binary file added
BIN
+58.2 KB
src/platform-includes/sourcemaps/artifact-and-release-bundles/artifact-bundles.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
56 changes: 56 additions & 0 deletions
56
src/platform-includes/sourcemaps/artifact-and-release-bundles/javascript.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 . |
Binary file added
BIN
+57.9 KB
src/platform-includes/sourcemaps/artifact-and-release-bundles/release-bundles.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
2 changes: 0 additions & 2 deletions
2
src/platform-includes/sourcemaps/primer/javascript.nextjs.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
7 changes: 7 additions & 0 deletions
7
src/platforms/javascript/common/sourcemaps/artifact-and-release-bundles.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" /> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" /> |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.