diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 7627cf0dc6810f..2a0eed0b1192e3 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,134 @@ 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: await 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. + + +, + _parameterizedRoute: string + ): GetStaticProps`} +> + 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/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index d3f5ab35ea36b1..269453e27751ca 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 7833572146c572..fef4e39593acb4 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, @@ -216,6 +216,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. @@ -371,46 +380,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: await 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. @@ -452,7 +422,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. @@ -482,114 +452,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). @@ -613,7 +476,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: @@ -634,7 +497,7 @@ module.exports = withSentryConfig(nextConfig, { }); ``` -## Step 10: Verify +## Step 8: Verify @@ -721,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/)