diff --git a/src/platform-includes/getting-started-config/javascript.nextjs.mdx b/src/platform-includes/getting-started-config/javascript.nextjs.mdx index 02f7e4984dfbb..bbaf19a056a3b 100644 --- a/src/platform-includes/getting-started-config/javascript.nextjs.mdx +++ b/src/platform-includes/getting-started-config/javascript.nextjs.mdx @@ -17,30 +17,6 @@ To complete your configuration, add o Once you're set up, the SDK will automatically capture unhandled errors and promise rejections, and monitor performance in the client. You can also manually capture errors. -By default, the SDK sets the environment for events to `process.env.NODE_ENV`, although you can set your own. -To capture [Next.js API Route](https://nextjs.org/docs/api-routes/introduction) errors and monitor server performance, you need to wrap your handlers with a Sentry function: - -```javascript {filename:pages/api/*} -import { withSentry } from "@sentry/nextjs"; - -const handler = async (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 = async (req: NextApiRequest, res: NextApiResponse) => { - res.status(200).json({ name: "John Doe" }); -}; - -export default withSentry(handler); -``` - By default, the SDK sets the environment for events to `process.env.NODE_ENV`, although you can [set your own](/platforms/javascript/guides/nextjs/configuration/environments/). To learn how to connect your app to Sentry and deploy it on Vercel, see the [Vercel integration](/product/integrations/deployment/vercel/). diff --git a/src/platform-includes/getting-started-verify/javascript.nextjs.mdx b/src/platform-includes/getting-started-verify/javascript.nextjs.mdx index 33cd9fdad9136..26411a7922260 100644 --- a/src/platform-includes/getting-started-verify/javascript.nextjs.mdx +++ b/src/platform-includes/getting-started-verify/javascript.nextjs.mdx @@ -14,26 +14,19 @@ Add a button to a frontend component that throws an error: And throw an error in an API route: ```javascript {filename:pages/api/error.js} -import { withSentry } from "@sentry/nextjs"; - -const handler = async (req, res) => { +export default (req, res) => { throw new Error("API throw error test"); res.status(200).json({ name: "John Doe" }); }; - -export default withSentry(handler); ``` ```typescript {filename:pages/api/error.ts} import type { NextApiRequest, NextApiResponse } from "next" -import { withSentry } from "@sentry/nextjs"; -const handler = async (req: NextApiRequest, res: NextApiResponse) => { +export default (req: NextApiRequest, res: NextApiResponse) => { throw new Error("API throw error test") res.status(200).json({ name: "John Doe" }); }; - -export default withSentry(handler); ``` diff --git a/src/platform-includes/performance/automatic-instrumentation-intro/javascript.nextjs.mdx b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.nextjs.mdx index 87d99c85d316a..facc78e9121b1 100644 --- a/src/platform-includes/performance/automatic-instrumentation-intro/javascript.nextjs.mdx +++ b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.nextjs.mdx @@ -1 +1,2 @@ -`@sentry/nextjs` provides a `BrowserTracing` integration to add automatic instrumentation for monitoring the performance of browser applications, which is enabled by default once you set up tracing in your app. Further, the same `withSentry` wrapper which enables error collection in your API routes also automatically measures their performance. +`@sentry/nextjs` provides a `BrowserTracing` integration to add automatic instrumentation for monitoring the performance of browser applications, which is enabled by default once you set up tracing in your app. +Further, the SDK will automatically enable error collection and performance monitoring in your API routes and [Next.js Data Fetchers](https://nextjs.org/docs/basic-features/data-fetching/overview). diff --git a/src/platform-includes/performance/connect-services/javascript.mdx b/src/platform-includes/performance/connect-services/javascript.mdx index b66c1730cfb8d..174185b0eef30 100644 --- a/src/platform-includes/performance/connect-services/javascript.mdx +++ b/src/platform-includes/performance/connect-services/javascript.mdx @@ -18,6 +18,8 @@ You'll need to configure your web server [CORS](https://developer.mozilla.org/en ## Pageload + + For traces that begin in your backend, you can connect the automatically-generated `pageload` transaction on the frontend with the request transaction that serves the page on the backend. Because JavaScript code running in a browser cannot read the response headers of the current page, the trace data must be transmitted in the response itself, specifically in `` tags in the `` of the HTML sent from your backend. ```html @@ -35,25 +37,25 @@ For traces that begin in your backend, you can connect the automatically-generat Remix SDK attaches `sentry-trace` and `baggage` values from your `root` loader. You need to use [`meta`](https://remix.run/docs/en/v1/api/conventions#meta) function to attach the data from your `loader` as `` tags. The following code snippet shows how to do this: ```typescript {filename: root.tsx} -export const meta: MetaFunction = ({data}) => { - return { - // ... - 'sentry-trace': data.sentryTrace, - baggage: data.sentryBaggage, - }; +export const meta: MetaFunction = ({ data }) => { + return { + // ... + "sentry-trace": data.sentryTrace, + baggage: data.sentryBaggage, + }; }; ``` - + This feature is available on Sentry Remix SDK version 7.9.0 and above. - The `name` attributes must be the strings `"sentry-trace"` and `"baggage"` and the `content` attributes must be generated by your backend Sentry SDK. For `sentry-trace`, use `span.toSentryTrace()` (or equivalent, depending on the backend platform). This guarantees that a new and unique value will be generated for each request. For `baggage`, use `serializeBaggage(span.getBaggage())`. + The `span.toSentryTrace()` was previously called `span.toTraceparent()`, so that's what you may find depending on the SDK and version. @@ -63,3 +65,13 @@ The `span.toSentryTrace()` was previously called `span.toTraceparent()`, so that The `span` reference is either the transaction that serves the HTML or any of its child spans. It defines the parent of the `pageload` transaction. Once the data is included in the `` tags, our `BrowserTracing` integration will pick them up automatically and link them to the transaction generated on pageload. Note that they will not be linked to automatically-generated `navigation` transactions — that is, those that don't require a full page reload. Each of those will be the result of a different request transaction on the backend and, therefore, should have a unique `trace_id`. + + + + + +For traces that begin in your backend, the `@sentry/nextjs` SDK will automatically connect pageload navigations in the frontend with the request transaction that serves the page on the backend. + +The SDK will return additional props from your configured [Next.js data fetchers](https://nextjs.org/docs/basic-features/data-fetching/overview) that the SDK picks up in to browser to connect the pageload transaction with the backend request. + + diff --git a/src/platform-includes/performance/what-instrumentation-provides/javascript.nextjs.mdx b/src/platform-includes/performance/what-instrumentation-provides/javascript.nextjs.mdx index ede2fd9093a44..916c1f8a9e98b 100644 --- a/src/platform-includes/performance/what-instrumentation-provides/javascript.nextjs.mdx +++ b/src/platform-includes/performance/what-instrumentation-provides/javascript.nextjs.mdx @@ -1 +1,3 @@ -The `BrowserTracing` integration creates a new transaction for each page load and navigation event, and creates a child span for every `XMLHttpRequest` or `fetch` request that occurs while those transactions are open. The `withSentry` wrapper creates a transaction for every API request. Learn more about [traces, transactions, and spans](/product/sentry-basics/tracing/distributed-tracing/). +The `BrowserTracing` integration creates a new transaction for each pageload and navigation event, and creates a child span for every `XMLHttpRequest` or `fetch` request that occurs while those transactions are open. +Additionally, the SDK creates transactions for all requests to API routes and [Next.js data fetchers](https://nextjs.org/docs/basic-features/data-fetching/overview). +Learn more about [traces, transactions, and spans](/product/sentry-basics/tracing/distributed-tracing/). diff --git a/src/platforms/javascript/guides/nextjs/manual-setup.mdx b/src/platforms/javascript/guides/nextjs/manual-setup.mdx index f432fe0dd972b..f3e6ab36b5c05 100644 --- a/src/platforms/javascript/guides/nextjs/manual-setup.mdx +++ b/src/platforms/javascript/guides/nextjs/manual-setup.mdx @@ -48,29 +48,6 @@ Sentry.init({ You can include your DSN directly in these two files, or provide it in either of two environment variables, `SENTRY_DSN` or `NEXT_PUBLIC_SENTRY_DSN`. -If you want to instrument [Next.js API Routes](https://nextjs.org/docs/api-routes/introduction), which run on serverless, you need to wrap your handler in our `withSentry` wrapper in order to be able to capture crashes: - -```javascript {filename:pages/api/*} -import { withSentry } from "@sentry/nextjs"; - -const handler = async (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 = async (req: NextApiRequest, res: NextApiResponse) => { - res.status(200).json({ name: "John Doe" }); -}; - -export default withSentry(handler); -``` - ## Create a Custom `_error` Page In serverless deployment environments, including Vercel, the Next.js server runs in a "minimal" mode to reduce serverless function size. As a result, some of the auto-instrumentation done by `@sentry/nextjs` doesn't run, and therefore certain errors aren't caught. In addition, Next.js includes a custom error boundary which will catch certain errors before they bubble up to our handlers. @@ -242,21 +219,53 @@ module.exports = withSentryConfig(moduleExports); In that case you can also skip the `sentry-cli` configuration step below. -### Automatically Instrument API Routes and Data Fetching Methods +### Automatic Instrumentation of API Routes and Data Fetching Methods _(New in version 7.14.0)_ -The SDK provides an option to 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, removing the need to manually wrap API routes in `withSentry`: +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: true, + autoInstrumentServerFunctions: false, }, }; ``` -Under the hood, the SDK is using a Webpack loader to wrap all your API route handlers and data fetching methods. +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) If the automatic instrumentation doesn't work for your use case, API routes can also be wrapped manually using the `withSentry` function: diff --git a/src/wizard/javascript/nextjs.md b/src/wizard/javascript/nextjs.md index 191c8e26dfe07..df97e1d3b71e9 100644 --- a/src/wizard/javascript/nextjs.md +++ b/src/wizard/javascript/nextjs.md @@ -21,35 +21,19 @@ npx @sentry/wizard -i nextjs ``` Sentry wizard will automatically patch your application: + - create `sentry.client.config.js` and `sentry.server.config.js` with the default `Sentry.init`. - create `next.config.js` with the default configuration. - create `sentry.properties` with configuration for sentry-cli (which is used when automatically uploading source maps). - You can also [configure it manually](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/). - -## Nextjs API routes -While `@sentry/nextjs` will enable Sentry for your nextjs application, files under the `pages/api` require one additional installing step. - -Wrap your API handlers with a `withSentry` function to capture [Next.js API route errors](https://nextjs.org/docs/api-routes/introduction): - -```javascript -import { withSentry } from '@sentry/nextjs'; - -const handler = async (req, res) => { - // ... -} - -export default withSentry(handler); -``` - Configure the Sentry initialization: ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - + // Set tracesSampleRate to 1.0 to capture 100% // of transactions for performance monitoring. // We recommend adjusting this value in production @@ -62,10 +46,13 @@ The above configuration has automatic error tracking with source maps for both J Then create an intentional error, so you can test that everything is working from your development environment. For example, a button whose `onClick` handler throws an error: ```javascript - ```