From 0d222d80275e8bb12704a23636e27002a11ba21c Mon Sep 17 00:00:00 2001 From: Andrei Borza Date: Fri, 10 May 2024 11:30:04 +0200 Subject: [PATCH 1/4] ref(docs): Update migration to use --require/--import flag --- MIGRATION.md | 2 +- docs/v8-initializing.md | 2 +- docs/v8-node.md | 86 +++++++++++++++++++++++++++++++++-------- 3 files changed, 71 insertions(+), 19 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index ef1f17dcfe7d..4633fc01856e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -20,7 +20,7 @@ stable release of `8.x` comes out). ## 1. Version Support changes: -**Node.js**: We now official support Node 14.18+ for our CJS package, and Node 18.8+ for our ESM package. This applies +**Node.js**: We now official support Node 14.18+ for our CJS package, and Node 18.19+ for our ESM package. This applies to `@sentry/node` and all of our node-based server-side sdks (`@sentry/nextjs`, `@sentry/serverless`, etc.). We no longer test against Node 8, 10, or 12 and cannot guarantee that the SDK will work as expected on these versions. diff --git a/docs/v8-initializing.md b/docs/v8-initializing.md index 238f02aa1bf9..b5c4bf2a0478 100644 --- a/docs/v8-initializing.md +++ b/docs/v8-initializing.md @@ -21,7 +21,7 @@ In an environment with multiple execution contexts (e.g. Node), you can setup mu different contexts, like this: ```js -import * as Sentry from '@sentry/browser'; +import * as Sentry from '@sentry/node'; // Sets up the _default_ client Sentry.init({ diff --git a/docs/v8-node.md b/docs/v8-node.md index b74266a7fbc1..c498eef7744a 100644 --- a/docs/v8-node.md +++ b/docs/v8-node.md @@ -16,7 +16,8 @@ We support the following Node Frameworks out of the box: - [Express](#express) - [Fastify](#fastify) -- Koa +- [Connect](#connect) +- [Koa](#koa) - Nest.js - Hapi @@ -52,13 +53,36 @@ Sentry.init({ const app = express(); ``` +We recommend creating a file named `instrument.js` that imports and initializes Sentry. + ```js -// In v8, in order to ensure express is instrumented, -// you have to initialize before you import: +// In v8, we create a file that only initializes sentry. +// The file is then passed to Node via --require or --import. const Sentry = require('@sentry/node'); Sentry.init({ // ... }); +``` + +Adjust the Node.js call for your application to use the [--require](https://nodejs.org/api/cli.html#-r---require-module) +or [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.js`. Using +`--require` or `--import` is the easiest way to guarantee that Sentry is imported and initialized before any other +modules in your application + +```bash +# If you are using CommonJS (CJS) +node --require ./instrument.js app.js + +# If you are using ECMAScript Modules (ESM) +# Note: This is only available for Node v18.19.0 onwards. +node --import ./instrument.mjs app.mjs +``` + +**Alternatively**, if you cannot run node with `--require` or `--import`, add a top level import of `instrument.js` in +your application. + +```js +require('./instrument.js'); const express = require('express'); const app = express(); @@ -75,8 +99,11 @@ See [New Performance APIs](./v8-new-performance-apis.md) for details. ### ESM Support -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. +Instrumentation works out of the box for CommonJS (CJS) applications based on require() calls. This means that as long +as your application is either natively in CJS, or compiled at build time to CJS (which is the case for most TypeScript +apps, for example), everything will work without any further setup. + +ECMAScript Modules (ESM) are only supported for Node v18.19.0 onwards. ### Using Custom OpenTelemetry Instrumentation @@ -153,12 +180,6 @@ your Express app. ```js const Sentry = require('@sentry/node'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1, -}); - const express = require('express'); const app = express(); @@ -177,12 +198,6 @@ your Fastify app. ```js const Sentry = require('@sentry/node'); - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1, -}); - const { fastify } = require('fastify'); const app = fastify(); Sentry.setupFastifyErrorHandler(app); @@ -191,3 +206,40 @@ Sentry.setupFastifyErrorHandler(app); app.listen(); ``` + +## Connect + +The following shows how you can setup Connect instrumentation in v8. This will capture performance data & errors for +your Fastify app. + +```js +const connect = require('connect'); +const Sentry = require('@sentry/node'); +const app = connect(); + +Sentry.setupConnectErrorHandler(app); + +// Add your routes, etc. + +app.listen(3030); +``` + +## Koa + +The following shows how you can setup Koa instrumentation in v8. This will capture performance data & errors for your +Fastify app. + +```js +const Koa = require('koa'); +const Router = require('@koa/router'); +const Sentry = require('@sentry/node'); + +const router = new Router(); +const app = new Koa(); + +Sentry.setupKoaErrorHandler(app); + +// Add your routes, etc. + +app.listen(3030); +``` From 5f730d935907c6bc11ba13cce30a3db4a6b667f9 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Fri, 10 May 2024 16:30:09 +0200 Subject: [PATCH 2/4] Apply suggestions from code review --- docs/v8-node.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/v8-node.md b/docs/v8-node.md index c498eef7744a..9221c1c10a52 100644 --- a/docs/v8-node.md +++ b/docs/v8-node.md @@ -56,8 +56,8 @@ const app = express(); We recommend creating a file named `instrument.js` that imports and initializes Sentry. ```js -// In v8, we create a file that only initializes sentry. -// The file is then passed to Node via --require or --import. +// In v8, create a separate file that initializes sentry. +// Then pass the file to Node via --require or --import. const Sentry = require('@sentry/node'); Sentry.init({ // ... @@ -100,8 +100,7 @@ See [New Performance APIs](./v8-new-performance-apis.md) for details. ### ESM Support Instrumentation works out of the box for CommonJS (CJS) applications based on require() calls. This means that as long -as your application is either natively in CJS, or compiled at build time to CJS (which is the case for most TypeScript -apps, for example), everything will work without any further setup. +as your application is either natively in CJS, or compiled at build time to CJS, everything will work without any further setup. ECMAScript Modules (ESM) are only supported for Node v18.19.0 onwards. From bdb8706b50027f770ef2486a9286b11ee0b66d53 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Fri, 10 May 2024 14:33:30 +0000 Subject: [PATCH 3/4] lint --- docs/v8-node.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/v8-node.md b/docs/v8-node.md index 9221c1c10a52..73339494bbf8 100644 --- a/docs/v8-node.md +++ b/docs/v8-node.md @@ -100,7 +100,8 @@ See [New Performance APIs](./v8-new-performance-apis.md) for details. ### ESM Support Instrumentation works out of the box for CommonJS (CJS) applications based on require() calls. This means that as long -as your application is either natively in CJS, or compiled at build time to CJS, everything will work without any further setup. +as your application is either natively in CJS, or compiled at build time to CJS, everything will work without any +further setup. ECMAScript Modules (ESM) are only supported for Node v18.19.0 onwards. From ddc2f85239e5673a60f4ac1d685a9b6e86f28642 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Fri, 10 May 2024 14:36:09 +0000 Subject: [PATCH 4/4] typo --- MIGRATION.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 4633fc01856e..fe35e77722d0 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -20,9 +20,9 @@ stable release of `8.x` comes out). ## 1. Version Support changes: -**Node.js**: We now official support Node 14.18+ for our CJS package, and Node 18.19+ for our ESM package. This applies -to `@sentry/node` and all of our node-based server-side sdks (`@sentry/nextjs`, `@sentry/serverless`, etc.). We no -longer test against Node 8, 10, or 12 and cannot guarantee that the SDK will work as expected on these versions. +**Node.js**: We now officially support Node 14.18+ for our CJS package, and Node 18.19.1+ for our ESM package. This +applies to `@sentry/node` and all of our node-based server-side sdks (`@sentry/nextjs`, `@sentry/serverless`, etc.). We +no longer test against Node 8, 10, or 12 and cannot guarantee that the SDK will work as expected on these versions. **Browser**: Our browser SDKs (`@sentry/browser`, `@sentry/react`, `@sentry/vue`, etc.) now require ES2018+ compatible browsers. This means that we no longer support IE11 (end of an era). This also means that the Browser SDK requires the