feat: implement Sentry Cache Module instrumentation for response cache

Align cache spans with the Sentry Cache Module spec for the
Caches Insights dashboard:

- Change span ops from generic 'cache' to 'cache.get' and 'cache.put'
- Set 'cache.key' attribute (string array) with the cache entry key
- Set 'cache.hit' attribute (boolean) dynamically after lookup
- Set 'cache.item_size' attribute with serialized body length on hit/store
- Set 'network.peer.address' to the cache directory path
- Use the URL as span name instead of generic 'cache.lookup'/'cache.store'
- Pass span to callback in withCacheSpan for dynamic attribute setting

Ref: https://docs.sentry.io/platforms/javascript/guides/node/tracing/instrumentation/caches-module/

Author: BYK

src/lib/response-cache.ts

@@ -367,36 +367,48 @@ export async function getCachedResponse(
     return;
   }
 
+  const key = buildCacheKey(method, url);
+
   return await withCacheSpan(
-    "cache.lookup",
-    async () => {
-      const key = buildCacheKey(method, url);
+    url,
+    "cache.get",
+    async (span) => {
       const entry = await readCacheEntry(key);
       if (!entry) {
+        span.setAttribute("cache.hit", false);
         return;
       }
 
       try {
         const policy = CachePolicy.fromObject(entry.policy);
         if (!isEntryFresh(policy, entry, requestHeaders, url)) {
+          span.setAttribute("cache.hit", false);
           return;
         }
 
+        const body = JSON.stringify(entry.body);
+        span.setAttribute("cache.hit", true);
+        span.setAttribute("cache.item_size", body.length);
+
         const responseHeaders = buildResponseHeaders(policy, entry);
-        return new Response(JSON.stringify(entry.body), {
+        return new Response(body, {
           status: entry.status,
           headers: responseHeaders,
         });
       } catch {
         // Corrupted or version-incompatible policy object — treat as cache miss.
         // Best-effort cleanup of the broken entry.
+        span.setAttribute("cache.hit", false);
         unlink(cacheFilePath(key)).catch(() => {
           // Ignored — fire-and-forget
         });
         return;
       }
     },
-    { "cache.url": url }
+    {
+      "cache.key": [key],
+      "network.peer.address": getCacheDir(),
+    }
   );
 }
 
@@ -455,38 +467,60 @@ export async function storeCachedResponse(
     return;
   }
 
+  const key = buildCacheKey(method, url);
+
   try {
     await withCacheSpan(
-      "cache.store",
-      () => writeResponseToCache(method, url, requestHeaders, response),
-      { "cache.url": url }
+      url,
+      "cache.put",
+      async (span) => {
+        const size = await writeResponseToCache(
+          key,
+          url,
+          requestHeaders,
+          response
+        );
+        if (size > 0) {
+          span.setAttribute("cache.item_size", size);
+        }
+      },
+      {
+        "cache.key": [key],
+        "network.peer.address": getCacheDir(),
+      }
     );
   } catch {
     // Cache write failures are non-fatal — silently ignore
   }
 }
 
-/** Core cache write logic, separated for complexity management */
+/**
+ * Core cache write logic, separated for complexity management.
+ *
+ * Always called for GET requests (caller checks method), so "GET" is hardcoded
+ * for the CachePolicy constructor.
+ *
+ * @returns The serialized body size in bytes (0 if not storable).
+ */
 async function writeResponseToCache(
-  method: string,
+  key: string,
   url: string,
   requestHeaders: Record<string, string>,
   response: Response
-): Promise<void> {
+): Promise<number> {
   const responseHeadersObj = headersToObject(response.headers);
 
   const policy = new CachePolicy(
-    { url, method, headers: requestHeaders },
+    { url, method: "GET", headers: requestHeaders },
     { status: response.status, headers: responseHeadersObj },
     POLICY_OPTIONS
   );
 
   if (!policy.storable()) {
-    return;
+    return 0;
   }
 
   const body: unknown = await response.json();
-  const key = buildCacheKey(method, url);
   const now = Date.now();
 
   // Pre-compute expiry for cheap cleanup checks (avoids CachePolicy deserialization).
@@ -507,15 +541,18 @@ async function writeResponseToCache(
     expiresAt: now + ttl,
   };
 
+  const serialized = JSON.stringify(entry);
   await mkdir(getCacheDir(), { recursive: true, mode: 0o700 });
-  await writeFile(cacheFilePath(key), JSON.stringify(entry), "utf-8");
+  await writeFile(cacheFilePath(key), serialized, "utf-8");
 
   // Probabilistic cleanup to avoid unbounded cache growth
   if (Math.random() < CLEANUP_PROBABILITY) {
     cleanupCache().catch(() => {
       // Non-fatal: cleanup failure doesn't affect cache correctness
     });
   }
+
+  return serialized.length;
 }
 
 /**

src/lib/telemetry.ts

@@ -952,20 +952,35 @@ export function withFsSpan<T>(
 }
 
 /**
- * Wrap a cache operation with a span for tracing.
+ * Wrap a cache operation with a Sentry Cache Module span.
  *
- * Creates a child span under the current active span to track
- * response cache hit/miss/store operations.
+ * Implements the [Sentry Cache Module spec](https://develop.sentry.dev/sdk/performance/modules/caches/)
+ * for the Caches Insights dashboard. The span is passed to the callback so
+ * callers can set `cache.hit`, `cache.item_size`, etc. after the lookup.
  *
- * @param operation - Name of the operation (e.g., "cache.lookup", "cache.store")
- * @param fn - The function that performs the cache operation
- * @param attributes - Optional span attributes (e.g., url, cache.hit)
+ * @param name - Span name (typically the cache key or a descriptive label)
+ * @param op - Cache operation: `"cache.get"` for reads, `"cache.put"` for writes
+ * @param fn - Function to execute, receives the span for dynamic attribute setting
+ * @param attributes - Initial span attributes (e.g., `cache.key`, `network.peer.address`)
  * @returns The result of the function
  */
 export function withCacheSpan<T>(
-  operation: string,
-  fn: () => T | Promise<T>,
-  attributes?: Record<string, string | number | boolean>
+  name: string,
+  op: "cache.get" | "cache.put",
+  fn: (span: Span) => T | Promise<T>,
+  attributes?: Record<string, string | number | boolean | string[]>
 ): Promise<T> {
-  return withTracing(operation, "cache", fn, attributes);
+  return Sentry.startSpan(
+    { name, op, attributes, onlyIfParent: true },
+    async (span) => {
+      try {
+        const result = await fn(span);
+        span.setStatus({ code: 1 }); // OK
+        return result;
+      } catch (error) {
+        span.setStatus({ code: 2 }); // Error
+        throw error;
+      }
+    }
+  );
 }