diff --git a/docs/v8-node.md b/docs/v8-node.md index 960541889c3e..47bab0cdd452 100644 --- a/docs/v8-node.md +++ b/docs/v8-node.md @@ -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 + +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