feat(js): Document onlyIncludeInstrumentedModules option

Author: timfish

docs/platforms/javascript/common/install/esm.mdx

@@ -49,18 +49,43 @@ 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.
+
+If `import-in-the-middle` encounters problems wrapping a package, you may see
+syntax errors at runtime or logged errors in your console:
+```
+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'
+```
+
+You can confirm that these errors are caused by `import-in-the-middle` by
+disabling it by setting `registerEsmLoaderHooks` to false. Note, this will also
+disable tracing instrumentation: 
+
+```javascript {tabTitle:ESM} {filename: instrument.mjs}
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  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}
 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
   },
 });
 ```

docs/platforms/javascript/common/troubleshooting/index.mdx

@@ -82,6 +82,15 @@ To fix this, change the `tracePropagationTargets` option during SDK initializati
 </Expandable>
 </PlatformCategorySection>
 
+<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 [ESM troubleshooting section](/platforms/javascript/guides/node/install/esm/#troubleshooting-instrumentation) for more information.
+</Expandable>
+
 <PlatformCategorySection supported={['browser']}>
 <Expandable permalink title="`instrument.js` Line Numbers for Console Log statements">