Skip to content

docs: More node docs #11076

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 13, 2024
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
72 changes: 72 additions & 0 deletions docs/v8-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,78 @@ See [New Performance APIs](./v8-new-performance-apis.md) for details.
For now, ESM support is only experimental. For the time being we only fully support CJS-based Node application - we are
working on this during the v8 alpha/beta cycle.

### Using Custom OpenTelemetry Instrumentation

While we include some vetted OpenTelemetry instrumentation out of the box, you can also add your own instrumentation on
top of that. You can do that by installing an instrumentation package (as well as `@opentelemetry/instrumentation`) and
setting it up like this:

```js
const Sentry = require('@sentry/node');
const { GenericPoolInstrumentation } = require('@opentelemetry/instrumentation-generic-pool');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

Sentry.init({
dsn: '__DSN__',
});

// Afterwards, you can add additional instrumentation:
registerInsturmentations({
instrumentations: [new GenericPoolInstrumentation()],
});
```

### Using a Custom OpenTelemetry Setup
Copy link
Member

Choose a reason for hiding this comment

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

Copy link
Member Author

Choose a reason for hiding this comment

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

we'll need to adjust more or less all the node docs, eventually 😬 so yes!


If you already have OpenTelemetry set up yourself, you can also use your existing setup.

In this case, you need to set `skipOpenTelemetrySetup: true` in your `init({})` config, and ensure you setup all the
components that Sentry needs yourself. In this case, you need to install `@sentry/opentelemetry`, and add the following:

```js
const Sentry = require('@sentry/node');
const { SentrySpanProcessor, SentryPropagator, SentryContextManager, SentrySampler } = require('@sentry/opentelemetry');

// We need a custom span processor
provider.addSpanProcessor(new SentrySpanProcessor());
// We need a custom propagator and context manager
provier.register({
propagator: new SentryPropagator(),
contextManager: new SentryContextManager(),
});

// And optionally, if you want to use the `tracesSamplingRate` or related options from Sentry,
// you also need to use a custom sampler when you set up your provider
const provider = new BasicTracerProvider({
sampler: new SentrySampler(Sentry.getClient()),
});
```

## Plain Node / Unsupported Frameworks

When using `@sentry/node` in an app without any supported framework, you will still get some auto instrumentation out of
the box!

Any framework that works on top of `http`, which means any framework that handles incoming HTTP requests, will
automatically be instrumented - so you'll get request isolation & basic transactions without any further action.

For any non-HTTP scenarios (e.g. websockets or a scheduled job), you'll have to manually ensure request isolation by
wrapping the function with `Sentry.withIsolationScope()`:

```js
const Sentry = require('@sentry/node');

function myScheduledJob() {
return Sentry.withIsolationScope(async () => {
await doSomething();
await doSomethingElse();
return { status: 'DONE' };
});
}
```

This way, anything happening inside of this function will be isolated, even if they run concurrently.

## Express

The following shows how you can setup Express instrumentation in v8. This will capture performance data & errors for
Expand Down