From 80197f0e3dfaf083ddee039c2edf6a0c22376c15 Mon Sep 17 00:00:00 2001 From: Tim Fish Date: Tue, 22 Oct 2024 17:37:25 +0200 Subject: [PATCH 1/6] feat(js): Document `onlyIncludeInstrumentedModules` option --- .../javascript/common/install/esm.mdx | 33 ++++++++++++++++--- .../common/troubleshooting/index.mdx | 9 +++++ 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index d93658a9219e4..77dcd39371e0b 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -49,9 +49,35 @@ 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"; @@ -59,8 +85,7 @@ 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 68ee3a0d753a6..6ecbc23985c2e 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -82,6 +82,15 @@ To fix this, change the `tracePropagationTargets` option during SDK initializati + + 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. + + From 19142c25601f6e92d8743f4b9f468b9182030bfd Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 23 Oct 2024 09:02:39 +0200 Subject: [PATCH 2/6] Fix links and dont show in browser --- docs/platforms/javascript/common/troubleshooting/index.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 6ecbc23985c2e..45a20a4817a8d 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -77,19 +77,22 @@ 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 Automatic Instrumentation in our Tracing documentation. + 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. +Check out the ESM Troubleshooting Instrumentation section for more information. + + From d561fa710f63fad923e836266a9f3c582afc0cca Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 23 Oct 2024 09:06:40 +0200 Subject: [PATCH 3/6] cleanup --- docs/platforms/javascript/common/install/esm.mdx | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index 77dcd39371e0b..5f12f0766bc2f 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -57,21 +57,21 @@ 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: -``` + +```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' ``` 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: +disable tracing instrumentation: -```javascript {tabTitle:ESM} {filename: instrument.mjs} +```javascript {tabTitle:ESM} {filename: instrument.mjs} {4} import * as Sentry from "@sentry/node"; Sentry.init({ - dsn: "___PUBLIC_DSN___", - registerEsmLoaderHooks: false + registerEsmLoaderHooks: false, }); ``` @@ -79,13 +79,12 @@ If you are starting Sentry via `--import`, you can instruct `import-in-the-middl to only wrap packages that Sentry specifically instruments. To do this, you can set the `onlyIncludeInstrumentedModules` to `true`: -```javascript {tabTitle:ESM} {filename: instrument.mjs} +```javascript {tabTitle:ESM} {filename: instrument.mjs} {4-6} import * as Sentry from "@sentry/node"; Sentry.init({ - dsn: "___PUBLIC_DSN___", registerEsmLoaderHooks: { - onlyIncludeInstrumentedModules: true + onlyIncludeInstrumentedModules: true, }, }); ``` From 42a8cb10841a07db1762f1fc1a27c53972a41c00 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Thu, 24 Oct 2024 11:22:41 +0200 Subject: [PATCH 4/6] only show for relevant platforms --- docs/platforms/javascript/common/troubleshooting/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 45a20a4817a8d..5dc43bb9fa0fc 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -82,7 +82,7 @@ To fix this, change the `tracePropagationTargets` option during SDK initializati - + 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). From fb54318cd038f6343be8a1d301e6e9f57ff20d37 Mon Sep 17 00:00:00 2001 From: Tim Fish Date: Thu, 24 Oct 2024 11:40:33 +0200 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Alex Krawiec --- docs/platforms/javascript/common/install/esm.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index 5f12f0766bc2f..d8d8ceea8b970 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -63,8 +63,8 @@ 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 +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} From c1c60fb07b1edc4fcf6b10c833792107909d1c09 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Thu, 24 Oct 2024 11:55:59 +0200 Subject: [PATCH 6/6] jeez --- docs/platforms/javascript/common/troubleshooting/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 5dc43bb9fa0fc..05d067d3e3013 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -82,7 +82,8 @@ To fix this, change the `tracePropagationTargets` option during SDK initializati - + + 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). @@ -92,6 +93,7 @@ To fix this, change the `tracePropagationTargets` option during SDK initializati Check out the ESM Troubleshooting Instrumentation section for more information. +