From a9de7c4f6d4d3a66520a6e570b4b4c84211a299c Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 13 Mar 2024 09:24:00 +0000 Subject: [PATCH 1/3] docs: More node docs --- docs/v8-node.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/v8-node.md b/docs/v8-node.md index 960541889c3e..eeef699168f3 100644 --- a/docs/v8-node.md +++ b/docs/v8-node.md @@ -78,6 +78,83 @@ 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 From 0b3de34f9538eff754ed7ccc43e339bf543a1bda Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 13 Mar 2024 09:32:53 +0000 Subject: [PATCH 2/3] small typo fixes --- docs/v8-node.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/v8-node.md b/docs/v8-node.md index eeef699168f3..30292b8f90e6 100644 --- a/docs/v8-node.md +++ b/docs/v8-node.md @@ -78,7 +78,7 @@ 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 +### 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 @@ -99,7 +99,7 @@ registerInsturmentations({ }); ``` -### Using a custom OpenTelemetry Setup +### Using a Custom OpenTelemetry Setup If you already have OpenTelemetry set up yourself, you can also use your existing setup. From cc04a13953af77a877e9a07d878df763092b4864 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 13 Mar 2024 09:48:16 +0000 Subject: [PATCH 3/3] fix linting --- docs/v8-node.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/v8-node.md b/docs/v8-node.md index 30292b8f90e6..47bab0cdd452 100644 --- a/docs/v8-node.md +++ b/docs/v8-node.md @@ -108,25 +108,20 @@ components that Sentry needs yourself. In this case, you need to install `@sentr ```js const Sentry = require('@sentry/node'); -const { - SentrySpanProcessor, - SentryPropagator, - SentryContextManager, - SentrySampler - } = require("@sentry/opentelemetry"); +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(), + 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()), + sampler: new SentrySampler(Sentry.getClient()), }); ```