diff --git a/docs/concepts/migration/index.mdx b/docs/concepts/migration/index.mdx index 2a932f4f440065..cf73c48421b24b 100644 --- a/docs/concepts/migration/index.mdx +++ b/docs/concepts/migration/index.mdx @@ -48,7 +48,7 @@ Below is a non-exhaustive list of some items that will not be relocated: - Issues - Events - Replays and/or other [Event Attachments](/platforms/javascript/enriching-events/attachments/) -- Source Maps, [Debug Information Files](/cli/dif/) and/or [Artifact Bundles](/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/) +- Source Maps, [Debug Information Files](/cli/dif/) and/or [Debug IDs](/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/) - Release information, including any references to external repositories via specific Pull Requests - Deployment information - Custom Avatars diff --git a/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/artifact-bundles.mdx b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/artifact-bundles.mdx deleted file mode 100644 index af81df4daa5392..00000000000000 --- a/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/artifact-bundles.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: What are Artifact Bundles -description: "Learn about artifact bundles." -notSupported: - - javascript.capacitor - - javascript.cordova -sidebar_order: 6 ---- - - diff --git a/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/bad-stack-trace.png b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/bad-stack-trace.png new file mode 100644 index 00000000000000..c46df3b27f9b47 Binary files /dev/null and b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/bad-stack-trace.png differ diff --git a/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/debug-ids.png b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/debug-ids.png new file mode 100644 index 00000000000000..04612ac216deed Binary files /dev/null and b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/debug-ids.png differ diff --git a/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/good-stack-trace.png b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/good-stack-trace.png new file mode 100644 index 00000000000000..37c877711f7af8 Binary files /dev/null and b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/img/good-stack-trace.png differ diff --git a/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/index.mdx b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/index.mdx new file mode 100644 index 00000000000000..48548631b82cd1 --- /dev/null +++ b/docs/platforms/javascript/common/sourcemaps/troubleshooting_js/debug-ids/index.mdx @@ -0,0 +1,80 @@ +--- +title: What are Debug IDs +sidebar_order: 7 +--- + +This documentation provides an in-depth look at Debug IDs, explaining how they work and why Sentry recommends using them. Visit [Uploading Source Maps](https://docs.sentry.io/platforms/javascript/guides/react/sourcemaps/uploading/) if you're looking for our guides on how to upload source maps. + +## Introduction + +Modern web applications often use some kind of build process when using JavaScript. This build process takes some input JavaScript, transforms it in some way, then outputs JavaScript that is served alongside the website. Some example transformations include minifying JavaScript code (so the final JavaScript bundle is smaller and faster to load) or removing TypeScript types (only JavaScript can run on the browser). + +As a result, the JavaScript code running in production is typically not the same as the code written by the developer in the source editor. Instead, it has undergone several transformations, such as minification, transpilation, downcompilation, bundling, polyfilling, and others, aimed at improving performance and ensuring cross-browser compatibility. Some common tools that transform code in such ways are Babel, Vite, Webpack, Rollup, Terser, or SWC - which are often used by higher-level tools like Next.js, Nuxt, Create React App, and similar. + +Stack traces are essential to debug errors, but stack traces that come from generated JavaScript are often unreadable or unusable! They look nothing like the code you wrote and you can't connect them to your source code repository. + +To ensure Sentry (and other tools) can provide stack traces that are both readable and useful, you'll want to generate and use [source maps](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html). Source maps are additional pieces information (often stored as files) that map the transformed JavaScript back to the original code. This allows Sentry to associate the error with your original source, which means you’ll get stack traces that look like the code you wrote, not the code you generated. + +To connect source maps to a JavaScript file, we relied on filenames, but these often were unreliable. For example, when you changed the subpath of where your javascript files are served it would mean that the filenames no longer match and the corresponding sourcemap would not be able to be found by Sentry. + +`//# source mappingURL=http://example.com/path/to/your/source-map.js.map` + +Given the url-based filename approach was unreliable, we came up with [Debug IDs](/platforms/javascript/sourcemaps/debug-ids#what-are-debug-ids). + +## What are Debug IDs + +Inspired by approaches in native language ecosystems, Debug IDs are globally unique ids that identify a transformed JavaScript file and its associated source map. + +![Debug IDs example](./img/debug-ids.png) + +When using sentry-cli or Sentry plugins for Webpack, Vite, or Rollup, Debug IDs are deterministically generated based on the source file contents. Note that deterministic Debug IDs for esbuild are not currently supported. + +This approach is Sentry's recommended and most reliable method for associating minified JavaScript files with their original source code, making it easier to trace errors back to their source. Because debug IDs will generally change across releasess if the file content is changed **creating a release is no longer required**. Release names were previously used to disambiguate sourcemaps with the same name across deployments. + + + +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). + + + +## How Sentry uses Debug IDs + + + To use Debug IDs, ensure that you're using **Sentry's SDK version 7.47 or higher**. Once you're on a supported version, follow the steps outlined below: + + + For Debug IDs with Next.js, you’ll need **Sentry's SDK version 8.0.0 or higher**. Once you're on a supported version, follow the steps outlined below: + + + +1. **A globally unique Debug ID is generated**: During the build process, if you are using one of Sentry's Bundler Plugins or Sentry CLI a Debug ID is generated, which is globally unique and ideally deterministic. + +2. **Debug IDs are embedded in minified files**: Each minified JavaScript file includes a special comment, such as `//# debugId=DEBUG_ID`, where `DEBUG_ID` is the unique identifier generated in the previous step. + +3. **The same Debug ID is added to source maps**: Source maps also include the same Debug ID as a new attribute, linking the minified JavaScript file to its corresponding source map. + +4. **Stack traces in Sentry link the Debug ID**: When an error occurs, Sentry's event contains the Debug ID, which allows Sentry to automatically link the error to the correct source map. This ensures the stack trace is resolved back to the original source code, providing you with clearer and more accurate debugging information—even if the JavaScript has been minified or transformed. + +### Why use Debug IDs to uniminify your code? + +Unminifying your code is essential for effective debugging. While there are other [legacy ways](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/legacy-uploading-methods/) to achieve this at Sentry, using **Debug IDs are recommended by Sentry** as it is the most reliable method. By unminifying your code, you get much clearer stack traces when errors occur. Instead of seeing obfuscated code, you'll see the exact code you originally wrote, making it far easier to understand and resolve issues. Below are examples that demonstrates the difference: + +#### Bad Stack Trace +![bad stack trace example](./img/bad-stack-trace.png) + +#### Good Stack Trace +![good stack trace example](./img/good-stack-trace.png) + +## Retention Policy + +Artifacts including Debug IDs have a retention period of _90 days_, using a _time to idle_ expiration mechanism. +This means that uploaded Debug IDs are retained for as long as they are actively being used for event processing. +Once an ID has not been used to process incoming events for at least 90 days, it will automatically expire and be eligible for deletion. + +## Associating a Release with Debug IDs + +Since you might still want to know to which release an specific Debug ID is connected to, we designed a new way to still associate a `release` to your bundle. + +The new Debug ID format supports a new kind of association to a `release` and optionally `dist`, known as weak release association. This type of association **will not require the creation of a `release`** before uploading source maps and will consequently allow 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 Debug ID from your `release` in Sentry, without having to worry about which Debug ID was used for your errors. diff --git a/docs/platforms/javascript/common/sourcemaps/uploading/create-react-app.mdx b/docs/platforms/javascript/common/sourcemaps/uploading/create-react-app.mdx index d238045c8a0e19..5e559d6087884e 100644 --- a/docs/platforms/javascript/common/sourcemaps/uploading/create-react-app.mdx +++ b/docs/platforms/javascript/common/sourcemaps/uploading/create-react-app.mdx @@ -64,7 +64,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ### 3. Inject Debug IDs Into Build Artifacts Debug IDs are used to match the stack frame of an event with its corresponding minified source and source map file. -Visit [What are Artifact Bundles](/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/) if you want to learn more about Artifact Bundles and Debug IDs. +Visit [What are Debug IDs](/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/) if you want to learn more about Debug IDs. To inject Debug IDs, use the following command **every time after building your application**: diff --git a/docs/product/releases/setup/release-automation/github-actions/index.mdx b/docs/product/releases/setup/release-automation/github-actions/index.mdx index ecb34fdf4fd28d..5c47fd88df5323 100644 --- a/docs/product/releases/setup/release-automation/github-actions/index.mdx +++ b/docs/product/releases/setup/release-automation/github-actions/index.mdx @@ -56,7 +56,7 @@ If your application is written in JavaScript you probably deploy minified applic stack traces in your Sentry errors, you need to upload source maps to Sentry. Provide the path(s) to your source maps via the `sourcemaps` option to ensure proper un-minification of your stack traces. -Visit [What are Artifact Bundles](/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/) if you want to learn more. +Visit [What are Debug IDs](/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/) if you want to learn more. ```yml - uses: actions/checkout@v4 diff --git a/includes/sentry-cli-sourcemaps.mdx b/includes/sentry-cli-sourcemaps.mdx index ca74e2e2032ec8..a89cafd6c8e364 100644 --- a/includes/sentry-cli-sourcemaps.mdx +++ b/includes/sentry-cli-sourcemaps.mdx @@ -20,7 +20,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ### 3. Inject Debug IDs Into Artifacts -Debug IDs are used to match the stack frame of an event with its corresponding minified source and source map file. Visit [What are Artifact Bundles](/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/) if you want to learn more about Artifact Bundles and Debug IDs. +Debug IDs are used to match the stack frame of an event with its corresponding minified source and source map file. Visit [What are Debug IDs](/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/) if you want to learn more about Debug IDs. To inject Debug IDs, use the following command: diff --git a/platform-includes/migration/javascript-v8/important-changes/javascript.sveltekit.mdx b/platform-includes/migration/javascript-v8/important-changes/javascript.sveltekit.mdx index 08c33dbc6b2c81..3e3637749043fa 100644 --- a/platform-includes/migration/javascript-v8/important-changes/javascript.sveltekit.mdx +++ b/platform-includes/migration/javascript-v8/important-changes/javascript.sveltekit.mdx @@ -36,7 +36,7 @@ We now support the following integrations out of the box with 0 configuration: ### Breaking `sentrySvelteKit()` changes -Under the hood, the SvelteKit SDK uses [Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin) to upload sourcemaps and automatically associate add releases to your events. In `8.x`, the SDK now uses `2.x` of the Sentry Vite Plugin which brings many improvements and bug fixes. Sourcemaps uploading with the SvelteKit SDK now uses Debug IDs. +Under the hood, the SvelteKit SDK uses [Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin) to upload sourcemaps and automatically associate add releases to your events. In `8.x`, the SDK now uses `2.x` of the Sentry Vite Plugin which brings many improvements and bug fixes. Sourcemaps uploading with the SvelteKit SDK now uses Debug IDs. To allow future upgrades of the Vite plugin without breaking stable and public APIs in `sentrySvelteKit`, we modified the `sourceMapsUploadOptions` to remove the hard dependency on the API of the plugin. While you previously could specify all [version 0.x Vite plugin options](https://www.npmjs.com/package/@sentry/vite-plugin/v/0.6.1), we now reduced them to a subset of [2.x options](https://www.npmjs.com/package/@sentry/vite-plugin/v/2.14.2#options). diff --git a/platform-includes/migration/javascript-v8/other-changes/javascript.nextjs.mdx b/platform-includes/migration/javascript-v8/other-changes/javascript.nextjs.mdx index da966b2bb17f32..537b0cf49bcb37 100644 --- a/platform-includes/migration/javascript-v8/other-changes/javascript.nextjs.mdx +++ b/platform-includes/migration/javascript-v8/other-changes/javascript.nextjs.mdx @@ -1,6 +1,6 @@ ### Improved Source Map Uploading -Under the hood, the Next.js SDK uses [Sentry Webpack Plugin](https://www.npmjs.com/package/@sentry/webpack-plugin) to upload sourcemaps and automatically associate add releases to your events. In `8.x`, the SDK now uses `2.x` of the Sentry Webpack Plugin which brings many improvements and bug fixes. Sourcemaps uploading with the Next.js SDK now uses Debug IDs. +Under the hood, the Next.js SDK uses [Sentry Webpack Plugin](https://www.npmjs.com/package/@sentry/webpack-plugin) to upload sourcemaps and automatically associate add releases to your events. In `8.x`, the SDK now uses `2.x` of the Sentry Webpack Plugin which brings many improvements and bug fixes. Sourcemaps uploading with the Next.js SDK now uses Debug IDs. ### Removal of deprecated API diff --git a/platform-includes/sourcemaps/artifact-bundles/artifact-bundle.png b/platform-includes/sourcemaps/artifact-bundles/artifact-bundle.png deleted file mode 100644 index bc481b9b2c2f8a..00000000000000 Binary files a/platform-includes/sourcemaps/artifact-bundles/artifact-bundle.png and /dev/null differ diff --git a/platform-includes/sourcemaps/artifact-bundles/javascript.mdx b/platform-includes/sourcemaps/artifact-bundles/javascript.mdx deleted file mode 100644 index 1d17bc2ae258a2..00000000000000 --- a/platform-includes/sourcemaps/artifact-bundles/javascript.mdx +++ /dev/null @@ -1,36 +0,0 @@ -This article explains the inner workings of Artifact 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 uses **Artifact Bundles** for managing un-minification of your stack traces. A bundle, at a higher level, contains all the minified sources and source maps (known as _artifacts_) required for Sentry to unminify the frames of a stack trace. - -## Artifact Bundles - -An artifact bundle is our new bundle format that aims to address the shortcomings of the old Release Bundles by **adding the support for Debug IDs** and **removing the need to create a `release`**. - -![How Artifact Bundles Work](./artifact-bundle.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 a 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. Thus, you don't have to worry about wrong paths configurations. - -When using sentry-cli or the Webpack, Vite, or Rollup bundler plugins, Debug IDs are generated deterministically based on the source file contents. Deterministic Debug IDs for esbuild are currently not supported. - - - -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 to which release a specific artifact bundle is connected to, we designed a new way to still associate a `release` to your bundle. - -The new Artifact Bundle format supports a new kind of association to a `release` and optionally `dist`, known as weak release association. This type of association **will not require the creation of a `release`** before uploading sourcemaps and will consequently allow 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. - -## Retention Policy - -Artifact Bundles have a retention period of _90 days_, using a _time to idle_ expiration mechanism. -This means that uploaded artifact bundles are retained for as long as they are actively being used for event processing. -Once an artifact bundle has not been used to process incoming events for at least 90 days, -it will automatically expire and be eligible for deletion. diff --git a/platform-includes/sourcemaps/artifact-bundles/release-bundle.png b/platform-includes/sourcemaps/artifact-bundles/release-bundle.png deleted file mode 100644 index b3e779ca707c99..00000000000000 Binary files a/platform-includes/sourcemaps/artifact-bundles/release-bundle.png and /dev/null differ diff --git a/redirects.js b/redirects.js index 1650993b30a944..0692528231b048 100644 --- a/redirects.js +++ b/redirects.js @@ -585,6 +585,16 @@ const userDocsRedirects = [ '/platforms/:platform/guides/:guide/sourcemaps/:section(generating|validating|best-practices|artifact-and-release-bundles)/', destination: '/platforms/:platform/guides/:guide/sourcemaps/', }, + { + source: '/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/', + destination: '/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/', + }, + { + source: + '/platforms/:platform/guides/:guide/sourcemaps/troubleshooting_js/artifact-bundles/', + destination: + '/platforms/:platform/guides/:guide/sourcemaps/troubleshooting_js/debug-ids/', + }, { source: '/platforms/minidump/crashpad/:path*', destination: '/platforms/native/guides/crashpad/:path*', @@ -997,7 +1007,7 @@ const userDocsRedirects = [ source: '/platforms/php/:productfeature/troubleshooting/:path*', destination: '/platforms/php/troubleshooting/:path*', }, - { + { source: '/product/explore/feature-flags/:path*', destination: '/product/issues/issue-details/feature-flags/:path*', }, @@ -1009,14 +1019,16 @@ const userDocsRedirects = [ source: '/product/tracing/:path*', destination: '/concepts/key-terms/tracing/:path*', }, - // Redirects for JavaScript tracing docs + // Redirects for JavaScript tracing docs { source: '/platforms/javascript/tracing/trace-propagation/:path*', destination: '/platforms/javascript/tracing/distributed-tracing/:path*', }, { - source: '/platforms/javascript/guides/:guide/tracing/instrumentation/performance-metrics/', - destination: '/platforms/javascript/guides/:guide/tracing/span-metrics/performance-metrics/', + source: + '/platforms/javascript/guides/:guide/tracing/instrumentation/performance-metrics/', + destination: + '/platforms/javascript/guides/:guide/tracing/span-metrics/performance-metrics/', }, { source: '/platforms/javascript/guides/:guide/tracing/trace-propagation/:path*', @@ -1027,7 +1039,8 @@ const userDocsRedirects = [ destination: '/platforms/javascript/tracing/instrumentation/:path*', }, { - source: '/platforms/javascript/guides/:guide/tracing/instrumentation/custom-instrumentation/:path*', + source: + '/platforms/javascript/guides/:guide/tracing/instrumentation/custom-instrumentation/:path*', destination: '/platforms/javascript/guides/:guide/tracing/instrumentation/:path*', }, { @@ -1040,22 +1053,27 @@ const userDocsRedirects = [ }, { source: '/platforms/dart/guides/flutter/upload-debug/#when-to-upload', - destination: '/platforms/dart/guides/flutter/debug-symbols/#when-to-upload-debug-symbols', + destination: + '/platforms/dart/guides/flutter/debug-symbols/#when-to-upload-debug-symbols', }, { source: '/platforms/dart/guides/flutter/upload-debug/#source-context', - destination: '/platforms/dart/guides/flutter/debug-symbols/dart-plugin/#configuration', + destination: + '/platforms/dart/guides/flutter/debug-symbols/dart-plugin/#configuration', }, { - source: '/platforms/dart/guides/flutter/upload-debug/#uploading-source-code-context-for-flutter-android-ios-and-macos', + source: + '/platforms/dart/guides/flutter/upload-debug/#uploading-source-code-context-for-flutter-android-ios-and-macos', destination: '/platforms/dart/guides/flutter/debug-symbols/manual-upload/', }, { source: '/platforms/dart/guides/flutter/upload-debug/#uploading-for-android-ndk', - destination: '/platforms/dart/guides/flutter/debug-symbols/manual-upload/#android-ndk', + destination: + '/platforms/dart/guides/flutter/debug-symbols/manual-upload/#android-ndk', }, { - source: '/platforms/dart/guides/flutter/upload-debug/#automatically-upload-debug-symbols', + source: + '/platforms/dart/guides/flutter/upload-debug/#automatically-upload-debug-symbols', destination: '/dart/guides/flutter/debug-symbols/dart-plugin/', }, {