feat(js): Document onlyIncludeInstrumentedModules option (#11632)

* feat(js): Document `onlyIncludeInstrumentedModules` option * Fix links and dont show in browser * cleanup * only show for relevant platforms * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> * jeez --------- Co-authored-by: Luca Forstner <[email protected]> Co-authored-by: Alex Krawiec <[email protected]>
getsentry · Oct 31, 2024 · e6ebed4 · e6ebed4
1 parent d8130fd
commit e6ebed4
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 7 deletions.
diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx
@@ -49,18 +49,42 @@ NODE_OPTIONS="--import ./instrument.mjs" npm run start
 
 We do not support ESM in Node versions before 18.19.0.
 
-## Skipping instrumentation
+## Troubleshooting instrumentation
 
-By default, all packages are wrapped under the hood by [import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle). If you run into a problem with a package, you can skip instrumentation for it by configuring `registerEsmLoaderHooks` in your `Sentry.init()` config:
+By default, all packages are wrapped under the hood by
+[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to
+aid instrumenting them.
 
-```javascript {tabTitle:ESM} {filename: instrument.mjs}
+If `import-in-the-middle` encounters problems wrapping a package, you may see
+syntax errors at runtime or logged errors in your console:
+
+```logs
+SyntaxError: The requested module '...' does not provide an export named '...'
+(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js'
+```
+
+To confirm that these errors are caused by `import-in-the-middle`,
+disable it by setting `registerEsmLoaderHooks` to false. Note, this will also
+disable tracing instrumentation:
+
+```javascript {tabTitle:ESM} {filename: instrument.mjs} {4}
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  registerEsmLoaderHooks: false,
+});
+```
+
+If you are starting Sentry via `--import`, you can instruct `import-in-the-middle`
+to only wrap packages that Sentry specifically instruments. To do this, you can
+set the `onlyIncludeInstrumentedModules` to `true`:
+
+```javascript {tabTitle:ESM} {filename: instrument.mjs} {4-6}
 import * as Sentry from "@sentry/node";
 
 Sentry.init({
-  dsn: "___PUBLIC_DSN___",
   registerEsmLoaderHooks: {
-    // Provide a list of package names to exclude from instrumentation
-    exclude: ["package-name"],
+    onlyIncludeInstrumentedModules: true,
   },
 });
 ```
diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx
@@ -77,11 +77,25 @@ Most community CDNs properly set an `Access-Control-Allow-Origin` header.
 
 If your application started to misbehave because of performing additional OPTIONS requests, it is most likely an issue with unwanted `sentry-trace` request headers, which can happen when you are using too generic a configuration for our Tracing Integration in the Browser SDK.
 
-To fix this, change the `tracePropagationTargets` option during SDK initialization. For more details, see [Automatic Instrumentation](/platforms/javascript/tracing/instrumentation/automatic-instrumentation/#tracePropagationTargets) in our Tracing documentation.
+To fix this, change the `tracePropagationTargets` option during SDK initialization. For more details, see <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/#tracePropagationTarget">Automatic Instrumentation</PlatformLink> in our Tracing documentation.
 
 </Expandable>
 </PlatformCategorySection>
 
+<PlatformCategorySection notSupported={['browser']}>
+<PlatformSection notSupported={['javascript.aws-lambda', 'javascript.azure-functions', 'javascript.bun', 'javascript.cloudflare', 'javascript.deno', 'javascript.electron', 'javascript.gcp-functions']}>
+<Expandable permalink title="Error: 'import-in-the-middle' failed to wrap">
+ When using ESM, by default all packages are wrapped under the hood by
+ [import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle).
+ `import-in-the-middle` has compatibility issues with some packages and
+ can throw errors in these situations.
+
+Check out the <PlatformLink to="/install/esm/#troubleshooting-instrumentation">ESM Troubleshooting Instrumentation</PlatformLink> section for more information.
+
+</Expandable>
+</PlatformSection>
+</PlatformCategorySection>
+
 <PlatformCategorySection supported={['browser']}>
 <Expandable permalink title="`instrument.js` Line Numbers for Console Log statements">