From 2d526dd5f837cf55f3b9141e1f5fec312f588fc9 Mon Sep 17 00:00:00 2001 From: Katie Byers Date: Tue, 15 Nov 2022 10:42:26 -0800 Subject: [PATCH 1/2] add `excludeServerRoutes` option to manual setup page --- .../javascript/guides/nextjs/manual-setup.mdx | 146 +++++++++++------- 1 file changed, 90 insertions(+), 56 deletions(-) diff --git a/src/platforms/javascript/guides/nextjs/manual-setup.mdx b/src/platforms/javascript/guides/nextjs/manual-setup.mdx index a8bf727e33b77e..d9c56a7691e1ba 100644 --- a/src/platforms/javascript/guides/nextjs/manual-setup.mdx +++ b/src/platforms/javascript/guides/nextjs/manual-setup.mdx @@ -156,14 +156,17 @@ const moduleExports = { // Optional build-time configuration options sentry: { - // See the 'Configure Source Maps' and 'Configure Legacy Browser Support' - // sections below for information on the following options: - // - disableServerWebpackPlugin - // - disableClientWebpackPlugin - // - autoInstrumentServerFunctions - // - hideSourceMaps - // - widenClientFileUpload - // - transpileClientSDK + // See the sections below for information on the following options: + // 'Configure Source Maps': + // - disableServerWebpackPlugin + // - disableClientWebpackPlugin + // - hideSourceMaps + // - widenClientFileUpload + // 'Configure Legacy Browser Support': + // - transpileClientSDK + // 'Configure Serverside Auto-instrumentation': + // - autoInstrumentServerFunctions + // - excludeServerRoutes }, }; @@ -219,54 +222,6 @@ module.exports = withSentryConfig(moduleExports); In that case you can also skip the `sentry-cli` configuration step below. -### Automatic Instrumentation of API Routes and Data Fetching Methods - -_(New in version 7.14.0)_ - -The SDK will automatically instrument API routes and server-side [Next.js data fetching methods](https://nextjs.org/docs/basic-features/data-fetching/overview) with error and performance monitoring To disable it, set the `autoInstrumentServerFunctions` to `false`. - -```javascript {filename:next.config.js} -const moduleExports = { - sentry: { - autoInstrumentServerFunctions: false, - }, -}; -``` - -Under the hood, when using this option, the SDK is using a Webpack loader to wrap all your API route handlers and data fetching methods. - -If the automatic instrumentation doesn't work for your use case, API routes can also be wrapped manually using the `withSentry` function: - -```javascript {filename:pages/api/*} -import { withSentry } from "@sentry/nextjs"; - -const handler = (req, res) => { - res.status(200).json({ name: "John Doe" }); -}; - -export default withSentry(handler); -``` - -```typescript {filename:pages/api/*} -import type { NextApiRequest, NextApiResponse } from "next" -import { withSentry } from "@sentry/nextjs"; - -const handler = (req: NextApiRequest, res: NextApiResponse) => { - res.status(200).json({ name: "John Doe" }); -}; - -export default withSentry(handler); -``` - -Data fetching methods can also be manually wrapped using the following functions: - -- `withSentryServerSideGetInitialProps` for `getInitialProps` -- `withSentryGetServerSideProps` for `getServerSideProps` -- `withSentryGetStaticProps` for `getStaticProps` -- `withSentryServerSideErrorGetInitialProps` for `getInitialProps` in [custom Error pages](https://nextjs.org/docs/advanced-features/custom-error-page) -- `withSentryServerSideAppGetInitialProps` for `getInitialProps` in [custom `App` components](https://nextjs.org/docs/advanced-features/custom-app) -- `withSentryServerSideDocumentGetInitialProps` for `getInitialProps` in [custom `Document` components](https://nextjs.org/docs/advanced-features/custom-document) - ### Use `hidden-source-map` _(New in version 6.17.1, will default to `true` in 8.0.0 and beyond.)_ @@ -355,3 +310,82 @@ const moduleExports = { ``` (This assumes you are using [the `next.config.js` setup shown above](#extend-nextjs-configuration).) + +## Configure Serverside Auto-instrumentation + +The SDK will automatically instrument API routes and server-side [Next.js data fetching methods](https://nextjs.org/docs/basic-features/data-fetching/overview) with error and performance monitoring. + +### Disable API Route and Data Fetching Auto-instrumentation Entirely + +_(New in version 7.14.0)_ + +To disable the automatic instrumentation of API route handlers and serverside data fetching functions, set the `autoInstrumentServerFunctions` to `false`. + +```javascript {filename:next.config.js} +const moduleExports = { + sentry: { + autoInstrumentServerFunctions: false, + }, +}; +``` + +Under the hood, when using this option, the SDK is using a Webpack loader to wrap all your API route handlers and data fetching methods. + +### Opt In to Auto-instrumentation on Specific Routes + +_(New in version 7.14.0)_ + +If the automatic instrumentation doesn't work for your use case, you can turn it off globally and choose instead to only wrap specific API route handlers or data fetching functions. + +For API routes, use the `withSentry` function: + +```javascript {filename:pages/api/*} +import { withSentry } from "@sentry/nextjs"; + +const handler = (req, res) => { + res.status(200).json({ name: "John Doe" }); +}; + +export default withSentry(handler); +``` + +```typescript {filename:pages/api/*} +import type { NextApiRequest, NextApiResponse } from "next" +import { withSentry } from "@sentry/nextjs"; + +const handler = (req: NextApiRequest, res: NextApiResponse) => { + res.status(200).json({ name: "John Doe" }); +}; + +export default withSentry(handler); +``` + +For data fetching methods, use the following functions: + +- `withSentryServerSideGetInitialProps` for `getInitialProps` +- `withSentryGetServerSideProps` for `getServerSideProps` +- `withSentryGetStaticProps` for `getStaticProps` +- `withSentryServerSideErrorGetInitialProps` for `getInitialProps` in [custom Error pages](https://nextjs.org/docs/advanced-features/custom-error-page) +- `withSentryServerSideAppGetInitialProps` for `getInitialProps` in [custom `App` components](https://nextjs.org/docs/advanced-features/custom-app) +- `withSentryServerSideDocumentGetInitialProps` for `getInitialProps` in [custom `Document` components](https://nextjs.org/docs/advanced-features/custom-document) + +### Opt Out of Auto-instrumentation on Specific Routes + +_(New in version 7.20.0)_ + +If you want auto-instrumenatation to apply by default, but want to exclude certain routes, use the `excludeServerRoutes` option in the `sentry` object in your `next.config.js`: + +```javascript {filename:next.config.js} +const moduleExports = { + sentry: { + excludeServerRoutes: [ + "/some/excluded/route", + "/excluded/route/with/[parameter]", + /^\/route\/beginning\/with\/some\/prefix/, + /\/routeContainingASpecificPathSegment\/?/, + ], + }, +}; +``` + +Excluded routes can be specified either as strings (which must exactly match the full route you want to exclude, with a leading slash but no trailing one) or regexes. From 1cf772436f4115b9a68f2b45a3f34b399ef06e4a Mon Sep 17 00:00:00 2001 From: Katie Byers Date: Wed, 16 Nov 2022 21:28:23 -0800 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Liza Mock --- .../javascript/guides/nextjs/manual-setup.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/platforms/javascript/guides/nextjs/manual-setup.mdx b/src/platforms/javascript/guides/nextjs/manual-setup.mdx index d9c56a7691e1ba..cb34f5bc2c63a0 100644 --- a/src/platforms/javascript/guides/nextjs/manual-setup.mdx +++ b/src/platforms/javascript/guides/nextjs/manual-setup.mdx @@ -311,7 +311,7 @@ const moduleExports = { (This assumes you are using [the `next.config.js` setup shown above](#extend-nextjs-configuration).) -## Configure Serverside Auto-instrumentation +## Configure Server-side Auto-instrumentation The SDK will automatically instrument API routes and server-side [Next.js data fetching methods](https://nextjs.org/docs/basic-features/data-fetching/overview) with error and performance monitoring. @@ -319,7 +319,7 @@ The SDK will automatically instrument API routes and server-side [Next.js data f _(New in version 7.14.0)_ -To disable the automatic instrumentation of API route handlers and serverside data fetching functions, set the `autoInstrumentServerFunctions` to `false`. +To disable the automatic instrumentation of API route handlers and server-side data fetching functions, set the `autoInstrumentServerFunctions` to `false`. ```javascript {filename:next.config.js} const moduleExports = { @@ -329,13 +329,13 @@ const moduleExports = { }; ``` -Under the hood, when using this option, the SDK is using a Webpack loader to wrap all your API route handlers and data fetching methods. +With this option, under the hood, the SDK is using a Webpack loader to wrap all your API route handlers and data fetching methods. ### Opt In to Auto-instrumentation on Specific Routes _(New in version 7.14.0)_ -If the automatic instrumentation doesn't work for your use case, you can turn it off globally and choose instead to only wrap specific API route handlers or data fetching functions. +If the automatic instrumentation doesn't work for your use case, you can turn it off globally and choose to only wrap specific API route handlers or data fetching functions instead. For API routes, use the `withSentry` function: @@ -388,4 +388,4 @@ const moduleExports = { }; ``` -Excluded routes can be specified either as strings (which must exactly match the full route you want to exclude, with a leading slash but no trailing one) or regexes. +Excluded routes can be specified either as regexes or strings. When using a string, make sure that it matches the route exactly, and has a leading slash but no trailing one.