From e4e48dc55496e152d6c6b7d61679f1ff1a8d9b9a Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 31 Oct 2024 13:28:50 +0100 Subject: [PATCH 1/5] ref(js): Update custom Note Otel setup docs --- .../common/opentelemetry/custom-setup.mdx | 35 ++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index 289cfad3bbdc3..f3fb838ce73fe 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -111,7 +111,17 @@ If you want to add your own http/node-fetch instrumentation, you have to follow ### Custom HTTP Instrumentation -You won't be able to add `@opentelemetry/instrumentation-http` yourself and will need to use `httpIntegration` in order for Sentry to work as expected. If you want to use custom configuration for your HTTP instrumentation, you can use the httpIntegration configuration. +You can add your own `@opentelemetry/instrumentation-http` instance in your setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`: + +```javascript +const sentryClient = Sentry.init({ + dsn: "___DSN___", + skipOpenTelemetrySetup: true, + integrations: [Sentry.httpIntegration({ spans: false })], +}); +``` + +It's important that `httpIntegration` is still registered this way to ensure that the Sentry SDK can correctly isolate requests, for example when capturing errors. ### Custom Node Fetch Instrumentation @@ -168,3 +178,26 @@ const provider = new NodeTracerProvider({ // Validate that the setup is correct Sentry.validateOpenTelemetrySetup(); ``` +## ESM loaders + +If your application is running in ESM (`import`/`export` syntax), OpenTelemetry requires a [special setup](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md) to work correctly. +The Sentry SDK will automatically detect if your application is running in ESM mode and by default [register a loader hook](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md#instrumentation-hook-required-for-esm) itself. +If you are also registering a loader hook, you need to disable Sentry's loader hook: + +```javascript +Sentry.init({ + skipOpenTelemetrySetup: true, + registerEsmLoaderHooks: false, +}); +``` + + + +Registering loader hooks multiple times might result in duplicated spans being created. +[More details.](https://github.com/getsentry/sentry-javascript/issues/14065#issuecomment-2435546961) + + + +Alternatively, you can also use Sentry's loader hook and remove your own loader hook registration code. +In this case, ensure that you initialize the Sentry SDK in its own file and you load this file prior to your application via `node --import instrument.mjs your-app.mjs`. +Learn more about ESM installation methods. From d536e72ef003e4f8b4d46359d99b47c8ad5df319 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 31 Oct 2024 13:30:33 +0100 Subject: [PATCH 2/5] availability note --- docs/platforms/javascript/common/opentelemetry/custom-setup.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index f3fb838ce73fe..c397571fb6ac3 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -111,6 +111,8 @@ If you want to add your own http/node-fetch instrumentation, you have to follow ### Custom HTTP Instrumentation +_Available since SDK version 8.35.0_ + You can add your own `@opentelemetry/instrumentation-http` instance in your setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`: ```javascript From 449a8a5bbdfadad8084229c59bd20e1df8119d83 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 31 Oct 2024 14:50:42 +0100 Subject: [PATCH 3/5] review suggestions --- .../javascript/common/opentelemetry/custom-setup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index c397571fb6ac3..263ef29fc41d8 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -105,7 +105,7 @@ If tracing is not enabled (no `tracesSampleRate` is defined in the SDK configura -These are needed to make sure that trace propagation works correctly. Additionally, the HTTP instrumentation is configured to ensure that request isolation is automatically applied for Sentry. +These are needed to make sure that trace propagation works correctly. If you want to add your own http/node-fetch instrumentation, you have to follow the following steps: @@ -113,7 +113,7 @@ If you want to add your own http/node-fetch instrumentation, you have to follow _Available since SDK version 8.35.0_ -You can add your own `@opentelemetry/instrumentation-http` instance in your setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`: +You can add your own `@opentelemetry/instrumentation-http` instance in your OpenTelemetry setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`: ```javascript const sentryClient = Sentry.init({ From a90681f5071603534268498ae15478775b5be776 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 31 Oct 2024 14:51:15 +0100 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Francesco Novy --- .../javascript/common/opentelemetry/custom-setup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index 263ef29fc41d8..5ab76e833e884 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -180,7 +180,7 @@ const provider = new NodeTracerProvider({ // Validate that the setup is correct Sentry.validateOpenTelemetrySetup(); ``` -## ESM loaders +## ESM Loaders If your application is running in ESM (`import`/`export` syntax), OpenTelemetry requires a [special setup](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md) to work correctly. The Sentry SDK will automatically detect if your application is running in ESM mode and by default [register a loader hook](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md#instrumentation-hook-required-for-esm) itself. @@ -201,5 +201,5 @@ Registering loader hooks multiple times might result in duplicated spans being c Alternatively, you can also use Sentry's loader hook and remove your own loader hook registration code. -In this case, ensure that you initialize the Sentry SDK in its own file and you load this file prior to your application via `node --import instrument.mjs your-app.mjs`. +In this case, ensure that you initialize the Sentry SDK in its own file and load this file prior to your application via `node --import instrument.mjs your-app.mjs`. Learn more about ESM installation methods. From c432ac2fc7060b58647b336a41b09ea88fe5de08 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 31 Oct 2024 16:02:48 +0100 Subject: [PATCH 5/5] fix links --- docs/platforms/javascript/common/opentelemetry/custom-setup.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index 5ab76e833e884..e39ea40ae68fc 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -202,4 +202,6 @@ Registering loader hooks multiple times might result in duplicated spans being c Alternatively, you can also use Sentry's loader hook and remove your own loader hook registration code. In this case, ensure that you initialize the Sentry SDK in its own file and load this file prior to your application via `node --import instrument.mjs your-app.mjs`. + Learn more about ESM installation methods. +