Repository: vercel/next.js
Pull request: Add more debug logs to `'use cache'` wrapper

The cache handlers are generally responsible for adding debug logs to their methods, see
`packages/next/src/server/lib/cache-handlers/default.ts` for reference. However, the `'use cache'` wrapper in
`packages/next/src/server/use-cache/use-cache-wrapper.ts` also adds a few debug logs of its own that pertain to logic that is specific to the wrapper itself, e.g. when discarding cache entries because of tag revalidation. With this PR, we're now also logging cache hits and misses in the Resume Data Cache, as well as when entries are omitted from the static or runtime shell due to their revalidate, expire or stale values.

Docs: https://nextjs.org/docs/app/api-reference/directives/use-cache#verbose-logging

Changed files:
filename: packages/next/src/server/use-cache/use-cache-wrapper.ts
patch: @@ -1256,6 +1256,20 @@ export async function cache(
               // generating static pages for such data. It's better to leave
               // a dynamic hole that can be filled in during the resume with
               // a potentially cached entry.
+              if (existingEntry.revalidate === 0) {
+                debug?.(
+                  'omitting entry',
+                  serializedCacheKey,
+                  'from static shell due to revalidate: 0'
+                )
+              } else {
+                debug?.(
+                  'omitting entry',
+                  serializedCacheKey,
+                  'from static shell due to short expire value:',
+                  existingEntry.expire
+                )
+              }
               if (cacheSignal) {
                 cacheSignal.endRead()
               }
@@ -1307,6 +1321,12 @@ export async function cache(
               // stale in less then 30 seconds, we consider this cache entry
               // dynamic as it's not worth prefetching. It's better to leave
               // a dynamic hole that can be filled during the navigation.
+              debug?.(
+                'omitting entry',
+                serializedCacheKey,
+                'from runtime shell due to short stale value:',
+                existingEntry.stale
+              )
               if (cacheSignal) {
                 cacheSignal.endRead()
               }
@@ -1344,6 +1364,8 @@ export async function cache(
         }
       }
 
+      debug?.('Resume Data Cache entry found', serializedCacheKey)
+
       // We want to make sure we only propagate cache life & tags if the
       // entry was *not* omitted from the prerender. So we only do this
       // after the above early returns.
@@ -1360,6 +1382,8 @@ export async function cache(
         stream = streamA
       }
     } else {
+      debug?.('Resume Data Cache entry not found', serializedCacheKey)
+
       if (cacheSignal) {
         cacheSignal.endRead()
       }
@@ -1481,6 +1505,20 @@ export async function cache(
           // pages for such data. It's better to leave a dynamic hole that
           // can be filled in during the resume with a potentially cached
           // entry.
+          if (entry.revalidate === 0) {
+            debug?.(
+              'omitting entry',
+              serializedCacheKey,
+              'from static shell due to revalidate: 0'
+            )
+          } else {
+            debug?.(
+              'omitting entry',
+              serializedCacheKey,
+              'from static shell due to short expire value:',
+              entry.expire
+            )
+          }
           if (cacheSignal) {
             cacheSignal.endRead()
           }