Skip to content

Commit e4e48dc

Browse files
committed
ref(js): Update custom Note Otel setup docs
1 parent 6a438d2 commit e4e48dc

File tree

1 file changed

+34
-1
lines changed

1 file changed

+34
-1
lines changed

docs/platforms/javascript/common/opentelemetry/custom-setup.mdx

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,17 @@ If you want to add your own http/node-fetch instrumentation, you have to follow
111111

112112
### Custom HTTP Instrumentation
113113

114-
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 <PlatformLink to="/configuration/integrations/http/">httpIntegration configuration</PlatformLink>.
114+
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`:
115+
116+
```javascript
117+
const sentryClient = Sentry.init({
118+
dsn: "___DSN___",
119+
skipOpenTelemetrySetup: true,
120+
integrations: [Sentry.httpIntegration({ spans: false })],
121+
});
122+
```
123+
124+
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.
115125

116126
### Custom Node Fetch Instrumentation
117127

@@ -168,3 +178,26 @@ const provider = new NodeTracerProvider({
168178
// Validate that the setup is correct
169179
Sentry.validateOpenTelemetrySetup();
170180
```
181+
## ESM loaders
182+
183+
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.
184+
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.
185+
If you are also registering a loader hook, you need to disable Sentry's loader hook:
186+
187+
```javascript
188+
Sentry.init({
189+
skipOpenTelemetrySetup: true,
190+
registerEsmLoaderHooks: false,
191+
});
192+
```
193+
194+
<Note>
195+
196+
Registering loader hooks multiple times might result in duplicated spans being created.
197+
[More details.](https://github.com/getsentry/sentry-javascript/issues/14065#issuecomment-2435546961)
198+
199+
</Note>
200+
201+
Alternatively, you can also use Sentry's loader hook and remove your own loader hook registration code.
202+
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`.
203+
<PlatformLink to="/install">Learn more about ESM installation methods.</PlatformLink>

0 commit comments

Comments
 (0)