Skip to content

Commit a20bf74

Browse files
authored
docs: More node docs (#11076)
Some more node docs for v8, including: * How to add custom OTEL instrumentation * How to use with custom OTEL setup * How to setup non-framework node apps
1 parent eb6a3c5 commit a20bf74

File tree

1 file changed

+72
-0
lines changed

1 file changed

+72
-0
lines changed

docs/v8-node.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,78 @@ See [New Performance APIs](./v8-new-performance-apis.md) for details.
7878
For now, ESM support is only experimental. For the time being we only fully support CJS-based Node application - we are
7979
working on this during the v8 alpha/beta cycle.
8080

81+
### Using Custom OpenTelemetry Instrumentation
82+
83+
While we include some vetted OpenTelemetry instrumentation out of the box, you can also add your own instrumentation on
84+
top of that. You can do that by installing an instrumentation package (as well as `@opentelemetry/instrumentation`) and
85+
setting it up like this:
86+
87+
```js
88+
const Sentry = require('@sentry/node');
89+
const { GenericPoolInstrumentation } = require('@opentelemetry/instrumentation-generic-pool');
90+
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
91+
92+
Sentry.init({
93+
dsn: '__DSN__',
94+
});
95+
96+
// Afterwards, you can add additional instrumentation:
97+
registerInsturmentations({
98+
instrumentations: [new GenericPoolInstrumentation()],
99+
});
100+
```
101+
102+
### Using a Custom OpenTelemetry Setup
103+
104+
If you already have OpenTelemetry set up yourself, you can also use your existing setup.
105+
106+
In this case, you need to set `skipOpenTelemetrySetup: true` in your `init({})` config, and ensure you setup all the
107+
components that Sentry needs yourself. In this case, you need to install `@sentry/opentelemetry`, and add the following:
108+
109+
```js
110+
const Sentry = require('@sentry/node');
111+
const { SentrySpanProcessor, SentryPropagator, SentryContextManager, SentrySampler } = require('@sentry/opentelemetry');
112+
113+
// We need a custom span processor
114+
provider.addSpanProcessor(new SentrySpanProcessor());
115+
// We need a custom propagator and context manager
116+
provier.register({
117+
propagator: new SentryPropagator(),
118+
contextManager: new SentryContextManager(),
119+
});
120+
121+
// And optionally, if you want to use the `tracesSamplingRate` or related options from Sentry,
122+
// you also need to use a custom sampler when you set up your provider
123+
const provider = new BasicTracerProvider({
124+
sampler: new SentrySampler(Sentry.getClient()),
125+
});
126+
```
127+
128+
## Plain Node / Unsupported Frameworks
129+
130+
When using `@sentry/node` in an app without any supported framework, you will still get some auto instrumentation out of
131+
the box!
132+
133+
Any framework that works on top of `http`, which means any framework that handles incoming HTTP requests, will
134+
automatically be instrumented - so you'll get request isolation & basic transactions without any further action.
135+
136+
For any non-HTTP scenarios (e.g. websockets or a scheduled job), you'll have to manually ensure request isolation by
137+
wrapping the function with `Sentry.withIsolationScope()`:
138+
139+
```js
140+
const Sentry = require('@sentry/node');
141+
142+
function myScheduledJob() {
143+
return Sentry.withIsolationScope(async () => {
144+
await doSomething();
145+
await doSomethingElse();
146+
return { status: 'DONE' };
147+
});
148+
}
149+
```
150+
151+
This way, anything happening inside of this function will be isolated, even if they run concurrently.
152+
81153
## Express
82154

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

0 commit comments

Comments
 (0)