feat(nuxt): Instrument storage API #17858

logaretm · 2025-10-03T15:40:16Z

What

This PR adds automatic instrumentation for Nuxt's storage layer (powered by unstorage), enabling performance monitoring for cache and key-value storage operations in Nuxt/Nitro applications.

Storage operations will now automatically create performance spans with detailed attributes for observability in Sentry.

What's New

Automatic Storage Instrumentation: Instruments all storage drivers configured in nuxt.config.ts via nitro.storage
Comprehensive Coverage: Tracks all storage operations including:
- getItem, setItem, hasItem, removeItem
- Raw variants: getItemRaw, setItemRaw
- Batch operations: getItems, setItems
- Utility methods: getKeys, clear
- Aliases: get, set, has, del, remove

Implementation Details

Span Attributes:

sentry.op: cache.{operation} (e.g., cache.get_item, cache.set_item)
sentry.origin: auto.cache.nuxt
cache.key: Full key including mount prefix
cache.hit: true for successful get/has operations
db.operation.name: Original method name
db.collection.name: Storage mount point
db.system.name: Driver name (e.g., memory, fs, redis)

Files Changed:

packages/nuxt/src/runtime/plugins/storage.server.ts - Runtime instrumentation plugin
packages/nuxt/src/vite/storageConfig.ts - Build-time configuration
packages/nuxt/src/module.ts - Module integration
E2E tests for Nuxt 3 & 4

linear · 2025-10-03T15:40:21Z

JS-1016 [Nuxt/Nitro] Instrument KV Storage (instrumenting `unstorage`)

github-actions · 2025-10-09T09:05:37Z

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	24.4 kB	-	-
@sentry/browser - with treeshaking flags	22.9 kB	-	-
@sentry/browser (incl. Tracing)	40.61 kB	-0.01%	-1 B 🔽
@sentry/browser (incl. Tracing, Replay)	78.98 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	68.62 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	83.67 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	95.82 kB	-	-
@sentry/browser (incl. Feedback)	41.1 kB	+0.01%	+1 B 🔺
@sentry/browser (incl. sendFeedback)	29.06 kB	-	-
@sentry/browser (incl. FeedbackAsync)	33.97 kB	-	-
@sentry/react	26.11 kB	-	-
@sentry/react (incl. Tracing)	42.55 kB	-	-
@sentry/vue	28.92 kB	-	-
@sentry/vue (incl. Tracing)	42.39 kB	-	-
@sentry/svelte	24.44 kB	-	-
CDN Bundle	26.63 kB	-	-
CDN Bundle (incl. Tracing)	41.15 kB	-	-
CDN Bundle (incl. Tracing, Replay)	77.44 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	82.9 kB	-	-
CDN Bundle - uncompressed	78.18 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	122.18 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	237.34 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	250.1 kB	-	-
@sentry/nextjs (client)	44.58 kB	-	-
@sentry/sveltekit (client)	40.98 kB	-	-
@sentry/node-core	50.74 kB	-	-
@sentry/node	154.36 kB	-0.01%	-1 B 🔽
@sentry/node - without tracing	92.59 kB	-0.01%	-1 B 🔽
@sentry/aws-serverless	106.32 kB	+0.01%	+1 B 🔺

View base workflow run

packages/nuxt/src/vendor/server-template.ts

s1gr1d · 2025-10-09T18:23:11Z

packages/nuxt/src/runtime/plugins/storage.server.ts

+  // Mounts are suffixed with a colon, so we need to add it to the set items
+  const userMounts = new Set((userStorageMounts as string[]).map(m => `${m}:`));
+
+  debug.log('[storage] Starting to instrument storage drivers...');


You probably want to show this log conditionally based on debug: true (also applies to other debug statements).

You mean with DEBUG && ....? I don't think it works in server-added plugins as I tried and it fails to build. It also doesn't log anything when debug is false.

s1gr1d · 2025-10-09T18:32:37Z

packages/nuxt/src/runtime/plugins/storage.server.ts

+    'nuxt.storage.op': methodName,
+    'nuxt.storage.mount': mountBase,
+    'nuxt.storage.driver': driver.name ?? 'unknown',


Those attribute names are new - just wondering what's the decision process behind using those. We have some pre-defined attribute names for databases (probably only partially applicable): https://develop.sentry.dev/sdk/telemetry/traces/span-operations/#database

just wondering what's the decision process behind using those

None! I maybe understood that if we don't have a matching attribute name we could create our own. Sorry about that.

I took a read at this and I think we can use these instead:

'db.operation.name': methodName, 'db.collection.name ': mountBase, 'db.system.name': driver.name ?? 'unknown',

s1gr1d · 2025-10-09T18:56:02Z

packages/nuxt/src/runtime/plugins/storage.server.ts

+
+      const spanName = KEYED_METHODS.has(methodName)
+        ? `${mountBase}${args?.[0]}`
+        : `storage.${normalizeMethodName(methodName)}`;


afaik, the span names usually look a bit different than span attributes. Using "storage" here is a bit repetitive and my suggestion would be {operation} {affected keys} based on HTTP span names which are `{method} {endpoint}".

Makes sense, this will tie in nicely with the multiple key handling for getItems calls.

Played around with a few name formats and {operation} {keys} feels redundant since the span description will contain the operation as well. Or is the redundancy usually desired in span names?

I changed it so it is in line with this:

Not sure if we should repeat the mount name for each cache key if it happens to be a multiple.

s1gr1d · 2025-10-09T20:23:39Z

packages/nuxt/src/runtime/plugins/storage.server.ts

+  if (args?.[0] && typeof args[0] === 'string') {
+    attributes[SEMANTIC_ATTRIBUTE_CACHE_KEY] = `${mountBase}${args[0]}`;


is this always just one key or can there be multiple?

If you mean the first arg. yep it is possible, but it would be serialized to a string eg: key1,key2,key3 etc...

and if you mean if args would contain other keys in [1], then no, all the methods signatures place the keys at the first arg.

{ async hasItem(key, _opts) {}, async getItem(key, _opts) {}, async setItem(key, value, _opts) {}, async removeItem(key, _opts) {}, async getKeys(base, _opts) {}, async clear(base, _opts) {}, }

I also missed the possibility of those keys being objects containing a key property, I will add a key normalizer to handle all these cases and format the multiple keys more nicely for the span names.

github-actions · 2025-10-10T09:34:23Z

node-overhead report 🧳

Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	8,877	-	8,903	-0%
GET With Sentry	1,389	16%	1,367	+2%
GET With Sentry (error only)	6,253	70%	6,204	+1%
POST Baseline	1,216	-	1,208	+1%
POST With Sentry	511	42%	526	-3%
POST With Sentry (error only)	1,063	87%	1,069	-1%
MYSQL Baseline	3,353	-	3,350	+0%
MYSQL With Sentry	479	14%	438	+9%
MYSQL With Sentry (error only)	2,722	81%	2,715	+0%

View base workflow run

…heck

logaretm force-pushed the awad/js-1016-nuxtnitro-instrument-kv-storage-instrumenting-unstorage branch from 07cb542 to 24a5470 Compare October 3, 2025 15:40

logaretm linked an issue Oct 3, 2025 that may be closed by this pull request

[Nuxt/Nitro] Instrument KV Storage (instrumenting unstorage) #17846

Open

logaretm self-assigned this Oct 4, 2025

logaretm marked this pull request as ready for review October 6, 2025 12:28

logaretm force-pushed the awad/js-1016-nuxtnitro-instrument-kv-storage-instrumenting-unstorage branch from a6dc41f to fe203a5 Compare October 6, 2025 12:29

This comment was marked as outdated.

Sign in to view

logaretm requested review from andreiborza and s1gr1d October 6, 2025 12:55

logaretm force-pushed the awad/js-1016-nuxtnitro-instrument-kv-storage-instrumenting-unstorage branch from 911b7fe to abe38de Compare October 8, 2025 10:34

This comment was marked as outdated.

Sign in to view

logaretm mentioned this pull request Oct 8, 2025

feat(nuxt): Instrument server cache API #17886

Open

logaretm force-pushed the awad/js-1016-nuxtnitro-instrument-kv-storage-instrumenting-unstorage branch from 64e5814 to 42ef2c7 Compare October 9, 2025 09:02

s1gr1d reviewed Oct 9, 2025

View reviewed changes

This comment was marked as outdated.

Sign in to view

logaretm added 12 commits October 10, 2025 13:50

feat(nuxt): instrument storage drivers

f9500c4

refactor: only instrument user-defined storage

48f2dcb

feat: added more logs and instrument drivers in-place

1012674

refactor: shorter logging messages

b8d605b

feat: remove disposed from instrumentation list

b4aca20

feat: clean up attributes and use semantic cache ops

dac291b

fix: show global key path on span name and adjust operation attrs

f785c77

fix: tighten types and added cache hit attr for get item raw

d5b317a

tests: added e2e tests for storage instrumentation

e05bf53

tests: make sure the storage aliases are covered

0998d46

fix: es compat

334428e

tests: avoid importing semantic attrs exported by indirect dep

572add6

logaretm added 13 commits October 10, 2025 13:50

fix: cache hit detection and excessive mount instrumentation

86dc654

fix: protect storage mount() from nested instrumentation for sanity c…

617d46b

…heck

fix: remove uneeded try catch block

9f0fd65

refactor: move server-template util to vendor

97c1e00

fix: only log when DEBUG_BUILD flag is on

c9a1845

fix: use semantic span attributes for driver info

a682a70

fix: handle multiple cache keys and more complex calls

c43af8f

fix: revert log stuff

19b7d8d

tests: updated test assertions

7d03f1c

fix: op name will contain the method name anyways

e9505da

fix: adjustment to span names

66bb5f3

fix: normalize cache keys properly

c1e4c0e

tests: update assertions to match new keys and attr names

d943f7d

logaretm force-pushed the awad/js-1016-nuxtnitro-instrument-kv-storage-instrumenting-unstorage branch from ab3ecc1 to d943f7d Compare October 10, 2025 10:51

		if (args?.[0] && typeof args[0] === 'string') {
		attributes[SEMANTIC_ATTRIBUTE_CACHE_KEY] = `${mountBase}${args[0]}`;

Uh oh!

feat(nuxt): Instrument storage API #17858

Are you sure you want to change the base?

feat(nuxt): Instrument storage API #17858

Conversation

logaretm commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

What's New

Implementation Details

Uh oh!

linear bot commented Oct 3, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

s1gr1d Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

logaretm Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

s1gr1d Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

logaretm Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

s1gr1d Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

logaretm Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

logaretm Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

s1gr1d Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

logaretm Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions bot commented Oct 10, 2025

node-overhead report 🧳

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

logaretm commented Oct 3, 2025 •

edited

Loading

github-actions bot commented Oct 9, 2025 •

edited

Loading

logaretm Oct 10, 2025 •

edited

Loading

logaretm Oct 10, 2025 •

edited

Loading

logaretm Oct 10, 2025 •

edited

Loading

logaretm Oct 10, 2025 •

edited

Loading