Add cache status attributes to OpenTelemetry spans for Next.js fetch requests

[dmgawel]

Goals

• Provide visibility into cache behavior for fetch requests through OpenTelemetry spans
• Enable developers to monitor and debug caching performance in production environments
• Add standardized cache-related attributes that align with OpenTelemetry conventions
• Improve observability of Next.js's advanced caching mechanisms

Non-Goals

• Modify the core caching logic or behavior of Next.js
• Add performance overhead to fetch operations
• Change existing OpenTelemetry span structure or break backward compatibility
• Implement cache metrics beyond what's needed for span attributes

Background

Next.js provides advanced caching capabilities, including fetch requests caching.

Currently, Next.js generates OpenTelemetry spans for fetch requests (AppRender.fetch) but these spans lack visibility into whether requests were served from cache or fetched from origin. This makes it difficult for developers to:

• Debug caching issues in production
• Monitor cache hit rates
• Understand performance characteristics of their applications
• Validate that caching is working as expected

Proposal

Add three new attributes to fetch spans in packages/next/src/server/lib/patch-fetch.ts:

1. next.cache.status

Indicates the cache outcome for the request:

• hit - Request was served from cache
• miss - Request was not found in cache and fetched from origin
• skip - Caching was disabled for this request
• hmr - Request was served from HMR cache during development

2. next.cache.reason

Provides context for the caching behavior:

• fetchCache = force-cache - Explicit cache configuration
• revalidate: 60 - Time-based revalidation
• Other descriptive reasons based on Next.js caching logic

3. next.cache.revalidate

The revalidate value used for the request:

• Number of seconds for time-based revalidation
• undefined if no revalidate value was set

Implementation Details

• Attributes are set on the existing fetch span using span.setAttributes()
• Only applied to non-internal fetch requests to avoid noise
• Integrated with existing cache decision logic (it's all already available as variables)
• Minimal performance impact as attributes are set during existing cache operations

This enhancement provides essential observability into Next.js's caching behavior without changing core functionality or adding significant overhead.