From e6ebed4bd6ffb4b2e088ac71207bf21e1b8c9106 Mon Sep 17 00:00:00 2001
From: Tim Fish <tim@timfish.uk>
Date: Thu, 31 Oct 2024 15:23:26 +0100
Subject: [PATCH] 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 <alexanderkrawiec@gmail.com>

* jeez

---------

Co-authored-by: Luca Forstner <luca.forstner@sentry.io>
Co-authored-by: Alex Krawiec <alexanderkrawiec@gmail.com>
---
 .../javascript/common/install/esm.mdx         | 36 +++++++++++++++----
 .../common/troubleshooting/index.mdx          | 16 ++++++++-
 2 files changed, 45 insertions(+), 7 deletions(-)

diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx
index d93658a9219e4..d8d8ceea8b970 100644
--- 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
index 754dc838a074f..d938566e980ed 100644
--- 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">