Skip to content

Commit a72b2d8

Browse files
feat(nuxt): Instrument Nitro v3 cache storage (#25951)
**Why:** Starting with the RC, Nitro v3 runs `defineCachedFunction` / `defineCachedHandler` (and `cache` route rules) on an `ocache` storage. That storage only goes through KV storage when the `kv` cache driver is set, so with the default `memory` driver (and with `fs`) our KV driver instrumentation never sees cache reads or writes, and no `cache.*` spans are produced. Nitro doesn't offer a tracing channel for its cache, and the storage instance is private to Nitro's runtime. It is created in the build-time `#nitro/virtual/cache` module, though, so a bundler transform wraps that module's `createCacheStorage` export and the storage gets patched in place. It has to be patched in place because `ocache` also reads `binary` and `maxEntryBytes` from the storage object. The `kv` driver is skipped because the existing KV instrumentation already covers it. `cache.hit` comes from the stored entry: it must have a value, be unexpired, and not be marked `stale`. This PR also undoes the `kv` workaround in the nuxt-5 E2E app, so the default driver is what gets tested. **How to review:** Start with `cacheStorageInstrumentationPlugin` in `vite/storageConfig.ts`, then `instrumentCacheStorage` in `runtime/utils/instrumentStorage.ts`. The span wrapper is now shared with the KV driver instrumentation, and KV behavior is unchanged. **Unsure about:** The transform matches the exact `export const createCacheStorage =` line that Nitro generates. If Nitro changes that template, the transform does nothing (no crash), but cache spans would disappear again. Is that acceptable, or should we push upstream for a tracing channel or hook in Nitro/ocache? Note this is stacked on #25949. <!-- junior-request-attribution:start --> via **Francesco Gringl-Novy**. <!-- junior-request-attribution:end --> <!-- junior-session-footer:start --> <!-- junior-conversation-id:slack%3AD0CA8FXFXAS%3A1793366214.663899 --> -- [View Session](https://junior-prod.sentry.dev/conversations/slack%3AD0CA8FXFXAS%3A1793366214.663899) [[Sentry]](https://sentry.sentry.io/explore/conversations/slack%3AD0CA8FXFXAS%3A1793366214.663899/?project=4510944073809921) <!-- junior-session-footer:end --> --------- Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Francesco Gringl-Novy <francesco.novy@sentry.io>
1 parent 73e928a commit a72b2d8

8 files changed

Lines changed: 404 additions & 48 deletions

File tree

‎dev-packages/e2e-tests/test-applications/nuxt-5/nuxt.config.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,7 @@ export default defineNuxtConfig({
2828
},
2929
},
3030
nitro: {
31-
// Nitro v3 only routes `defineCachedFunction`/`defineCachedHandler` through KV storage (which the SDK
32-
// instruments) with the `kv` cache driver. The default `memory` driver bypasses KV storage entirely.
33-
cache: { driver: 'kv' },
31+
...(process.env.E2E_TEST_CACHE_DRIVER && { cache: { driver: process.env.E2E_TEST_CACHE_DRIVER } }),
3432
experimental: {
3533
database: true,
3634
},

‎dev-packages/e2e-tests/test-applications/nuxt-5/package.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,9 @@
1818
"test:assert": "pnpm test:prod && pnpm test:dev",
1919
"test:build:tunnel-basepath": "pnpm install && E2E_TEST_TUNNEL=1 E2E_TEST_BASE_PATH=/app pnpm build",
2020
"test:assert:tunnel-basepath": "E2E_TEST_TUNNEL=1 E2E_TEST_BASE_PATH=/app TEST_ENV=production playwright test tunnel",
21-
"test:assert:tunnel-dev": "E2E_TEST_TUNNEL=1 TEST_ENV=development playwright test tunnel"
21+
"test:assert:tunnel-dev": "E2E_TEST_TUNNEL=1 TEST_ENV=development playwright test tunnel",
22+
"test:build:kv-cache": "pnpm install && E2E_TEST_CACHE_DRIVER=kv pnpm build",
23+
"test:assert:kv-cache": "E2E_TEST_CACHE_DRIVER=kv TEST_ENV=production playwright test cache"
2224
},
2325
"//": [
2426
"Currently, we need to install the Nuxt nightlies as those contain Nuxt v5",
@@ -54,6 +56,11 @@
5456
"build-command": "pnpm install",
5557
"assert-command": "pnpm test:assert:tunnel-dev",
5658
"label": "nuxt-5 (tunnel-dev)"
59+
},
60+
{
61+
"build-command": "pnpm test:build:kv-cache",
62+
"assert-command": "pnpm test:assert:kv-cache",
63+
"label": "nuxt-5 (kv-cache)"
5764
}
5865
]
5966
}

‎dev-packages/e2e-tests/test-applications/nuxt-5/tests/cache.test.ts‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
11
import { expect, test } from '@playwright/test';
22
import { collectStreamedSpansUntilSegment } from '@sentry-internal/test-utils';
33

4+
// Nitro v3 only routes cached functions and handlers through KV storage with the `kv` cache driver,
5+
// so the default (`memory`) driver is traced through ocache's storage instead.
6+
const isKvCacheDriver = process.env.E2E_TEST_CACHE_DRIVER === 'kv';
7+
const GET_METHOD = isKvCacheDriver ? 'getItem' : 'get';
8+
const SET_METHOD = isKvCacheDriver ? 'setItem' : 'set';
9+
const STORAGE_ATTRIBUTES = isKvCacheDriver
10+
? { 'db.collection.name': { type: 'string', value: expect.stringMatching(/^(cache)?$/) } }
11+
: { 'db.system.name': { type: 'string', value: 'memory' } };
12+
413
test.describe('Cache Instrumentation', () => {
514
const SEMANTIC_ATTRIBUTE_CACHE_KEY = 'cache.key';
615
const SEMANTIC_ATTRIBUTE_CACHE_HIT = 'cache.hit';
@@ -34,8 +43,8 @@ test.describe('Cache Instrumentation', () => {
3443

3544
const getCacheKey = (span: (typeof allCacheSpans)[number]) => span.attributes[SEMANTIC_ATTRIBUTE_CACHE_KEY]?.value;
3645

37-
// Test getItem spans for cachedFunction - should have both cache miss and cache hit
38-
const getItemSpans = findSpansByMethod('getItem');
46+
// Test read spans for cachedFunction - should have both cache miss and cache hit
47+
const getItemSpans = findSpansByMethod(GET_METHOD);
3948
expect(getItemSpans.length).toBeGreaterThan(0);
4049

4150
// Find cache miss (first call to getCachedUser('123'))
@@ -51,8 +60,8 @@ test.describe('Cache Instrumentation', () => {
5160
'cache.operation': { type: 'string', value: 'get' },
5261
'sentry.origin': { type: 'string', value: 'auto.cache.nuxt' },
5362
[SEMANTIC_ATTRIBUTE_CACHE_HIT]: { type: 'boolean', value: false },
54-
'db.operation.name': { type: 'string', value: 'getItem' },
55-
'db.collection.name': { type: 'string', value: expect.stringMatching(/^(cache)?$/) },
63+
'db.operation.name': { type: 'string', value: GET_METHOD },
64+
...STORAGE_ATTRIBUTES,
5665
});
5766
}
5867

@@ -69,13 +78,13 @@ test.describe('Cache Instrumentation', () => {
6978
'cache.operation': { type: 'string', value: 'get' },
7079
'sentry.origin': { type: 'string', value: 'auto.cache.nuxt' },
7180
[SEMANTIC_ATTRIBUTE_CACHE_HIT]: { type: 'boolean', value: true },
72-
'db.operation.name': { type: 'string', value: 'getItem' },
73-
'db.collection.name': { type: 'string', value: expect.stringMatching(/^(cache)?$/) },
81+
'db.operation.name': { type: 'string', value: GET_METHOD },
82+
...STORAGE_ATTRIBUTES,
7483
});
7584
}
7685

77-
// Test setItem spans for cachedFunction - when cache miss occurs, value is set
78-
const setItemSpans = findSpansByMethod('setItem');
86+
// Test write spans for cachedFunction - when cache miss occurs, value is set
87+
const setItemSpans = findSpansByMethod(SET_METHOD);
7988
expect(setItemSpans.length).toBeGreaterThan(0);
8089

8190
const cacheSetSpan = setItemSpans.find(
@@ -86,8 +95,8 @@ test.describe('Cache Instrumentation', () => {
8695
'sentry.op': { type: 'string', value: 'cache.put' },
8796
'cache.operation': { type: 'string', value: 'put' },
8897
'sentry.origin': { type: 'string', value: 'auto.cache.nuxt' },
89-
'db.operation.name': { type: 'string', value: 'setItem' },
90-
'db.collection.name': { type: 'string', value: expect.stringMatching(/^(cache)?$/) },
98+
'db.operation.name': { type: 'string', value: SET_METHOD },
99+
...STORAGE_ATTRIBUTES,
91100
});
92101
}
93102

‎packages/nuxt/src/runtime/utils/instrumentStorage.ts‎

Lines changed: 119 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,9 @@ import {
1414
captureException,
1515
debug,
1616
getClient,
17+
handleCallbackErrors,
1718
hasSpanStreamingEnabled,
1819
isObjectLike,
19-
SPAN_STATUS_ERROR,
20-
SPAN_STATUS_OK,
2120
type SpanAttributes,
2221
startSpan,
2322
type StartSpanOptions,
@@ -32,6 +31,7 @@ import type { Driver, Storage } from 'unstorage';
3231
interface CacheEntry<T = unknown> {
3332
value?: T;
3433
expires?: number;
34+
stale?: boolean;
3535
}
3636

3737
/**
@@ -180,33 +180,119 @@ function createMethodWrapper(
180180

181181
debug.log(`[storage] Running method: "${methodName}" on driver: "${driver.name ?? 'unknown'}"`);
182182

183-
return startSpan(options, async span => {
184-
try {
185-
const result = await target.apply(thisArg, args);
186-
span.setStatus({ code: SPAN_STATUS_OK });
187-
188-
if (CACHE_HIT_METHODS.has(methodName)) {
189-
span.setAttribute(CACHE_HIT, resolveCacheHit(methodName, args[0], result));
190-
}
191-
192-
return result;
193-
} catch (error) {
194-
span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
195-
captureException(error, {
196-
mechanism: {
197-
handled: false,
198-
type: options.attributes?.[SENTRY_ORIGIN],
199-
},
200-
});
201-
202-
// Re-throw the error to be handled by the caller
203-
throw error;
204-
} finally {
205-
await flushIfServerless();
183+
return traceCacheOperation(
184+
options,
185+
() => target.apply(thisArg, args),
186+
CACHE_HIT_METHODS.has(methodName) ? result => resolveCacheHit(methodName, args[0], result) : undefined,
187+
);
188+
},
189+
});
190+
}
191+
192+
/**
193+
* Runs a cache operation in a span, optionally recording whether the result was a cache hit.
194+
*/
195+
function traceCacheOperation(
196+
options: StartSpanOptions,
197+
operation: () => unknown,
198+
getCacheHit?: (result: unknown) => boolean,
199+
): Promise<unknown> {
200+
return handleCallbackErrors(
201+
() =>
202+
startSpan(options, async span => {
203+
const result = await operation();
204+
205+
if (getCacheHit) {
206+
span.setAttribute(CACHE_HIT, getCacheHit(result));
206207
}
208+
209+
return result;
210+
}),
211+
error => {
212+
captureException(error, {
213+
mechanism: {
214+
handled: false,
215+
type: 'auto.cache.nuxt',
216+
},
207217
});
208218
},
209-
});
219+
() => {
220+
void flushIfServerless();
221+
},
222+
);
223+
}
224+
225+
/**
226+
* The storage behind Nitro v3's `defineCachedFunction` and `defineCachedHandler` (an `ocache` storage).
227+
*/
228+
interface NitroCacheStorage {
229+
get(key: string): unknown;
230+
set(key: string, value: unknown, opts?: { ttl?: number }): unknown;
231+
}
232+
233+
/**
234+
* Instruments the storage that Nitro v3 caches functions and handlers in.
235+
*
236+
* Unlike Nitro v2, Nitro v3 only writes its cache to KV storage with the `kv` cache driver, so the KV
237+
* driver instrumentation doesn't see the default `memory` or the `fs` cache driver.
238+
* The storage is patched in place because `ocache` reads other properties, like `binary`, from it.
239+
*/
240+
export function instrumentCacheStorage<T extends NitroCacheStorage>(
241+
storage: MaybeInstrumented<T>,
242+
driverName: string,
243+
): T {
244+
if (storage.__sentry_instrumented__) {
245+
return storage;
246+
}
247+
248+
const originalGet = storage.get.bind(storage);
249+
const originalSet = storage.set.bind(storage);
250+
251+
storage.get = (key: string) =>
252+
traceCacheOperation(
253+
createCacheStorageSpanStartOptions('get', CACHE_GET, key, driverName),
254+
() => originalGet(key),
255+
isCacheEntryHit,
256+
);
257+
258+
storage.set = (key: string, value: unknown, opts?: { ttl?: number }) =>
259+
// `ocache` deletes an entry by setting it to `null`
260+
traceCacheOperation(
261+
createCacheStorageSpanStartOptions('set', value == null ? CACHE_REMOVE : CACHE_PUT, key, driverName),
262+
() => originalSet(key, value, opts),
263+
);
264+
265+
storage.__sentry_instrumented__ = true;
266+
267+
return storage;
268+
}
269+
270+
function createCacheStorageSpanStartOptions(
271+
methodName: keyof NitroCacheStorage,
272+
cacheOperation: typeof CACHE_GET | typeof CACHE_PUT | typeof CACHE_REMOVE,
273+
key: string,
274+
driverName: string,
275+
): StartSpanOptions {
276+
const client = getClient();
277+
return {
278+
// With span streaming, span names have to be low cardinality, so we can't fall back to the cache key.
279+
name: client && hasSpanStreamingEnabled(client) ? cacheOperation : key,
280+
attributes: {
281+
[SENTRY_OP]: cacheOperation,
282+
[CACHE_OPERATION]: CACHE_OPERATION_NAMES[cacheOperation],
283+
[SENTRY_ORIGIN]: 'auto.cache.nuxt',
284+
[CACHE_KEY]: key,
285+
[DB_OPERATION_NAME]: methodName,
286+
[DB_SYSTEM_NAME]: driverName,
287+
},
288+
};
289+
}
290+
291+
/**
292+
* `ocache` storage holds full cache entries, so a stored but expired or stale entry is a miss.
293+
*/
294+
function isCacheEntryHit(entry: unknown): boolean {
295+
return isObjectLike(entry) && !(entry as CacheEntry).stale && isFreshCacheEntry(entry);
210296
}
211297

212298
/**
@@ -338,13 +424,7 @@ function validateCacheEntry(
338424
key: string,
339425
entry: CacheEntry | CacheEntry<ResponseCacheEntry & { status: number }>,
340426
): boolean {
341-
if (entry.value == null) {
342-
return false;
343-
}
344-
345-
// Date.now is used by Nitro internally, so safe to use here.
346-
// https://github.com/nitrojs/nitro/blob/5508f71b77730e967fb131de817725f5aa7c4862/src/runtime/internal/cache.ts#L78
347-
if (Date.now() > (entry.expires || 0)) {
427+
if (!isFreshCacheEntry(entry)) {
348428
return false;
349429
}
350430

@@ -369,6 +449,12 @@ function validateCacheEntry(
369449
return true;
370450
}
371451

452+
function isFreshCacheEntry<T>(entry: CacheEntry<T>): entry is CacheEntry<T> & { value: NonNullable<T> } {
453+
// Date.now is used by Nitro internally, so safe to use here.
454+
// https://github.com/nitrojs/nitro/blob/5508f71b77730e967fb131de817725f5aa7c4862/src/runtime/internal/cache.ts#L78
455+
return entry.value != null && Date.now() <= (entry.expires || 0);
456+
}
457+
372458
/**
373459
* Checks if the cache entry is a response cache entry.
374460
*/

‎packages/nuxt/src/vite/nitroServer.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import {
1212
} from './addServerConfig';
1313
import { addDatabaseInstrumentation } from './databaseConfig';
1414
import { addMiddlewareImports, addMiddlewareInstrumentation } from './middlewareConfig';
15-
import { addStorageInstrumentation } from './storageConfig';
15+
import { addCacheStorageInstrumentation, addStorageInstrumentation } from './storageConfig';
1616
import { addRuntimeInjectionTraceDep, type ServerApi } from './utils';
1717

1818
type NitroModuleOptions = Omit<SentryNuxtModuleOptions, 'experimental_entrypointWrappedFunctions'> &
@@ -65,6 +65,10 @@ export function setupNitroServer(
6565

6666
addMiddlewareInstrumentation(nitro, isNitroV3);
6767

68+
if (isNitroV3) {
69+
addCacheStorageInstrumentation(nitro);
70+
}
71+
6872
if (deprecatedInjectMode) {
6973
setupDeprecatedInjectMode(nitro, deprecatedInjectMode, isNitroV3, serverConfigFile, moduleOptions);
7074
return;

‎packages/nuxt/src/vite/storageConfig.ts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
import { addNitroPlugin, createResolver } from '@nuxt/kit';
22
import type { Nuxt } from '@nuxt/schema';
3+
import type { Nitro } from 'nitropack/types';
4+
import type { InputPluginOption } from 'rollup';
35
import { addServerTemplate } from '../vendor/server-template';
46

7+
const NITRO_CACHE_VIRTUAL_MODULE_ID = '#nitro/virtual/cache';
8+
const CREATE_CACHE_STORAGE_EXPORT = 'export const createCacheStorage =';
9+
510
/**
611
* Prepares the storage config export to be used in the runtime storage instrumentation.
712
*/
@@ -23,3 +28,47 @@ export function addStorageInstrumentation(nuxt: Nuxt, isLegacyNitro: boolean): v
2328
addNitroPlugin(moduleDirResolver.resolve('./runtime/plugins/storage.server'));
2429
}
2530
}
31+
32+
/**
33+
* Instruments the storage behind Nitro v3's cached functions and handlers.
34+
*
35+
* Nitro v3 creates that storage in the `#nitro/virtual/cache` module, which is generated at build time and
36+
* can't be reached at runtime, so the module's `createCacheStorage` export is wrapped while bundling.
37+
*/
38+
export function addCacheStorageInstrumentation(nitro: Nitro): void {
39+
nitro.hooks.hook('rollup:before', (nitro, rollupConfig) => {
40+
if (!rollupConfig.plugins) {
41+
rollupConfig.plugins = [];
42+
}
43+
44+
if (!Array.isArray(rollupConfig.plugins)) {
45+
rollupConfig.plugins = [rollupConfig.plugins];
46+
}
47+
48+
rollupConfig.plugins.push(cacheStorageInstrumentationPlugin(nitro));
49+
});
50+
}
51+
52+
function cacheStorageInstrumentationPlugin(nitro: Nitro): InputPluginOption {
53+
const instrumentStoragePath = createResolver(import.meta.url).resolve('./runtime/utils/instrumentStorage');
54+
55+
return {
56+
name: 'sentry-nuxt-cache-storage-instrumentation',
57+
transform(code: string, id: string) {
58+
// The `kv` driver re-exports a KV-backed storage, which the storage plugin already instruments
59+
if (id !== NITRO_CACHE_VIRTUAL_MODULE_ID || !code.includes(CREATE_CACHE_STORAGE_EXPORT)) {
60+
return null;
61+
}
62+
63+
const driverName = (nitro.options as { cache?: { driver?: string } }).cache?.driver ?? 'memory';
64+
65+
return {
66+
code: `import { instrumentCacheStorage } from ${JSON.stringify(instrumentStoragePath)};
67+
${code.replace(CREATE_CACHE_STORAGE_EXPORT, 'const createUninstrumentedCacheStorage =')}
68+
export const createCacheStorage = () => instrumentCacheStorage(createUninstrumentedCacheStorage(), ${JSON.stringify(driverName)});
69+
`,
70+
map: null,
71+
};
72+
},
73+
};
74+
}

0 commit comments

Comments
 (0)