Unverified Commit 4ee00d4f authored by Wyatt Johnson's avatar Wyatt Johnson Committed by GitHub

[PPR] Dynamic API Debugging (#61798)

<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:

## For Contributors

### Improving Documentation

- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide

### Adding or Updating Examples

- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md

### Fixing a bug

- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Adding a feature

- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md


## For Maintainers

- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Closes NEXT-
Fixes #

-->

### What?

This adds dynamic usage logging when the `__nextppronly` query parameter
is set and partial prerendering has been enabled. This will print the
stack trace for the accesses for all Dynamic API's that were called.
This includes those API's that were called during the flight render if
they were called before the static shell was ready.

### Why?

To take the most advantage of partial prerendering, it's important to
track where Dynamic API's are called so developers can determine what
has caused part of the component tree not to be included in the static
shell. This also helps debug situations where the error thrown by
Dynamic API's (used internally for tracking and interruption) are caught
but not re-thrown, but due to the implementation of the flight renderer
provided by React, we are unable to distinguish between errors that are
swallowed by user code or by the flight renderer.

### How?

Instead of using a boolean to track **if** a dynamic API was used, this
actually captures the stack at the callsite, allowing developers to find
the location in the codebase that invoked it.

Closes NEXT-2399
parent d01a6219
...@@ -1366,7 +1366,6 @@ export async function buildAppStaticPaths({ ...@@ -1366,7 +1366,6 @@ export async function buildAppStaticPaths({
incrementalCache, incrementalCache,
supportsDynamicHTML: true, supportsDynamicHTML: true,
isRevalidate: false, isRevalidate: false,
isBot: false,
// building static paths should never postpone // building static paths should never postpone
experimental: { ppr: false }, experimental: { ppr: false },
}, },
......
...@@ -100,6 +100,7 @@ import { getStackWithoutErrorMessage } from '../../lib/format-server-error' ...@@ -100,6 +100,7 @@ import { getStackWithoutErrorMessage } from '../../lib/format-server-error'
import { import {
usedDynamicAPIs, usedDynamicAPIs,
createPostponedAbortSignal, createPostponedAbortSignal,
formatDynamicAPIAccesses,
} from './dynamic-rendering' } from './dynamic-rendering'
import { import {
getClientComponentLoaderMetrics, getClientComponentLoaderMetrics,
...@@ -1355,6 +1356,21 @@ async function renderToHTMLOrFlightImpl( ...@@ -1355,6 +1356,21 @@ async function renderToHTMLOrFlightImpl(
const buildFailingError = const buildFailingError =
digestErrorsMap.size > 0 ? digestErrorsMap.values().next().value : null digestErrorsMap.size > 0 ? digestErrorsMap.values().next().value : null
// If we're debugging partial prerendering, print all the dynamic API accesses
// that occurred during the render.
if (
staticGenerationStore.prerenderState &&
usedDynamicAPIs(staticGenerationStore.prerenderState) &&
staticGenerationStore.prerenderState?.isDebugSkeleton
) {
warn('The following dynamic usage was detected:')
for (const access of formatDynamicAPIAccesses(
staticGenerationStore.prerenderState
)) {
warn(access)
}
}
if (!flightDataResolver) { if (!flightDataResolver) {
throw new Error( throw new Error(
'Invariant: Flight data resolver is missing when generating static HTML' 'Invariant: Flight data resolver is missing when generating static HTML'
...@@ -1422,7 +1438,6 @@ export const renderToHTMLOrFlight: AppPageRender = ( ...@@ -1422,7 +1438,6 @@ export const renderToHTMLOrFlight: AppPageRender = (
{ {
urlPathname: pathname, urlPathname: pathname,
renderOpts, renderOpts,
postpone: React.unstable_postpone,
}, },
(staticGenerationStore) => (staticGenerationStore) =>
renderToHTMLOrFlightImpl(req, res, pagePath, query, renderOpts, { renderToHTMLOrFlightImpl(req, res, pagePath, query, renderOpts, {
......
...@@ -30,12 +30,39 @@ import { getPathname } from '../../lib/url' ...@@ -30,12 +30,39 @@ import { getPathname } from '../../lib/url'
const hasPostpone = typeof React.unstable_postpone === 'function' const hasPostpone = typeof React.unstable_postpone === 'function'
// Stores dynamic reasons used during a render type DynamicAccess = {
export type PrerenderState = { hasDynamic: boolean } /**
* If debugging, this will contain the stack trace of where the dynamic access
* occurred. This is used to provide more information to the user about why
* their page is being rendered dynamically.
*/
stack?: string
export function createPrerenderState(): PrerenderState { /**
* The expression that was accessed dynamically.
*/
expression: string
}
// Stores dynamic reasons used during a render.
export type PrerenderState = {
/**
* When true, stack information will also be tracked during dynamic access.
*/
readonly isDebugSkeleton: boolean | undefined
/**
* The dynamic accesses that occurred during the render.
*/
readonly dynamicAccesses: DynamicAccess[]
}
export function createPrerenderState(
isDebugSkeleton: boolean | undefined
): PrerenderState {
return { return {
hasDynamic: false, isDebugSkeleton,
dynamicAccesses: [],
} }
} }
...@@ -168,12 +195,57 @@ function postponeWithTracking( ...@@ -168,12 +195,57 @@ function postponeWithTracking(
`Route ${pathname} needs to bail out of prerendering at this point because it used ${expression}. ` + `Route ${pathname} needs to bail out of prerendering at this point because it used ${expression}. ` +
`React throws this special object to indicate where. It should not be caught by ` + `React throws this special object to indicate where. It should not be caught by ` +
`your own try/catch. Learn more: https://nextjs.org/docs/messages/ppr-caught-error` `your own try/catch. Learn more: https://nextjs.org/docs/messages/ppr-caught-error`
prerenderState.hasDynamic = true
prerenderState.dynamicAccesses.push({
// When we aren't debugging, we don't need to create another error for the
// stack trace.
stack: prerenderState.isDebugSkeleton ? new Error().stack : undefined,
expression,
})
React.unstable_postpone(reason) React.unstable_postpone(reason)
} }
export function usedDynamicAPIs(prerenderState: PrerenderState): boolean { export function usedDynamicAPIs(prerenderState: PrerenderState): boolean {
return prerenderState.hasDynamic === true return prerenderState.dynamicAccesses.length > 0
}
export function formatDynamicAPIAccesses(
prerenderState: PrerenderState
): string[] {
return prerenderState.dynamicAccesses
.filter(
(access): access is Required<DynamicAccess> =>
typeof access.stack === 'string' && access.stack.length > 0
)
.map(({ expression, stack }) => {
stack = stack
.split('\n')
// Remove the "Error: " prefix from the first line of the stack trace as
// well as the first 4 lines of the stack trace which is the distance
// from the user code and the `new Error().stack` call.
.slice(4)
.filter((line) => {
// Exclude Next.js internals from the stack trace.
if (line.includes('node_modules/next/')) {
return false
}
// Exclude anonymous functions from the stack trace.
if (line.includes(' (<anonymous>)')) {
return false
}
// Exclude Node.js internals from the stack trace.
if (line.includes(' (node:')) {
return false
}
return true
})
.join('\n')
return `Dynamic API Usage Debug - ${expression}:\n${stack}`
})
} }
function assertPostpone() { function assertPostpone() {
......
...@@ -157,6 +157,11 @@ export interface RenderOptsPartial { ...@@ -157,6 +157,11 @@ export interface RenderOptsPartial {
swrDelta: SwrDelta | undefined swrDelta: SwrDelta | undefined
} }
postponed?: string postponed?: string
/**
* When true, only the skeleton of the PPR page will be rendered. This will
* also enable other debugging features such as logging.
*/
isDebugPPRSkeleton?: boolean
isStaticGeneration?: boolean isStaticGeneration?: boolean
} }
......
...@@ -2,27 +2,26 @@ import type { AsyncStorageWrapper } from './async-storage-wrapper' ...@@ -2,27 +2,26 @@ import type { AsyncStorageWrapper } from './async-storage-wrapper'
import type { StaticGenerationStore } from '../../client/components/static-generation-async-storage.external' import type { StaticGenerationStore } from '../../client/components/static-generation-async-storage.external'
import type { AsyncLocalStorage } from 'async_hooks' import type { AsyncLocalStorage } from 'async_hooks'
import type { IncrementalCache } from '../lib/incremental-cache' import type { IncrementalCache } from '../lib/incremental-cache'
import type { RenderOptsPartial } from '../app-render/types'
import { createPrerenderState } from '../../server/app-render/dynamic-rendering' import { createPrerenderState } from '../../server/app-render/dynamic-rendering'
import type { FetchMetric } from '../base-http' import type { FetchMetric } from '../base-http'
export type StaticGenerationContext = { export type StaticGenerationContext = {
urlPathname: string urlPathname: string
postpone?: (reason: string) => never
renderOpts: { renderOpts: {
originalPathname?: string
incrementalCache?: IncrementalCache incrementalCache?: IncrementalCache
supportsDynamicHTML: boolean
isRevalidate?: boolean
isOnDemandRevalidate?: boolean isOnDemandRevalidate?: boolean
isBot?: boolean
nextExport?: boolean
fetchCache?: StaticGenerationStore['fetchCache'] fetchCache?: StaticGenerationStore['fetchCache']
isDraftMode?: boolean
isServerAction?: boolean isServerAction?: boolean
waitUntil?: Promise<any> waitUntil?: Promise<any>
experimental: { ppr: boolean; missingSuspenseWithCSRBailout?: boolean } experimental: { ppr: boolean; missingSuspenseWithCSRBailout?: boolean }
/**
* Fetch metrics attached in patch-fetch.ts
**/
fetchMetrics?: FetchMetric[]
/** /**
* A hack around accessing the store value outside the context of the * A hack around accessing the store value outside the context of the
* request. * request.
...@@ -32,9 +31,17 @@ export type StaticGenerationContext = { ...@@ -32,9 +31,17 @@ export type StaticGenerationContext = {
*/ */
// TODO: remove this when we resolve accessing the store outside the execution context // TODO: remove this when we resolve accessing the store outside the execution context
store?: StaticGenerationStore store?: StaticGenerationStore
/** Fetch metrics attached in patch-fetch.ts */ } & Pick<
fetchMetrics?: FetchMetric[] // Pull some properties from RenderOptsPartial so that the docs are also
} // mirrored.
RenderOptsPartial,
| 'originalPathname'
| 'supportsDynamicHTML'
| 'isRevalidate'
| 'nextExport'
| 'isDraftMode'
| 'isDebugPPRSkeleton'
>
} }
export const StaticGenerationAsyncStorageWrapper: AsyncStorageWrapper< export const StaticGenerationAsyncStorageWrapper: AsyncStorageWrapper<
...@@ -70,7 +77,7 @@ export const StaticGenerationAsyncStorageWrapper: AsyncStorageWrapper< ...@@ -70,7 +77,7 @@ export const StaticGenerationAsyncStorageWrapper: AsyncStorageWrapper<
const prerenderState: StaticGenerationStore['prerenderState'] = const prerenderState: StaticGenerationStore['prerenderState'] =
isStaticGeneration && renderOpts.experimental.ppr isStaticGeneration && renderOpts.experimental.ppr
? createPrerenderState() ? createPrerenderState(renderOpts.isDebugPPRSkeleton)
: null : null
const store: StaticGenerationStore = { const store: StaticGenerationStore = {
......
...@@ -2147,7 +2147,7 @@ export default abstract class Server<ServerOptions extends Options = Options> { ...@@ -2147,7 +2147,7 @@ export default abstract class Server<ServerOptions extends Options = Options> {
// allow debugging the skeleton in dev with PPR // allow debugging the skeleton in dev with PPR
// instead of continuing to resume stream right away // instead of continuing to resume stream right away
const debugPPRSkeleton = Boolean( const isDebugPPRSkeleton = Boolean(
this.nextConfig.experimental.ppr && this.nextConfig.experimental.ppr &&
(this.renderOpts.dev || this.experimentalTestProxy) && (this.renderOpts.dev || this.experimentalTestProxy) &&
query.__nextppronly query.__nextppronly
...@@ -2227,12 +2227,13 @@ export default abstract class Server<ServerOptions extends Options = Options> { ...@@ -2227,12 +2227,13 @@ export default abstract class Server<ServerOptions extends Options = Options> {
postponed, postponed,
} }
if (debugPPRSkeleton) { if (isDebugPPRSkeleton) {
supportsDynamicHTML = false supportsDynamicHTML = false
renderOpts.nextExport = true renderOpts.nextExport = true
renderOpts.supportsDynamicHTML = false renderOpts.supportsDynamicHTML = false
renderOpts.isStaticGeneration = true renderOpts.isStaticGeneration = true
renderOpts.isRevalidate = true renderOpts.isRevalidate = true
renderOpts.isDebugPPRSkeleton = true
} }
// Legacy render methods will return a render result that needs to be // Legacy render methods will return a render result that needs to be
...@@ -2893,12 +2894,10 @@ export default abstract class Server<ServerOptions extends Options = Options> { ...@@ -2893,12 +2894,10 @@ export default abstract class Server<ServerOptions extends Options = Options> {
} }
} }
if (debugPPRSkeleton) { // If we're debugging the skeleton, we should just serve the HTML without
return { // resuming the render. The returned HTML will be the static shell.
type: 'html', if (isDebugPPRSkeleton) {
body, return { type: 'html', body, revalidate: 0 }
revalidate: 0,
}
} }
// This request has postponed, so let's create a new transformer that the // This request has postponed, so let's create a new transformer that the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment