From 60329da35d8e17206b541dd561eff03c63c6ecf7 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 10 Apr 2025 13:54:53 +0200 Subject: [PATCH 1/4] remove API-related content from next.js manual QS guide and add these APIs to APIs page --- docs/platforms/javascript/common/apis.mdx | 128 +++++++++++++- .../javascript/guides/nextjs/manual-setup.mdx | 165 ++---------------- 2 files changed, 133 insertions(+), 160 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 7627cf0dc6810..0d46b1ee4cc15 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -330,7 +330,7 @@ Messages show up as issues on your issue stream, with the message as the issue n You cannot search these, but they are viewable on the issue page - if you need to be able to filter for certain data, use [tags](./#setTag) instead. - There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. +There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. By default, Sentry SDKs normalize nested structured context data up to three levels deep. Any data beyond this depth will be trimmed and marked using its type instead. @@ -341,13 +341,14 @@ Learn more about conventions for common contexts in the [contexts interface deve Context data is structured and can contain any data you want: - ```javascript - Sentry.setContext("character", { - name: "Mighty Fighter", - age: 19, - attack_type: "melee", - }); - ``` +```javascript +Sentry.setContext("character", { + name: "Mighty Fighter", + age: 19, + attack_type: "melee", +}); +``` + @@ -426,7 +427,6 @@ Learn more about conventions for common contexts in the [contexts interface deve - @@ -1077,3 +1077,113 @@ parameters={[ Wraps a callback with a cron monitor check in. The check in will be sent to Sentry when the callback finishes. + + +## Server Actions + + + To instrument Next.js Server Actions, wrap their content in `withServerActionInstrumentation`, along with a name to describe your server action. + You can optionally pass form data and headers to record them, and configure the wrapper to record the Server Action responses. + + + ```tsx + import * as Sentry from "@sentry/nextjs"; + import { headers } from "next/headers"; + + export default function ServerComponent() { + async function myServerAction(formData: FormData) { + "use server"; + return await Sentry.withServerActionInstrumentation( + "myServerAction", // The name you want to associate this Server Action with in Sentry + { + formData, // Optionally pass in the form data + headers: headers(), // Optionally pass in headers + recordResponse: true, // Optionally record the server action response + }, + async () => { + // ... Your Server Action code + + return { name: "John Doe" }; + } + ); + } + + return ( +
+ + +
+ ); + } + ``` + + + + +## Route and Data Fetching Instrumentation + + + Instrument the provided API route handler with Sentry for error and + performance monitoring. This function wraps the handler exported from the + user's API page route file (which may or may not already be wrapped with + `withSentry`). + + + + Instrument a `getInitialProps` function with Sentry error and performance + monitoring by creating and returning a wrapped version of the function. + + + + Instrument a `getServerSideProps` function with Sentry error and performance + monitoring by creating and returning a wrapped version of the function. + + + + Instrument a `getStaticProps` function with Sentry error and performance + monitoring by creating and returning a wrapped version of the function. + + + + Instrument a `getInitialProps` function in a custom error page ("_error.js") + with Sentry error and performance monitoring by creating and returning a + wrapped version of the function. + + + + Instrument a `getInitialProps` function in a custom app ("_app.js") with + Sentry error and performance monitoring by creating and returning a wrapped + version of the function. + + + + Instrument a `getInitialProps` function in a custom document ("_document.js") + with Sentry error and performance monitoring by creating and returning a + wrapped version of the function. + + + diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx index b8ee6fa167259..dda1ba05cc6cc 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx @@ -195,6 +195,15 @@ export async function register() { file. + + If you want the Sentry SDK to be available on the server side and not on the + client side, simply delete `instrumentation-client.(js|ts)`. This will prevent + webpack from pulling in the Sentry-related files when generating the browser + bundle. Similarly, if you want to opt out of server-side SDK bundling, delete + the `sentry.server.config.js` and `sentry.edge.config.js` files. Make sure to + remove any imports of these files from `instrumentation.ts`. + + ## Step 3: Capture React Render Errors To capture React render errors, you need to add error components for the App Router and the Pages Router. @@ -350,46 +359,7 @@ CustomErrorComponent.getInitialProps = async (contextData) => { export default CustomErrorComponent; ``` -## Step 4: Instrument Next.js Server Actions (Optional) - -_Requires `@sentry/nextjs` SDK version `7.81.0` or newer._ - -To instrument Next.js Server Actions, wrap their content in `withServerActionInstrumentation`, along with a name to describe your server action. - -You can optionally pass form data and headers to record them, and configure the wrapper to record the Server Action responses: - -```tsx -import * as Sentry from "@sentry/nextjs"; -import { headers } from "next/headers"; - -export default function ServerComponent() { - async function myServerAction(formData: FormData) { - "use server"; - return await Sentry.withServerActionInstrumentation( - "myServerAction", // The name you want to associate this Server Action with in Sentry - { - formData, // Optionally pass in the form data - headers: headers(), // Optionally pass in headers - recordResponse: true, // Optionally record the server action response - }, - async () => { - // ... Your Server Action code - - return { name: "John Doe" }; - } - ); - } - - return ( -
- - -
- ); -} -``` - -## Step 5: Add Readable Stack Traces With Source Maps (Optional) +## Step 4: Add Readable Stack Traces With Source Maps (Optional) Sentry can automatically provide readable stack traces for errors using source maps, requiring a Sentry auth token. @@ -431,7 +401,7 @@ Make sure to keep your auth token secret and out of version control. -## Step 6: Avoid Ad Blockers With Tunneling (Optional) +## Step 5: Avoid Ad Blockers With Tunneling (Optional) You can prevent ad blockers from blocking Sentry events using tunneling. Use the `tunnelRoute` option to add an API endpoint in your application that forwards Sentry events to Sentry servers. @@ -461,114 +431,7 @@ module.exports = withSentryConfig(nextConfig, { negative matcher to your middleware like `(?!monitoring-tunnel)`. -## Step 7: Configure Server-side Auto-instrumentation (Optional) - -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 tracing. - -### Disable API Route, Middleware and Data Fetching Auto-instrumentation Entirely - -To disable the automatic instrumentation of API route handlers and server-side data fetching functions, set the `autoInstrumentServerFunctions` to `false`. - -```javascript {tabTitle:ESM} {filename:next.config.mjs} -export default withSentryConfig(nextConfig, { - autoInstrumentServerFunctions: false, -}); -``` - -```javascript {tabTitle:CJS} {filename:next.config.js} -module.exports = withSentryConfig(nextConfig, { - 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 - -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 `wrapApiHandlerWithSentry` function: - -```javascript {filename:pages/api/*} -import { wrapApiHandlerWithSentry } from "@sentry/nextjs"; - -const handler = (req, res) => { - res.status(200).json({ name: "John Doe" }); -}; - -export default wrapApiHandlerWithSentry(handler, "/api/myRoute"); -``` - -```typescript {filename:pages/api/*} -import type { NextApiRequest, NextApiResponse } from "next"; -import { wrapApiHandlerWithSentry } from "@sentry/nextjs"; - -const handler = (req: NextApiRequest, res: NextApiResponse) => { - res.status(200).json({ name: "John Doe" }); -}; - -export default wrapApiHandlerWithSentry(handler, "/api/myRoute"); -``` - -For data fetching methods, use the following functions: - -- `wrapGetInitialPropsWithSentry` for `getInitialProps` -- `wrapGetServerSidePropsWithSentry` for `getServerSideProps` -- `wrapGetStaticPropsWithSentry` for `getStaticProps` -- `wrapErrorGetInitialPropsWithSentry` for `getInitialProps` in [custom Error pages](https://nextjs.org/docs/advanced-features/custom-error-page) -- `wrapAppGetInitialPropsWithSentry` for `getInitialProps` in [custom `App` components](https://nextjs.org/docs/advanced-features/custom-app) -- `wrapDocumentGetInitialPropsWithSentry` for `getInitialProps` in [custom `Document` components](https://nextjs.org/docs/advanced-features/custom-document) - -### Opt Out of Auto-instrumentation on Specific Routes - -If you want auto-instrumentation to apply by default, but want to exclude certain routes, use the `excludeServerRoutes` option: - -```javascript {tabTitle:ESM} {filename:next.config.mjs} -export default withSentryConfig(nextConfig, { - excludeServerRoutes: [ - "/some/excluded/route", - "/excluded/route/with/[parameter]", - /^\/route\/beginning\/with\/some\/prefix/, - /\/routeContainingASpecificPathSegment\/?/, - ], -}); -``` - -```javascript {tabTitle:CJS} {filename:next.config.js} -module.exports = withSentryConfig(nextConfig, { - 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. - -### Opt Out of Auto-instrumentation on Middleware - -To disable the automatic instrumentation of Next.js middleware, set the `autoInstrumentMiddleware` option to `false`. - -```javascript {tabTitle:ESM} {filename:next.config.mjs} -export default withSentryConfig(nextConfig, { - autoInstrumentMiddleware: false, -}); -``` - -```javascript {tabTitle:CJS} {filename:next.config.js} -module.exports = withSentryConfig(nextConfig, { - autoInstrumentMiddleware: false, -}); -``` - -### Opt Out of Sentry SDK bundling in Client- or Server-Side - -If you want the Sentry SDK to be available in your server-side and not in client-side, you can simply delete `instrumentation-client.(js|ts)`. This will prevent webpack from pulling in the Sentry related files when generating the browser bundle. -Similarly, to opt out of server-side SDK bundling, you can simply delete the `sentry.server.config.js` and `sentry.edge.config.js` files. Make sure to remove any imports of these files from `instrumentation.ts`. - -## Step 8: Instrument Vercel Cron Jobs (Optional) +## Step 6: Instrument Vercel Cron Jobs (Optional) You can automatically create [Cron Monitors](/product/crons/) in Sentry if you have configured [Vercel cron jobs](https://vercel.com/docs/cron-jobs). @@ -592,7 +455,7 @@ Automatic Vercel cron jobs instrumentation currently only supports the Pages Rou -## Step 9: Capture React Component Names (Optional) +## Step 7: Capture React Component Names (Optional) You can capture React component names to see which component a user clicked on in Sentry features like Session Replay. Update `withSentryConfig` in your `next.config.(js|mjs)` file with the following option: @@ -613,7 +476,7 @@ module.exports = withSentryConfig(nextConfig, { }); ``` -## Step 10: Verify +## Step 8: Verify From b7834517ba10486ef8aa3592cefbcbcaea74ec4a Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Mon, 14 Apr 2025 10:51:48 +0200 Subject: [PATCH 2/4] update withServerActionInstrumentation example --- docs/platforms/javascript/common/apis.mdx | 40 +++++++++++------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 0d46b1ee4cc15..3f8c754e5078a 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -1094,29 +1094,29 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent import { headers } from "next/headers"; export default function ServerComponent() { - async function myServerAction(formData: FormData) { - "use server"; - return await Sentry.withServerActionInstrumentation( - "myServerAction", // The name you want to associate this Server Action with in Sentry - { - formData, // Optionally pass in the form data - headers: headers(), // Optionally pass in headers - recordResponse: true, // Optionally record the server action response - }, - async () => { - // ... Your Server Action code + async function myServerAction(formData: FormData) { + "use server"; + return await Sentry.withServerActionInstrumentation( + "myServerAction", // The name you want to associate this Server Action with in Sentry + { + formData, // Optionally pass in the form data + headers: await headers(), // Optionally pass in headers + recordResponse: true, // Optionally record the server action response + }, + async () => { + // ... Your Server Action code - return { name: "John Doe" }; + return { name: "John Doe" }; + } + ); } - ); - } - return ( -
- - -
- ); + return ( +
+ + +
+ ); } ``` From 8ff49c70f4ef8597aab42f128c88ff9a230f51ee Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 17 Apr 2025 07:30:19 +0200 Subject: [PATCH 3/4] PR feedback: formatting updates --- docs/platforms/javascript/common/apis.mdx | 43 +++++++++++++++++------ 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 3f8c754e5078a..2a0eed0b1192e 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -1083,7 +1083,11 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent >`} > To instrument Next.js Server Actions, wrap their content in `withServerActionInstrumentation`, along with a name to describe your server action. You can optionally pass form data and headers to record them, and configure the wrapper to record the Server Action responses. @@ -1127,7 +1131,10 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent Instrument the provided API route handler with Sentry for error and performance monitoring. This function wraps the handler exported from the @@ -1137,7 +1144,9 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent Instrument a `getInitialProps` function with Sentry error and performance monitoring by creating and returning a wrapped version of the function. @@ -1145,7 +1154,10 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent Instrument a `getServerSideProps` function with Sentry error and performance monitoring by creating and returning a wrapped version of the function. @@ -1153,7 +1165,10 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent , + _parameterizedRoute: string + ): GetStaticProps`} > Instrument a `getStaticProps` function with Sentry error and performance monitoring by creating and returning a wrapped version of the function. @@ -1161,27 +1176,33 @@ Wraps a callback with a cron monitor check in. The check in will be sent to Sent - Instrument a `getInitialProps` function in a custom error page ("_error.js") + Instrument a `getInitialProps` function in a custom error page (`_error.js`) with Sentry error and performance monitoring by creating and returning a wrapped version of the function. - Instrument a `getInitialProps` function in a custom app ("_app.js") with + Instrument a `getInitialProps` function in a custom app (`_app.js`) with Sentry error and performance monitoring by creating and returning a wrapped version of the function. - Instrument a `getInitialProps` function in a custom document ("_document.js") + Instrument a `getInitialProps` function in a custom document (`_document.js`) with Sentry error and performance monitoring by creating and returning a wrapped version of the function. From 95c49615b7c6d7a46ec695e0282ea8492407957e Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 24 Apr 2025 12:28:27 +0200 Subject: [PATCH 4/4] update next steps for instrumenting server actions --- docs/platforms/javascript/guides/nextjs/index.mdx | 1 + .../javascript/guides/nextjs/manual-setup.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index d3f5ab35ea36b..269453e27751c 100644 --- a/docs/platforms/javascript/guides/nextjs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/index.mdx @@ -71,6 +71,7 @@ At this point, you should have integrated Sentry into your Next.js application a Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: +- Learn about [instrumenting Next.js server actions](/platforms/javascript/guides/nextjs/apis/#server-actions) - Learn how to [manually capture errors](/platforms/javascript/guides/nextjs/usage/) - Continue to [customize your configuration](/platforms/javascript/guides/nextjs/configuration/) - Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx index 5a25f62d3a3ae..fef4e39593acb 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx @@ -99,12 +99,12 @@ import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: "___PUBLIC_DSN___", - + // Adds request headers and IP for users, for more info visit: // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii sendDefaultPii: true, // ___PRODUCT_OPTION_START___ performance - + // Set tracesSampleRate to 1.0 to capture 100% // of transactions for tracing. // We recommend adjusting this value in production @@ -139,7 +139,7 @@ import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: "___PUBLIC_DSN___", - + // Adds request headers and IP for users, for more info visit: // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii sendDefaultPii: true, @@ -166,7 +166,7 @@ import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: "___PUBLIC_DSN___", - + // Adds request headers and IP for users, for more info visit: // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii sendDefaultPii: true, @@ -584,7 +584,7 @@ At this point, you should have integrated Sentry into your Next.js application a Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: -- Instrument Next.js server actions +- Learn about [instrumenting Next.js server actions](/platforms/javascript/guides/nextjs/apis/#server-actions) - Configure [server-side auto-instrumentation](/platforms/javascript/guides/nextjs/configuration/build/#nextjs-specific-options) - Learn how to [manually capture errors](/platforms/javascript/guides/nextjs/usage/) - Continue to [customize your configuration](/platforms/javascript/guides/nextjs/configuration/)