feat(telemetry): add cache hit rate metric across all cache systems (#638)

## Summary

- Add `recordCacheHit()` helper that emits `cache.hit_rate` distribution
metric (0=miss, 100=hit) with `cache_name` attribute
- Instrument all 5 cache systems: dsn, dsn-detection, project, region,
project-root, http
- Update dashboard "Cache Hit Rate (%)" widget to use tracemetrics avg
grouped by cache_name

## Why

Sentry dashboards don't support division/formula widgets, so computing
`hits / total` isn't possible. By emitting 0 for miss and 100 for hit as
a distribution metric, `avg(value,cache.hit_rate,distribution,none)`
directly gives the hit rate percentage.

## Caches instrumented

| Cache name | Function | What it caches |
|---|---|---|
| `dsn` | `getCachedDsn()` | Single-DSN detection result per directory |
| `dsn-detection` | `getCachedDetection()` | Full detection with mtime
validation |
| `project` | `getByKey()` | Project info by orgId:projectId or DSN key
|
| `region` | `getOrgRegion()` | Org-to-region URL mapping |
| `project-root` | `getCachedProjectRoot()` | cwd-to-project-root
mapping |
| `http` | `getCachedResponse()` | HTTP response cache (also has
existing cache.hit span attribute) |

Author: BYK

src/lib/db/dsn-cache.ts

@@ -13,6 +13,7 @@ import type {
   DetectedDsn,
   ResolvedProjectInfo,
 } from "../dsn/types.js";
+import { recordCacheHit } from "../telemetry.js";
 import { getDatabase, maybeCleanupCaches } from "./index.js";
 import { runUpsert, touchCacheEntry } from "./utils.js";
 
@@ -141,9 +142,11 @@ export function getCachedDsn(directory: string): CachedDsnEntry | undefined {
     .get(directory) as DsnCacheRow | undefined;
 
   if (!row) {
+    recordCacheHit("dsn", false);
     return;
   }
 
+  recordCacheHit("dsn", true);
   touchCacheEntry("dsn_cache", "directory", directory);
   return rowToCachedDsnEntry(row);
 }
@@ -330,6 +333,7 @@ export async function getCachedDetection(
     .get(projectRoot) as DsnCacheRow | undefined;
 
   if (!row) {
+    recordCacheHit("dsn-detection", false);
     return;
   }
 
@@ -340,18 +344,21 @@ export async function getCachedDetection(
     row.ttl_expires_at === null
   ) {
     // Old cache entry without full detection data
+    recordCacheHit("dsn-detection", false);
     return;
   }
 
   const now = Date.now();
 
   // Check TTL expiration
   if (now > row.ttl_expires_at) {
+    recordCacheHit("dsn-detection", false);
     return;
   }
 
   // Check project root directory mtime
   if (!(await validateDirMtime(projectRoot, row.root_dir_mtime))) {
+    recordCacheHit("dsn-detection", false);
     return;
   }
 
@@ -361,6 +368,7 @@ export async function getCachedDetection(
     number
   >;
   if (!(await validateSourceMtimes(projectRoot, sourceMtimes))) {
+    recordCacheHit("dsn-detection", false);
     return;
   }
 
@@ -369,9 +377,11 @@ export async function getCachedDetection(
     ? (JSON.parse(row.dir_mtimes_json) as Record<string, number>)
     : {};
   if (!(await validateDirMtimes(projectRoot, dirMtimes))) {
+    recordCacheHit("dsn-detection", false);
     return;
   }
 
+  recordCacheHit("dsn-detection", true);
   // Cache is valid - update last access time
   touchCacheEntry("dsn_cache", "directory", projectRoot);
 

src/lib/db/project-cache.ts

@@ -3,6 +3,7 @@
  */
 
 import type { CachedProject } from "../../types/index.js";
+import { recordCacheHit } from "../telemetry.js";
 import { getDatabase, maybeCleanupCaches } from "./index.js";
 import { runUpsert, touchCacheEntry } from "./utils.js";
 
@@ -44,9 +45,11 @@ function getByKey(key: string): CachedProject | undefined {
     .get(key) as ProjectCacheRow | undefined;
 
   if (!row) {
+    recordCacheHit("project", false);
     return;
   }
 
+  recordCacheHit("project", true);
   touchCacheEntry("project_cache", "cache_key", key);
   return rowToCachedProject(row);
 }

src/lib/db/project-root-cache.ts

@@ -10,6 +10,7 @@
 
 import { stat } from "node:fs/promises";
 import type { ProjectRootReason } from "../dsn/project-root.js";
+import { recordCacheHit } from "../telemetry.js";
 import { getDatabase, maybeCleanupCaches } from "./index.js";
 import { runUpsert } from "./utils.js";
 
@@ -58,6 +59,7 @@ export async function getCachedProjectRoot(
     .get(cwd) as ProjectRootCacheRow | undefined;
 
   if (!row) {
+    recordCacheHit("project-root", false);
     return;
   }
 
@@ -67,6 +69,7 @@ export async function getCachedProjectRoot(
   if (now > row.ttl_expires_at) {
     // Cache expired, delete it
     db.query("DELETE FROM project_root_cache WHERE cwd = ?").run(cwd);
+    recordCacheHit("project-root", false);
     return;
   }
 
@@ -78,15 +81,17 @@ export async function getCachedProjectRoot(
     if (currentMtime !== row.cwd_mtime) {
       // Directory structure changed, invalidate cache
       db.query("DELETE FROM project_root_cache WHERE cwd = ?").run(cwd);
+      recordCacheHit("project-root", false);
       return;
     }
   } catch {
     // Directory doesn't exist or can't stat - invalidate cache
     db.query("DELETE FROM project_root_cache WHERE cwd = ?").run(cwd);
+    recordCacheHit("project-root", false);
     return;
   }
 
-  // Cache is valid - update last access time would be here if we tracked it
+  recordCacheHit("project-root", true);
   return {
     projectRoot: row.project_root,
     reason: row.reason as ProjectRootReason,

src/lib/db/regions.ts

@@ -10,6 +10,7 @@
  * look up by `org_id = '1081365'` → get the slug).
  */
 
+import { recordCacheHit } from "../telemetry.js";
 import { getDatabase } from "./index.js";
 import { runUpsert } from "./utils.js";
 
@@ -59,6 +60,7 @@ export function getOrgRegion(orgSlug: string): string | undefined {
     .query(`SELECT region_url FROM ${TABLE} WHERE org_slug = ?`)
     .get(orgSlug) as Pick<OrgRegionRow, "region_url"> | undefined;
 
+  recordCacheHit("region", !!row);
   return row?.region_url;
 }
 

src/lib/response-cache.ts

@@ -29,7 +29,7 @@ import pLimit from "p-limit";
 
 import { getConfigDir } from "./db/index.js";
 import { getEnv } from "./env.js";
-import { withCacheSpan } from "./telemetry.js";
+import { recordCacheHit, withCacheSpan } from "./telemetry.js";
 
 // ---------------------------------------------------------------------------
 // TTL tiers — used as fallback when the server sends no cache headers
@@ -386,18 +386,21 @@ export async function getCachedResponse(
       const entry = await readCacheEntry(key);
       if (!entry) {
         span.setAttribute("cache.hit", false);
+        recordCacheHit("http", false);
         return;
       }
 
       try {
         const policy = CachePolicy.fromObject(entry.policy);
         if (!isEntryFresh(policy, entry, requestHeaders, url)) {
           span.setAttribute("cache.hit", false);
+          recordCacheHit("http", false);
           return;
         }
 
         const body = JSON.stringify(entry.body);
         span.setAttribute("cache.hit", true);
+        recordCacheHit("http", true);
         span.setAttribute("cache.item_size", body.length);
 
         const responseHeaders = buildResponseHeaders(policy, entry);
@@ -409,6 +412,7 @@ export async function getCachedResponse(
         // Corrupted or version-incompatible policy object — treat as cache miss.
         // Best-effort cleanup of the broken entry.
         span.setAttribute("cache.hit", false);
+        recordCacheHit("http", false);
         unlink(cacheFilePath(key)).catch(() => {
           // Ignored — fire-and-forget
         });

src/lib/telemetry.ts

@@ -620,6 +620,23 @@ export function setArgsContext(args: readonly unknown[]): void {
   });
 }
 
+/**
+ * Record a cache hit or miss as a distribution metric (0 or 100).
+ *
+ * Emitting 0 for miss and 100 for hit allows computing hit rate as
+ * `avg(value,cache.hit_rate,distribution,none)` on the tracemetrics
+ * dashboard — Sentry doesn't support division in widgets, so this
+ * pre-computed approach gives us percentages directly.
+ *
+ * @param cacheName - Identifier for the cache (e.g., "dsn", "project", "region", "http")
+ * @param hit - Whether the cache lookup was a hit
+ */
+export function recordCacheHit(cacheName: string, hit: boolean): void {
+  Sentry.metrics.distribution("cache.hit_rate", hit ? 100 : 0, {
+    attributes: { cache_name: cacheName },
+  });
+}
+
 /**
  * Wrap an operation with a Sentry span for tracing.
  *