From 74af05fb2cf4a519d9d5a89ba8b56d070346fb64 Mon Sep 17 00:00:00 2001 From: Katie Byers Date: Thu, 17 Nov 2022 06:30:41 -0800 Subject: [PATCH] feat(nextjs): Add `excludeServerRoutes` option to manual setup page (#5789) This adds the new `excludeServerRoutes` option in the nextjs SDK (added in https://github.com/getsentry/sentry-javascript/pull/6207) to the docs. It also pulls all of the auto-instrumentation config into its own section in the manual setup page. (Note: The only part of this which is actually new content is the `Opt Out of Auto-instrumentation on Specific Routes` section. Everything else is just stuff moving around.) --- .../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 a8bf727e33b77..cb34f5bc2c63a 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 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. + +### 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 server-side data fetching functions, set the `autoInstrumentServerFunctions` to `false`. + +```javascript {filename:next.config.js} +const moduleExports = { + sentry: { + autoInstrumentServerFunctions: false, + }, +}; +``` + +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 to only wrap specific API route handlers or data fetching functions instead. + +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 regexes or strings. When using a string, make sure that it matches the route exactly, and has a leading slash but no trailing one.