diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index 289cfad3bbdc3..e39ea40ae68fc 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -105,13 +105,25 @@ 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: ### 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. +_Available since SDK version 8.35.0_ + +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({ + 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 +180,28 @@ 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 load this file prior to your application via `node --import instrument.mjs your-app.mjs`. + +Learn more about ESM installation methods. +