Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 39 additions & 2 deletions docs/platforms/javascript/common/opentelemetry/custom-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -105,13 +105,25 @@ If tracing is not enabled (no `tracesSampleRate` is defined in the SDK configura
</Note>
</PlatformSection>

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Above there is also this sentence:

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.

Which we should also adjust (I guess just remove the second sentence?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, good point. We no longer configure HttpInstrumentation for this but use our own instrumentation. Will remove the sentence


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>.
_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

Expand Down Expand Up @@ -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,
});
```

<Note>

Registering loader hooks multiple times might result in duplicated spans being created.
[More details.](https://github.com/getsentry/sentry-javascript/issues/14065#issuecomment-2435546961)

</Note>

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`.
<PlatformSection supported={['javascript.node']}>
<PlatformLink to="/install">Learn more about ESM installation methods.</PlatformLink>
</PlatformSection>
Loading