feat(metrics): add observable instruments to DiagnosticsMetrics, with trackCache

docs/METRICS_CATALOG.md

@@ -90,10 +90,16 @@ All Metrics in node-vtex-api
 │       │   ├── latency histogram (via recordLatency)
 │       │   └── graphql_field_requests_total (Counter)
 │       │
-│       └── HTTP Agent (HttpClient/middlewares/request/HttpAgentSingleton.ts)
-│           ├── http_agent_sockets_current (Gauge)
-│           ├── http_agent_free_sockets_current (Gauge)
-│           └── http_agent_pending_requests_current (Gauge)
+│       ├── HTTP Agent (HttpClient/middlewares/request/HttpAgentSingleton.ts)
+│       │   ├── http_agent_sockets_current (Gauge)
+│       │   ├── http_agent_free_sockets_current (Gauge)
+│       │   └── http_agent_pending_requests_current (Gauge)
+│       │
+│       └── Cache (metrics/DiagnosticsMetrics.ts, via trackCache — observable/pull, not per-request)
+│           ├── io_app_cache_operations_total (Observable Counter) - attrs: cache, cache_state
+│           ├── io_app_cache_items_current (Observable Gauge) - caches that expose itemCount
+│           ├── io_app_cache_capacity (Observable Gauge) - caches that expose max
+│           └── io_app_cache_disposed_total (Observable Counter) - caches that expose disposedItems
 │
 └── 🏛️ Legacy Metrics (Non-Diagnostics)
     │
@@ -149,7 +155,7 @@ All Metrics in node-vtex-api
     │   │   ├── httpAgent - sockets, freeSockets, pendingRequests
     │   │   └── incomingRequest - total, closed, aborted
     │   │
-    │   └── Cache Metrics (via trackCache)
+    │   └── Cache Metrics (via trackCache — output discarded since #676; replacement above)
     │       └── {cache_name}-cache
     │           ├── LRU: itemCount, length, disposedItems, hitRate, hits, max, total
     │           ├── Disk: hits, total
@@ -242,6 +248,29 @@ These are operation-specific metrics recorded in middleware components.
 | `http_agent_free_sockets_current` | Gauge | Free sockets in pool |
 | `http_agent_pending_requests_current` | Gauge | Pending requests waiting for socket |
 
+#### Cache Metrics (Observable)
+
+**Source:** `metrics/DiagnosticsMetrics.ts` (`trackCache()`)
+
+The replacement for the legacy `MetricsAccumulator.trackCache()` (see [Legacy Metrics](#legacy-metrics-non-diagnostics) below). Unlike every other metric on this page, these are **observable (pull-based)**: the app registers a cache once, and the four instruments below are read by a callback on the OTel SDK's own collection schedule, not pushed per-request. See `registerObservableGauge`/`registerObservableCounter` on `DiagnosticsMetrics` if you need the same pull model for something other than a cache.
+
+Reads the cache's `getCumulativeStats()`, which has no side effects — so this can run alongside the legacy `metrics.trackCache()` without either reader consuming the other's counts. A cache registered in both places reports correctly in both, which is what makes a partial migration safe.
+
+| Metric Name | Type | Attributes | Reported when |
+|-------------|------|------------|----------------|
+| `io_app_cache_operations_total` | Observable Counter | `cache`, `cache_state` (`hit` \| `miss`) | Cache reports `hits` and `total` (all four cache classes do) |
+| `io_app_cache_items_current` | Observable Gauge | `cache` | Cache reports `itemCount` (`LRUCache`, `LRUDiskCache`) |
+| `io_app_cache_capacity` | Observable Gauge | `cache` | Cache reports `max` (`LRUCache`, `LRUDiskCache`) |
+| `io_app_cache_disposed_total` | Observable Counter | `cache` | Cache reports `disposedItems` (`LRUCache`, `LRUDiskCache`) |
+
+`hitRate` is not republished — derive it from `io_app_cache_operations_total` (`hit / (hit + miss)`) so it aggregates correctly across instances instead of averaging pre-computed ratios.
+
+**`io_app_cache_capacity` is in the cache's own units.** It reports the LRU's `max`, which is an item count for a cache built with a plain `max`, but a size budget for one built with a `length` function. Only treat `items_current / capacity` as a fill ratio when you know the cache is count-limited.
+
+```typescript
+const dispose = global.diagnosticsMetrics?.trackCache('pages', pagesCacheStorage)
+```
+
 ---
 
 ## Legacy Metrics (Non-Diagnostics)

docs/METRICS_OVERVIEW.md

@@ -172,6 +172,81 @@ global.diagnosticsMetrics.setGauge('cache_items_current', stats.size, {
 
 > 📌 **Production Example:** The [render-to-string's `recordCacheMetric()` function](https://github.com/vtex/render-to-string/blob/master/node/utils/metrics.ts) uses `incrementCounter('cache_operations_total', 1, { cache, cache_state })` for unified cache tracking.
 
+**Note:** Pattern 4 above is for *push*-based tracking — you call `incrementCounter`/`setGauge` yourself, at the point in your code where a cache is read. If instead your code uses `metrics.trackCache(name, cache)` — registering a cache instance once, with `MetricsAccumulator` reading its `getStats()` on every flush — that's a different idiom with its own replacement. See Pattern 5.
+
+### Pattern 5: Registering a Cache for Periodic Observation (`trackCache`)
+
+**Before:**
+```typescript
+// Registers the cache once; MetricsAccumulator calls cache.getStats() on every flush
+metrics.trackCache('pages', pagesCacheStorage)
+```
+
+**After:**
+```typescript
+// Same registration call, same cache instance — DiagnosticsMetrics reads getStats()
+// on the OTel SDK's own collection schedule instead of on every legacy flush.
+const dispose = global.diagnosticsMetrics?.trackCache('pages', pagesCacheStorage)
+```
+
+This is a direct replacement, not a manual re-implementation with `incrementCounter`/`setGauge` (Pattern 4's approach) — `trackCache()` reads the cache exactly once per collection cycle no matter how many metrics it produces from it.
+
+**Leaving the legacy call in place is harmless.** The legacy `getStats()` reports a per-flush window and consumes it on read; `getCumulativeStats()` reports the process-lifetime total and has no side effects, so the two readers don't steal counts from each other:
+
+```typescript
+metrics.trackCache('pages', pagesCacheStorage)                      // harmless to keep
+global.diagnosticsMetrics?.trackCache('pages', pagesCacheStorage)   // add; drop the line above when convenient
+```
+
+This is about safety, not about comparing the two. Since #676 (v7.4.2) nothing consumes what the legacy flush returns — `statusTrack()` keeps running only because flushing also resets the metric accumulators, the CPU baseline and the request stats. So there is no legacy cache metric to compare against; what you get is that a half-migrated app still reports correct numbers. That matters when 23 call sites across three apps are migrated by different people in different PRs: under a read that consumed the counters, registering a cache in both places would have leaked an arbitrary fraction of its counts into a flush that discards them — a plausible-looking, permanently wrong number, with no second metric anywhere to reveal the discrepancy.
+
+Emits `io_app_cache_operations_total`, `io_app_cache_items_current`, `io_app_cache_capacity` and `io_app_cache_disposed_total` — see [METRICS_CATALOG.md](./METRICS_CATALOG.md#cache-metrics-observable) for the full attribute reference. `hitRate` is not republished; derive it from `io_app_cache_operations_total` instead.
+
+### Pattern 6: Metrics Computed at Flush Time (`addOnFlushMetric`)
+
+`metrics.addOnFlushMetric(fn)` registers a function that `MetricsAccumulator` calls on every flush, returning an object that is published as a log line. The replacement is `registerObservableGauge`/`registerObservableCounter` — same idea (a callback read on a schedule), with the OTel collection cycle in place of the legacy flush.
+
+The translation is not mechanical: a flush metric returns **one object with arbitrarily many fields**, while an observable instrument reports **one numeric value** per observation. So decide, per field, whether it becomes its own instrument or an attribute on a shared one.
+
+**Before:**
+```typescript
+metrics.addOnFlushMetric(() => ({
+  name: 'my-queue',
+  size: queue.size,
+  oldestAgeMs: queue.oldestAgeMs(),
+}))
+```
+
+**After** — two distinct measurements, so two instruments:
+```typescript
+global.diagnosticsMetrics?.registerObservableGauge(
+  'my_queue_size_current',
+  result => result.observe(queue.size),
+  { description: 'Items currently queued', unit: '1' }
+)
+
+global.diagnosticsMetrics?.registerObservableGauge(
+  'my_queue_oldest_age_milliseconds',
+  result => result.observe(queue.oldestAgeMs()),
+  { description: 'Age of the oldest queued item', unit: 'ms' }
+)
+```
+
+When the fields are the *same* measurement split by category, use one instrument and an attribute instead:
+```typescript
+global.diagnosticsMetrics?.registerObservableGauge('my_queue_size_current', result => {
+  result.observe(queue.pending, { state: 'pending' })
+  result.observe(queue.running, { state: 'running' })
+})
+```
+
+Notes that apply to both register methods:
+
+- Use `registerObservableCounter` only for values that **never decrease** and report the cumulative total — the SDK derives the per-cycle delta itself. Anything that can go down is a gauge.
+- Re-registering the same name replaces the previous callback. A name already taken by the other kind is refused with an error log, since two same-named streams of different types break the collector.
+- Attributes reported by the callback are subject to the same limit as the push methods; base attributes are not merged, because the callback runs outside any request.
+- Both return a disposer. Call it when the thing you're observing goes away.
+
 ---
 
 ## What Doesn't Need Migration

package.json

@@ -95,6 +95,8 @@
     "xss": "^1.0.6"
   },
   "devDependencies": {
+    "@opentelemetry/context-async-hooks": "^1.30.1",
+    "@opentelemetry/sdk-metrics": "^1.30.1",
     "@tiagonapoli/opentracing-alternate-mock": "^0.0.3",
     "@types/archiver": "^2.0.1",
     "@types/bluebird": "^3.5.27",

src/caches/DiskCache.ts

@@ -1,5 +1,5 @@
 import { CacheLayer } from './CacheLayer'
-import { DiskStats } from './typings'
+import { CumulativeStats, DiskStats } from './typings'
 
 import { outputJSON, pathExistsSync, readJSON } from 'fs-extra'
 import { join } from 'path'
@@ -10,6 +10,7 @@ export class DiskCache<V> implements CacheLayer<string, V>{
   private hits = 0
   private total = 0
   private lock: ReadWriteLock
+  private reported = { hits: 0, total: 0 }
 
   constructor(private cachePath: string, private readFile=readJSON, private writeFile=outputJSON) {
     this.lock = new ReadWriteLock()
@@ -22,15 +23,19 @@ export class DiskCache<V> implements CacheLayer<string, V>{
 
   public getStats = (name='disk-cache'): DiskStats => {
     const stats = {
-      hits: this.hits,
+      hits: this.hits - this.reported.hits,
       name,
-      total: this.total,
+      total: this.total - this.reported.total,
     }
-    this.hits = 0
-    this.total = 0
+    this.reported = { hits: this.hits, total: this.total }
     return stats
   }
 
+  public getCumulativeStats = (): CumulativeStats => ({
+    hits: this.hits,
+    total: this.total,
+  })
+
   public get = async (key: string): Promise<V | void>  => {
     const pathKey = this.getPathKey(key)
     this.total += 1

src/caches/LRUCache.ts

@@ -1,19 +1,21 @@
 import LRU from 'lru-cache'
 import { CacheLayer } from './CacheLayer'
 import { MultilayeredCache } from './MultilayeredCache'
-import { FetchResult, LRUStats } from './typings'
+import { CumulativeStats, FetchResult, LRUStats } from './typings'
 
 export class LRUCache <K, V> implements CacheLayer<K, V>{
   private multilayer: MultilayeredCache<K, V>
   private storage: LRU<K, V>
   private hits: number
   private total: number
   private disposed: number
+  private reported: { hits: number, total: number, disposed: number }
 
   constructor (options: LRU.Options<K, V>) {
     this.hits = 0
     this.total = 0
     this.disposed = 0
+    this.reported = { disposed: 0, hits: 0, total: 0 }
     this.storage = new LRU({
       ...options,
       dispose: () => this.disposed += 1,
@@ -38,19 +40,28 @@ export class LRUCache <K, V> implements CacheLayer<K, V>{
   public has = (key: K): boolean => this.storage.has(key)
 
   public getStats = (name='lru-cache'): LRUStats => {
+    const hits = this.hits - this.reported.hits
+    const total = this.total - this.reported.total
     const stats = {
-      disposedItems: this.disposed,
-      hitRate: this.total > 0 ? this.hits / this.total : undefined,
-      hits: this.hits,
+      disposedItems: this.disposed - this.reported.disposed,
+      hitRate: total > 0 ? hits / total : undefined,
+      hits,
       itemCount: this.storage.itemCount,
       length: this.storage.length,
       max: this.storage.max,
       name,
-      total: this.total,
+      total,
     }
-    this.hits = 0
-    this.total = 0
-    this.disposed = 0
+    this.reported = { disposed: this.disposed, hits: this.hits, total: this.total }
     return stats
   }
+
+  public getCumulativeStats = (): CumulativeStats => ({
+    disposedItems: this.disposed,
+    hits: this.hits,
+    itemCount: this.storage.itemCount,
+    length: this.storage.length,
+    max: this.storage.max,
+    total: this.total,
+  })
 }

src/caches/LRUDiskCache.ts

@@ -1,5 +1,5 @@
 import { CacheLayer } from './CacheLayer'
-import { LRUDiskCacheOptions, LRUStats } from './typings'
+import { CumulativeStats, LRUDiskCacheOptions, LRUStats } from './typings'
 
 import { outputJSON, readJSON, remove } from 'fs-extra'
 import LRU from 'lru-cache'
@@ -14,6 +14,7 @@ export class LRUDiskCache<V> implements CacheLayer<string, V>{
   private total = 0
   private lruStorage: LRU<string, number>
   private keyToBeDeleted: string
+  private reported = { disposed: 0, hits: 0, total: 0 }
 
   constructor(private cachePath: string, options: LRUDiskCacheOptions, private readFile=readJSON, private writeFile=outputJSON) {
     this.hits = 0
@@ -40,22 +41,31 @@ export class LRUDiskCache<V> implements CacheLayer<string, V>{
   public has = (key: string): boolean => this.lruStorage.has(key)
 
   public getStats = (name='disk-lru-cache'): LRUStats => {
+    const hits = this.hits - this.reported.hits
+    const total = this.total - this.reported.total
     const stats = {
-      disposedItems: this.disposed,
-      hitRate: this.total > 0 ? this.hits / this.total : undefined,
-      hits: this.hits,
+      disposedItems: this.disposed - this.reported.disposed,
+      hitRate: total > 0 ? hits / total : undefined,
+      hits,
       itemCount: this.lruStorage.itemCount,
       length: this.lruStorage.length,
       max: this.lruStorage.max,
       name,
-      total: this.total,
+      total,
     }
-    this.hits = 0
-    this.total = 0
-    this.disposed = 0
+    this.reported = { disposed: this.disposed, hits: this.hits, total: this.total }
     return stats
   }
 
+  public getCumulativeStats = (): CumulativeStats => ({
+    disposedItems: this.disposed,
+    hits: this.hits,
+    itemCount: this.lruStorage.itemCount,
+    length: this.lruStorage.length,
+    max: this.lruStorage.max,
+    total: this.total,
+  })
+
   public get = async (key: string): Promise<V | void>  => {
     const timeOfDeath = this.lruStorage.get(key)
     this.total += 1

src/caches/MultilayeredCache.ts

@@ -1,11 +1,12 @@
 import { any, map, slice } from 'ramda'
 import { CacheLayer } from './CacheLayer'
-import { FetchResult, MultilayerStats } from './typings'
+import { CumulativeStats, FetchResult, MultilayerStats } from './typings'
 
 export class MultilayeredCache <K, V> implements CacheLayer<K, V>{
 
   private hits = 0
   private total = 0
+  private reported = { hits: 0, total: 0 }
 
   constructor (private caches: Array<CacheLayer<K, V>>) {}
 
@@ -45,16 +46,23 @@ export class MultilayeredCache <K, V> implements CacheLayer<K, V>{
   }
 
   public getStats = (name='multilayred-cache'): MultilayerStats => {
+    const hits = this.hits - this.reported.hits
+    const total = this.total - this.reported.total
     const multilayerStats = {
-      hitRate: this.total > 0 ? this.hits / this.total : undefined,
-      hits: this.hits,
+      hitRate: total > 0 ? hits / total : undefined,
+      hits,
       name,
-      total: this.total,
+      total,
     }
-    this.resetCounters()
+    this.reported = { hits: this.hits, total: this.total }
     return multilayerStats
   }
 
+  public getCumulativeStats = (): CumulativeStats => ({
+    hits: this.hits,
+    total: this.total,
+  })
+
   private findIndex = async <T> (func: (item: T) => Promise<boolean>, array: T[]): Promise<number> => {
     this.total += 1
     for (let index = 0; index < array.length; index++) {
@@ -67,8 +75,4 @@ export class MultilayeredCache <K, V> implements CacheLayer<K, V>{
     return -1
   }
 
-  private resetCounters () {
-    this.hits = 0
-    this.total = 0
-  }
 }