|
| 1 | +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. |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +## Release Bundles |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +| Pros | Cons | |
| 12 | +| :-------------------------------------- | :------------------------------------------------------------------------------------------------ | |
| 13 | +| Currently works with every SDK version. | Configuring your build pipeline to upload artifacts can be very challenging. | |
| 14 | +| | Requires your project to use Sentry Releases. | |
| 15 | +| | **In the near future, our bundler plugins and `sentry-cli` will use artifact bundles by default** | |
| 16 | + |
| 17 | +### How Do They Work? |
| 18 | + |
| 19 | + |
| 20 | + |
| 21 | +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`. |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +## Artifact Bundles |
| 26 | + |
| 27 | +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`**. |
| 28 | + |
| 29 | +| Pros | Cons | |
| 30 | +| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 31 | +| 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`).** | |
| 32 | +| 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 . | |
| 33 | + |
| 34 | +### How Do They Work? |
| 35 | + |
| 36 | + |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +<Note> |
| 41 | + |
| 42 | +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). |
| 43 | + |
| 44 | +</Note> |
| 45 | + |
| 46 | +### Associating a Release with Artifact Bundles |
| 47 | + |
| 48 | +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`. |
| 49 | + |
| 50 | +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. |
| 51 | + |
| 52 | +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. |
| 53 | + |
| 54 | +## Summary |
| 55 | + |
| 56 | +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 . |
0 commit comments