@vtex/api 7.5.0 → 7.5.1-beta.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [7.5.1-beta.1]
+
+### Added
+
+- `DiagnosticsMetrics.trackCache(name, cache)`: observable cache metrics (`io_app_cache_*`), safe alongside the legacy `trackCache`
+- `DiagnosticsMetrics.registerObservableGauge/Counter(name, observe, options?)`: pull-based instruments
+- `getCumulativeStats()` on the four cache classes: process-lifetime totals, side-effect free
+
+### Fixed
+
+- `io_app_cache_operations_total{cache_state="miss"}` counts misses when a read resolves, so the
+  series stays monotonic for the async caches (`LRUDiskCache`, `DiskCache`)
+
 ## [7.5.0]
 
 ### Added

package/lib/caches/DiskCache.d.ts

@@ -1,16 +1,16 @@
 import { CacheLayer } from './CacheLayer';
-import { DiskStats } from './typings';
+import { CumulativeStats, DiskStats } from './typings';
 import { outputJSON, readJSON } from 'fs-extra';
 export declare class DiskCache<V> implements CacheLayer<string, V> {
     private cachePath;
     private readFile;
     private writeFile;
-    private hits;
-    private total;
+    private readonly counters;
     private lock;
     constructor(cachePath: string, readFile?: typeof readJSON, writeFile?: typeof outputJSON);
     has: (key: string) => boolean;
     getStats: (name?: string) => DiskStats;
+    getCumulativeStats: () => CumulativeStats;
     get: (key: string) => Promise<V | void>;
     set: (key: string, value: V) => Promise<boolean>;
     private getPathKey;

package/lib/caches/DiskCache.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiskCache = void 0;
+const WindowedCounters_1 = require("./WindowedCounters");
 const fs_extra_1 = require("fs-extra");
 const path_1 = require("path");
 const rwlock_1 = __importDefault(require("rwlock"));
@@ -12,35 +13,33 @@ class DiskCache {
         this.cachePath = cachePath;
         this.readFile = readFile;
         this.writeFile = writeFile;
-        this.hits = 0;
-        this.total = 0;
+        this.counters = new WindowedCounters_1.WindowedCounters();
         this.has = (key) => {
             const pathKey = this.getPathKey(key);
             return (0, fs_extra_1.pathExistsSync)(pathKey);
         };
         this.getStats = (name = 'disk-cache') => {
-            const stats = {
-                hits: this.hits,
-                name,
-                total: this.total,
-            };
-            this.hits = 0;
-            this.total = 0;
-            return stats;
+            const { hits, total } = this.counters.windowed();
+            return { hits, name, total };
+        };
+        this.getCumulativeStats = () => {
+            const { hits, misses, total } = this.counters.cumulative();
+            return { hits, misses, total };
         };
         this.get = async (key) => {
             const pathKey = this.getPathKey(key);
-            this.total += 1;
+            this.counters.countRead();
             const data = await new Promise(resolve => {
                 this.lock.readLock(key, async (release) => {
                     try {
                         const fileData = await this.readFile(pathKey);
                         release();
-                        this.hits += 1;
+                        this.counters.countHit();
                         resolve(fileData);
                     }
-                    catch (e) {
+                    catch {
                         release();
+                        this.counters.countMiss(); // a missing or unreadable file is a miss
                         resolve(null);
                     }
                 });
@@ -56,7 +55,7 @@ class DiskCache {
                         release();
                         resolve(writePromise);
                     }
-                    catch (e) {
+                    catch {
                         release();
                         resolve(true);
                     }

package/lib/caches/LRUCache.d.ts

@@ -1,16 +1,15 @@
 import LRU from 'lru-cache';
 import { CacheLayer } from './CacheLayer';
-import { FetchResult, LRUStats } from './typings';
+import { CumulativeStats, FetchResult, LRUStats } from './typings';
 export declare class LRUCache<K, V> implements CacheLayer<K, V> {
     private multilayer;
     private storage;
-    private hits;
-    private total;
-    private disposed;
+    private readonly counters;
     constructor(options: LRU.Options<K, V>);
     get: (key: K) => V | void;
     getOrSet: (key: K, fetcher?: () => Promise<FetchResult<V>>) => Promise<V | void>;
     set: (key: K, value: V, maxAge?: number) => boolean;
     has: (key: K) => boolean;
     getStats: (name?: string) => LRUStats;
+    getCumulativeStats: () => CumulativeStats;
 }

package/lib/caches/LRUCache.js

@@ -6,41 +6,52 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LRUCache = void 0;
 const lru_cache_1 = __importDefault(require("lru-cache"));
 const MultilayeredCache_1 = require("./MultilayeredCache");
+const WindowedCounters_1 = require("./WindowedCounters");
 class LRUCache {
     constructor(options) {
         this.get = (key) => {
             const value = this.storage.get(key);
             if (this.storage.has(key)) {
-                this.hits += 1;
+                this.counters.countHit();
             }
-            this.total += 1;
+            else {
+                this.counters.countMiss();
+            }
+            this.counters.countRead();
             return value;
         };
         this.getOrSet = async (key, fetcher) => this.multilayer.get(key, fetcher);
         this.set = (key, value, maxAge) => this.storage.set(key, value, maxAge);
         this.has = (key) => this.storage.has(key);
         this.getStats = (name = 'lru-cache') => {
-            const stats = {
-                disposedItems: this.disposed,
-                hitRate: this.total > 0 ? this.hits / this.total : undefined,
-                hits: this.hits,
+            const { disposed, hits, total } = this.counters.windowed();
+            return {
+                disposedItems: 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.getCumulativeStats = () => {
+            const { disposed, hits, misses, total } = this.counters.cumulative();
+            return {
+                disposedItems: disposed,
+                hits,
+                itemCount: this.storage.itemCount,
+                length: this.storage.length,
+                max: this.storage.max,
+                misses,
+                total,
             };
-            this.hits = 0;
-            this.total = 0;
-            this.disposed = 0;
-            return stats;
         };
-        this.hits = 0;
-        this.total = 0;
-        this.disposed = 0;
+        this.counters = new WindowedCounters_1.WindowedCounters();
         this.storage = new lru_cache_1.default({
             ...options,
-            dispose: () => this.disposed += 1,
+            dispose: () => this.counters.countDisposed(),
             noDisposeOnSet: true,
         });
         this.multilayer = new MultilayeredCache_1.MultilayeredCache([this]);

package/lib/caches/LRUDiskCache.d.ts

@@ -1,19 +1,18 @@
 import { CacheLayer } from './CacheLayer';
-import { LRUDiskCacheOptions, LRUStats } from './typings';
+import { CumulativeStats, LRUDiskCacheOptions, LRUStats } from './typings';
 import { outputJSON, readJSON } from 'fs-extra';
 export declare class LRUDiskCache<V> implements CacheLayer<string, V> {
     private cachePath;
     private readFile;
     private writeFile;
     private lock;
-    private disposed;
-    private hits;
-    private total;
+    private readonly counters;
     private lruStorage;
     private keyToBeDeleted;
     constructor(cachePath: string, options: LRUDiskCacheOptions, readFile?: typeof readJSON, writeFile?: typeof outputJSON);
     has: (key: string) => boolean;
     getStats: (name?: string) => LRUStats;
+    getCumulativeStats: () => CumulativeStats;
     get: (key: string) => Promise<V | void>;
     set: (key: string, value: V, maxAge?: number) => Promise<boolean>;
     private getPathKey;

package/lib/caches/LRUDiskCache.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LRUDiskCache = void 0;
+const WindowedCounters_1 = require("./WindowedCounters");
 const fs_extra_1 = require("fs-extra");
 const lru_cache_1 = __importDefault(require("lru-cache"));
 const path_1 = require("path");
@@ -13,29 +14,37 @@ class LRUDiskCache {
         this.cachePath = cachePath;
         this.readFile = readFile;
         this.writeFile = writeFile;
-        this.hits = 0;
-        this.total = 0;
         this.has = (key) => this.lruStorage.has(key);
         this.getStats = (name = 'disk-lru-cache') => {
-            const stats = {
-                disposedItems: this.disposed,
-                hitRate: this.total > 0 ? this.hits / this.total : undefined,
-                hits: this.hits,
+            const { disposed, hits, total } = this.counters.windowed();
+            return {
+                disposedItems: 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.getCumulativeStats = () => {
+            const { disposed, hits, misses, total } = this.counters.cumulative();
+            return {
+                disposedItems: disposed,
+                hits,
+                itemCount: this.lruStorage.itemCount,
+                length: this.lruStorage.length,
+                max: this.lruStorage.max,
+                misses,
+                total,
             };
-            this.hits = 0;
-            this.total = 0;
-            this.disposed = 0;
-            return stats;
         };
         this.get = async (key) => {
             const timeOfDeath = this.lruStorage.get(key);
-            this.total += 1;
+            this.counters.countRead();
             if (timeOfDeath === undefined) {
+                this.counters.countMiss();
                 // if it is an outdated file when stale=false
                 if (this.keyToBeDeleted) {
                     await this.deleteFile(key);
@@ -48,11 +57,12 @@ class LRUDiskCache {
                     try {
                         const fileData = await this.readFile(pathKey);
                         release();
-                        this.hits += 1;
+                        this.counters.countHit();
                         resolve(fileData);
                     }
-                    catch (e) {
+                    catch {
                         release();
+                        this.counters.countMiss(); // a missing or unreadable file is a miss
                         resolve(null);
                     }
                 });
@@ -84,7 +94,7 @@ class LRUDiskCache {
                         release();
                         resolve(writePromise);
                     }
-                    catch (e) {
+                    catch {
                         release();
                         resolve(true);
                     }
@@ -105,7 +115,7 @@ class LRUDiskCache {
                         release();
                         resolve(removePromise);
                     }
-                    catch (e) {
+                    catch {
                         release();
                         resolve(true);
                     }
@@ -113,14 +123,12 @@ class LRUDiskCache {
             });
             return !failure;
         };
-        this.hits = 0;
-        this.total = 0;
-        this.disposed = 0;
+        this.counters = new WindowedCounters_1.WindowedCounters();
         this.keyToBeDeleted = '';
         this.lock = new rwlock_1.default();
         const dispose = (key) => {
             this.keyToBeDeleted = key;
-            this.disposed += 1;
+            this.counters.countDisposed();
         };
         const lruOptions = {
             ...options,

package/lib/caches/MultilayeredCache.d.ts

@@ -1,14 +1,13 @@
 import { CacheLayer } from './CacheLayer';
-import { FetchResult, MultilayerStats } from './typings';
+import { CumulativeStats, FetchResult, MultilayerStats } from './typings';
 export declare class MultilayeredCache<K, V> implements CacheLayer<K, V> {
     private caches;
-    private hits;
-    private total;
+    private readonly counters;
     constructor(caches: Array<CacheLayer<K, V>>);
     get: (key: K, fetcher?: () => Promise<FetchResult<V>>) => Promise<V | void>;
     set: (key: K, value: V, maxAge?: number) => Promise<boolean>;
     has: (key: K) => Promise<boolean>;
     getStats: (name?: string) => MultilayerStats;
+    getCumulativeStats: () => CumulativeStats;
     private findIndex;
-    private resetCounters;
 }

package/lib/caches/MultilayeredCache.js

@@ -2,11 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MultilayeredCache = void 0;
 const ramda_1 = require("ramda");
+const WindowedCounters_1 = require("./WindowedCounters");
 class MultilayeredCache {
     constructor(caches) {
         this.caches = caches;
-        this.hits = 0;
-        this.total = 0;
+        this.counters = new WindowedCounters_1.WindowedCounters();
         this.get = async (key, fetcher) => {
             let value = undefined;
             let maxAge;
@@ -40,30 +40,30 @@ class MultilayeredCache {
             return (0, ramda_1.any)(item => item, hasList);
         };
         this.getStats = (name = 'multilayred-cache') => {
-            const multilayerStats = {
-                hitRate: this.total > 0 ? this.hits / this.total : undefined,
-                hits: this.hits,
+            const { hits, total } = this.counters.windowed();
+            return {
+                hitRate: total > 0 ? hits / total : undefined,
+                hits,
                 name,
-                total: this.total,
+                total,
             };
-            this.resetCounters();
-            return multilayerStats;
+        };
+        this.getCumulativeStats = () => {
+            const { hits, misses, total } = this.counters.cumulative();
+            return { hits, misses, total };
         };
         this.findIndex = async (func, array) => {
-            this.total += 1;
+            this.counters.countRead();
             for (let index = 0; index < array.length; index++) {
                 const hasKey = await func(array[index]);
                 if (hasKey) {
-                    this.hits += 1;
+                    this.counters.countHit();
                     return index;
                 }
             }
+            this.counters.countMiss();
             return -1;
         };
     }
-    resetCounters() {
-        this.hits = 0;
-        this.total = 0;
-    }
 }
 exports.MultilayeredCache = MultilayeredCache;

package/lib/caches/WindowedCounters.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Counters with a windowed read. `windowed()` reports the delta since the previous read and
+ * `cumulative()` the process-lifetime total, so a windowed reader (the legacy flush) and a
+ * cumulative one (the observable reader) can share a cache without consuming each other's
+ * counts. Shared by the four cache classes so a fix to the delta/rollover behaviour cannot
+ * land in one and be forgotten in the others.
+ *
+ * Misses are counted when a read resolves, never when it starts. The observable reader
+ * publishes them as a monotonic counter, so a value derived from `total - hits` would dip
+ * while a read is in flight — and the SDK reports a dip on a monotonic counter as a reset,
+ * publishing the whole running total as one cycle's delta.
+ */
+export declare class WindowedCounters {
+    private hits;
+    private misses;
+    private total;
+    private disposed;
+    private reported;
+    countHit: () => void;
+    countMiss: () => void;
+    countRead: () => void;
+    countDisposed: () => void;
+    windowed: () => {
+        disposed: number;
+        hits: number;
+        misses: number;
+        total: number;
+    };
+    cumulative: () => {
+        disposed: number;
+        hits: number;
+        misses: number;
+        total: number;
+    };
+}

package/lib/caches/WindowedCounters.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WindowedCounters = void 0;
+/**
+ * Counters with a windowed read. `windowed()` reports the delta since the previous read and
+ * `cumulative()` the process-lifetime total, so a windowed reader (the legacy flush) and a
+ * cumulative one (the observable reader) can share a cache without consuming each other's
+ * counts. Shared by the four cache classes so a fix to the delta/rollover behaviour cannot
+ * land in one and be forgotten in the others.
+ *
+ * Misses are counted when a read resolves, never when it starts. The observable reader
+ * publishes them as a monotonic counter, so a value derived from `total - hits` would dip
+ * while a read is in flight — and the SDK reports a dip on a monotonic counter as a reset,
+ * publishing the whole running total as one cycle's delta.
+ */
+class WindowedCounters {
+    constructor() {
+        this.hits = 0;
+        this.misses = 0;
+        this.total = 0;
+        this.disposed = 0;
+        this.reported = { disposed: 0, hits: 0, misses: 0, total: 0 };
+        this.countHit = () => { this.hits += 1; };
+        this.countMiss = () => { this.misses += 1; };
+        this.countRead = () => { this.total += 1; };
+        this.countDisposed = () => { this.disposed += 1; };
+        this.windowed = () => {
+            const window = {
+                disposed: this.disposed - this.reported.disposed,
+                hits: this.hits - this.reported.hits,
+                misses: this.misses - this.reported.misses,
+                total: this.total - this.reported.total,
+            };
+            this.reported = { disposed: this.disposed, hits: this.hits, misses: this.misses, total: this.total };
+            return window;
+        };
+        this.cumulative = () => ({
+            disposed: this.disposed,
+            hits: this.hits,
+            misses: this.misses,
+            total: this.total,
+        });
+    }
+}
+exports.WindowedCounters = WindowedCounters;

package/lib/caches/typings.d.ts

@@ -17,6 +17,15 @@ export type LRUStats = {
     name: string;
     total: number;
 };
+export type CumulativeStats = {
+    hits?: number;
+    total?: number;
+    misses?: number;
+    disposedItems?: number;
+    itemCount?: number;
+    length?: number;
+    max?: number;
+};
 export type MultilayerStats = {
     hitRate: number | undefined;
     hits: number;

package/lib/metrics/DiagnosticsMetrics.d.ts

@@ -1,4 +1,8 @@
-import { Attributes } from '@opentelemetry/api';
+import { Attributes, MetricOptions, ObservableCallback } from '@opentelemetry/api';
+import { CumulativeStats } from '../caches/typings';
+export interface TrackedCache {
+    getCumulativeStats(): CumulativeStats;
+}
 /**
  * DiagnosticsMetrics provides a high-level API for recording metrics using
  * the @vtex/diagnostics-nodejs library. It completely abstracts instrument
@@ -56,8 +60,12 @@ export declare class DiagnosticsMetrics {
     private metricsClient;
     private clientInitPromise;
     private latencyHistogram;
-    private counters;
-    private gauges;
+    private readonly counters;
+    private readonly gauges;
+    private readonly observableRegistrations;
+    private readonly observableInstruments;
+    private readonly cacheRegistry;
+    private cacheInstruments;
     constructor();
     /**
      * Initialize the metrics client with timeout handling.
@@ -118,20 +126,29 @@ export declare class DiagnosticsMetrics {
      * @returns Merged attributes (base + non-conflicting limited custom) or undefined if both are empty
      */
     private mergeAttributes;
+    /**
+     * The reason `name` cannot carry a new instrument, or undefined when it can. The SDK
+     * accepts two same-named streams silently and the collector then rejects them, so a name
+     * is owned by whichever instrument took it first: reusing it through the other API, or
+     * under the other kind, is a conflict. Reusing it in place — same API, same kind — is a
+     * replace, not a conflict.
+     */
+    private nameConflict;
+    private pushInstruments;
+    /**
+     * Counter and gauge instruments are created once per name and reused.
+     */
+    private instrumentFor;
     /**
      * Record a latency measurement using the single shared histogram.
      * Accepts either an hrtime tuple from process.hrtime() or milliseconds as a number.
      * Use attributes to differentiate between different operations.
      *
-     * Base attributes from the current context (set via `runWithBaseAttributes`) are
-     * automatically merged with the provided custom attributes. Base attributes take
-     * precedence - if a custom attribute key conflicts with a base attribute key,
-     * the custom attribute is silently dropped.
-     *
-     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     * Base attributes from `runWithBaseAttributes` are merged in automatically and take
+     * precedence; custom attributes are capped at MAX_CUSTOM_ATTRIBUTES (7). See the class doc.
      *
      * @param value Either [seconds, nanoseconds] from process.hrtime() or milliseconds
-     * @param attributes Custom attributes including 'operation' to identify the operation type (max 5 custom attributes)
+     * @param attributes Custom attributes including 'operation' to identify the operation type (max 7 custom attributes)
      *
      * @example
      * ```typescript
@@ -148,16 +165,12 @@ export declare class DiagnosticsMetrics {
      * Increment a counter by a specific value.
      * Multiple counters are stored by name since counters represent different types of events.
      *
-     * Base attributes from the current context (set via `runWithBaseAttributes`) are
-     * automatically merged with the provided custom attributes. Base attributes take
-     * precedence - if a custom attribute key conflicts with a base attribute key,
-     * the custom attribute is silently dropped.
-     *
-     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     * Base attributes from `runWithBaseAttributes` are merged in automatically and take
+     * precedence; custom attributes are capped at MAX_CUSTOM_ATTRIBUTES (7). See the class doc.
      *
      * @param name Counter name (e.g., 'http_requests_total', 'cache_hits_total')
      * @param value Amount to increment by (typically 1)
-     * @param attributes Optional custom attributes for the counter (max 5 custom attributes, e.g., { method: 'GET', status: '2xx' })
+     * @param attributes Optional custom attributes for the counter (max 7 custom attributes, e.g., { method: 'GET', status: '2xx' })
      *
      * @example
      * ```typescript
@@ -169,16 +182,12 @@ export declare class DiagnosticsMetrics {
      * Set a gauge to a specific value (current state).
      * Multiple gauges are stored by name since gauges represent different types of measurements.
      *
-     * Base attributes from the current context (set via `runWithBaseAttributes`) are
-     * automatically merged with the provided custom attributes. Base attributes take
-     * precedence - if a custom attribute key conflicts with a base attribute key,
-     * the custom attribute is silently dropped.
-     *
-     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     * Base attributes from `runWithBaseAttributes` are merged in automatically and take
+     * precedence; custom attributes are capped at MAX_CUSTOM_ATTRIBUTES (7). See the class doc.
      *
      * @param name Gauge name (e.g., 'cache_items_current', 'memory_usage_bytes')
      * @param value Current value
-     * @param attributes Optional custom attributes for the gauge (max 5 custom attributes, e.g., { cache: 'pages' })
+     * @param attributes Optional custom attributes for the gauge (max 7 custom attributes, e.g., { cache: 'pages' })
      *
      * @example
      * ```typescript
@@ -186,4 +195,12 @@ export declare class DiagnosticsMetrics {
      * ```
      */
     setGauge(name: string, value: number, attributes?: Attributes): void;
+    registerObservableGauge(name: string, observe: ObservableCallback, options?: MetricOptions): () => void;
+    registerObservableCounter(name: string, observe: ObservableCallback, options?: MetricOptions): () => void;
+    private registerObservable;
+    private syncObservables;
+    private flushPendingObservables;
+    trackCache(name: string, cacheInstance: TrackedCache): () => void;
+    private ensureCacheInstruments;
+    private observeCaches;
 }

package/lib/metrics/DiagnosticsMetrics.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiagnosticsMetrics = void 0;
 const api_1 = require("@opentelemetry/api");
-const client_1 = require("../service/metrics/client");
 const constants_1 = require("../constants");
+const client_1 = require("../service/metrics/client");
 /**
  * Maximum number of custom attributes allowed per metric call to control cardinality.
  * This limit applies only to custom attributes provided by callers (VTEX IO Apps).
@@ -17,6 +17,19 @@ const MAX_CUSTOM_ATTRIBUTES = 7;
  * These attributes are automatically merged with custom attributes in all metric methods.
  */
 const BASE_ATTRIBUTES_KEY = (0, api_1.createContextKey)('vtex.metrics.baseAttributes');
+// trackCache() metric names — one shared instrument set, differentiated by `cache`.
+const CACHE_OPERATIONS_METRIC = 'io_app_cache_operations_total';
+const CACHE_ITEMS_METRIC = 'io_app_cache_items_current';
+const CACHE_CAPACITY_METRIC = 'io_app_cache_capacity';
+const CACHE_DISPOSED_METRIC = 'io_app_cache_disposed_total';
+// Names owned by trackCache(), which creates them straight on the client. An app
+// registering one of them as its own observable would publish a duplicate stream.
+const CACHE_METRIC_NAMES = new Set([
+    CACHE_OPERATIONS_METRIC,
+    CACHE_ITEMS_METRIC,
+    CACHE_CAPACITY_METRIC,
+    CACHE_DISPOSED_METRIC,
+]);
 /**
  * Converts an hrtime tuple [seconds, nanoseconds] to milliseconds.
  */
@@ -46,6 +59,50 @@ function limitCustomAttributes(customAttributes) {
     }
     return Object.fromEntries(entries.slice(0, MAX_CUSTOM_ATTRIBUTES));
 }
+/**
+ * A cache with no `max` reports Infinity (lru-cache@5's default for a missing one), so
+ * the capacity gauge publishes the sentinel the catalog documents instead.
+ */
+function capacityOrSentinel(max) {
+    return Number.isFinite(max) ? max : Number.MAX_SAFE_INTEGER;
+}
+/**
+ * The cache's miss count. A cache that reports misses directly wins: deriving them from
+ * `total - hits` reads as a decrease while a read is in flight across a collection cycle,
+ * and the SDK turns a decrease on a monotonic counter into a reset.
+ */
+function missesOf(stats) {
+    var _a, _b;
+    if (typeof stats.misses === 'number') {
+        return stats.misses;
+    }
+    return Math.max(((_a = stats.total) !== null && _a !== void 0 ? _a : 0) - ((_b = stats.hits) !== null && _b !== void 0 ? _b : 0), 0);
+}
+/**
+ * A disposer that only releases the entry it was created for. A later registration of
+ * the same name owns that entry, so an older disposer is a no-op instead of tearing
+ * down its successor.
+ */
+function releaseIfOwner(registry, name, entry, onRelease) {
+    return () => {
+        if (registry.get(name) !== entry) {
+            return;
+        }
+        registry.delete(name);
+        if (onRelease) {
+            onRelease();
+        }
+    };
+}
+/**
+ * Applies the same cardinality limit the push methods use to whatever an observable
+ * callback reports. Observables run outside any request, so every attribute is custom.
+ */
+function limitObservableResult(result) {
+    return {
+        observe: (value, attributes) => result.observe(value, limitCustomAttributes(attributes)),
+    };
+}
 /**
  * DiagnosticsMetrics provides a high-level API for recording metrics using
  * the @vtex/diagnostics-nodejs library. It completely abstracts instrument
@@ -103,6 +160,9 @@ class DiagnosticsMetrics {
     constructor() {
         this.counters = new Map();
         this.gauges = new Map();
+        this.observableRegistrations = { gauge: new Map(), counter: new Map() };
+        this.observableInstruments = { gauge: new Map(), counter: new Map() };
+        this.cacheRegistry = new Map();
         this.initMetricClient();
     }
     /**
@@ -124,6 +184,9 @@ class DiagnosticsMetrics {
                 ]);
                 // Create the single latency histogram after client is ready
                 this.createLatencyHistogram();
+                // Attach any observable registrations made before the client was ready.
+                // No-op if there are none.
+                this.flushPendingObservables();
                 return this.metricsClient;
             }
             catch (error) {
@@ -225,20 +288,48 @@ class DiagnosticsMetrics {
         // Merge: base attributes + non-conflicting custom attributes
         return { ...baseAttributes, ...nonConflictingCustomAttributes };
     }
+    /**
+     * The reason `name` cannot carry a new instrument, or undefined when it can. The SDK
+     * accepts two same-named streams silently and the collector then rejects them, so a name
+     * is owned by whichever instrument took it first: reusing it through the other API, or
+     * under the other kind, is a conflict. Reusing it in place — same API, same kind — is a
+     * replace, not a conflict.
+     */
+    nameConflict(name, kind, origin) {
+        if (CACHE_METRIC_NAMES.has(name)) {
+            return 'reserved for trackCache()';
+        }
+        const other = kind === 'gauge' ? 'counter' : 'gauge';
+        const foreign = origin === 'push'
+            ? [this.observableRegistrations[kind], this.observableRegistrations[other], this.pushInstruments(other)]
+            : [this.pushInstruments(kind), this.pushInstruments(other), this.observableRegistrations[other]];
+        return foreign.some(instruments => instruments.has(name)) ? 'already used by another instrument' : undefined;
+    }
+    pushInstruments(kind) {
+        return kind === 'counter' ? this.counters : this.gauges;
+    }
+    /**
+     * Counter and gauge instruments are created once per name and reused.
+     */
+    instrumentFor(map, name, create) {
+        const existing = map.get(name);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const instrument = create();
+        map.set(name, instrument);
+        return instrument;
+    }
     /**
      * Record a latency measurement using the single shared histogram.
      * Accepts either an hrtime tuple from process.hrtime() or milliseconds as a number.
      * Use attributes to differentiate between different operations.
      *
-     * Base attributes from the current context (set via `runWithBaseAttributes`) are
-     * automatically merged with the provided custom attributes. Base attributes take
-     * precedence - if a custom attribute key conflicts with a base attribute key,
-     * the custom attribute is silently dropped.
-     *
-     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     * Base attributes from `runWithBaseAttributes` are merged in automatically and take
+     * precedence; custom attributes are capped at MAX_CUSTOM_ATTRIBUTES (7). See the class doc.
      *
      * @param value Either [seconds, nanoseconds] from process.hrtime() or milliseconds
-     * @param attributes Custom attributes including 'operation' to identify the operation type (max 5 custom attributes)
+     * @param attributes Custom attributes including 'operation' to identify the operation type (max 7 custom attributes)
      *
      * @example
      * ```typescript
@@ -266,16 +357,12 @@ class DiagnosticsMetrics {
      * Increment a counter by a specific value.
      * Multiple counters are stored by name since counters represent different types of events.
      *
-     * Base attributes from the current context (set via `runWithBaseAttributes`) are
-     * automatically merged with the provided custom attributes. Base attributes take
-     * precedence - if a custom attribute key conflicts with a base attribute key,
-     * the custom attribute is silently dropped.
-     *
-     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     * Base attributes from `runWithBaseAttributes` are merged in automatically and take
+     * precedence; custom attributes are capped at MAX_CUSTOM_ATTRIBUTES (7). See the class doc.
      *
      * @param name Counter name (e.g., 'http_requests_total', 'cache_hits_total')
      * @param value Amount to increment by (typically 1)
-     * @param attributes Optional custom attributes for the counter (max 5 custom attributes, e.g., { method: 'GET', status: '2xx' })
+     * @param attributes Optional custom attributes for the counter (max 7 custom attributes, e.g., { method: 'GET', status: '2xx' })
      *
      * @example
      * ```typescript
@@ -287,33 +374,25 @@ class DiagnosticsMetrics {
             console.warn('DiagnosticsMetrics not initialized. Call initialize() first.');
             return;
         }
-        // Get or create counter instrument
-        if (!this.counters.has(name)) {
-            const counter = this.metricsClient.createCounter(name, {
-                description: `Counter for ${name}`,
-                unit: '1',
-            });
-            this.counters.set(name, counter);
+        const conflict = this.nameConflict(name, 'counter', 'push');
+        if (conflict) {
+            console.error(`DiagnosticsMetrics: '${name}' is ${conflict}; ignoring the counter. Pick a distinct metric name.`);
+            return;
         }
-        // Merge base attributes from context with custom attributes (custom attrs are limited internally)
-        const mergedAttributes = this.mergeAttributes(attributes);
-        // Increment the counter
-        this.counters.get(name).add(value, mergedAttributes);
+        const counter = this.instrumentFor(this.counters, name, () => this.metricsClient.createCounter(name, { description: `Counter for ${name}`, unit: '1' }));
+        // mergeAttributes() limits custom attributes internally
+        counter.add(value, this.mergeAttributes(attributes));
     }
     /**
      * Set a gauge to a specific value (current state).
      * Multiple gauges are stored by name since gauges represent different types of measurements.
      *
-     * Base attributes from the current context (set via `runWithBaseAttributes`) are
-     * automatically merged with the provided custom attributes. Base attributes take
-     * precedence - if a custom attribute key conflicts with a base attribute key,
-     * the custom attribute is silently dropped.
-     *
-     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     * Base attributes from `runWithBaseAttributes` are merged in automatically and take
+     * precedence; custom attributes are capped at MAX_CUSTOM_ATTRIBUTES (7). See the class doc.
      *
      * @param name Gauge name (e.g., 'cache_items_current', 'memory_usage_bytes')
      * @param value Current value
-     * @param attributes Optional custom attributes for the gauge (max 5 custom attributes, e.g., { cache: 'pages' })
+     * @param attributes Optional custom attributes for the gauge (max 7 custom attributes, e.g., { cache: 'pages' })
      *
      * @example
      * ```typescript
@@ -325,18 +404,148 @@ class DiagnosticsMetrics {
             console.warn('DiagnosticsMetrics not initialized. Call initialize() first.');
             return;
         }
-        // Get or create gauge instrument
-        if (!this.gauges.has(name)) {
-            const gauge = this.metricsClient.createGauge(name, {
-                description: `Gauge for ${name}`,
-                unit: '1',
-            });
-            this.gauges.set(name, gauge);
+        const conflict = this.nameConflict(name, 'gauge', 'push');
+        if (conflict) {
+            console.error(`DiagnosticsMetrics: '${name}' is ${conflict}; ignoring the gauge. Pick a distinct metric name.`);
+            return;
+        }
+        const gauge = this.instrumentFor(this.gauges, name, () => this.metricsClient.createGauge(name, { description: `Gauge for ${name}`, unit: '1' }));
+        // mergeAttributes() limits custom attributes internally
+        gauge.set(value, this.mergeAttributes(attributes));
+    }
+    // Registers (or replaces) a pull-based gauge: OTel calls `observe` on its own schedule
+    // with `result.observe(value, attributes?)`. No base-attribute merging (no request is
+    // in progress), but reported attributes keep the MAX_CUSTOM_ATTRIBUTES limit.
+    registerObservableGauge(name, observe, options) {
+        return this.registerObservable('gauge', name, observe, options);
+    }
+    // Same as registerObservableGauge, but `observe` reports the cumulative total —
+    // the SDK derives the delta itself.
+    registerObservableCounter(name, observe, options) {
+        return this.registerObservable('counter', name, observe, options);
+    }
+    registerObservable(kind, name, observe, options) {
+        const conflict = this.nameConflict(name, kind, 'observable');
+        if (conflict) {
+            console.error(`DiagnosticsMetrics: '${name}' is ${conflict}; ignoring the ${kind} registration. ` +
+                `Pick a distinct metric name.`);
+            return () => undefined;
+        }
+        const registration = { observe, options };
+        this.observableRegistrations[kind].set(name, registration);
+        this.syncObservables(kind);
+        return releaseIfOwner(this.observableRegistrations[kind], name, registration, () => {
+            var _a;
+            (_a = this.observableInstruments[kind].get(name)) === null || _a === void 0 ? void 0 : _a.remove();
+            this.observableInstruments[kind].delete(name);
+        });
+    }
+    // Attaches every `kind` registration to its instrument; a no-op when there is nothing
+    // registered or the client is not ready. One instrument per name, with a callback that
+    // trampolines over the current registration — re-creating it would duplicate the stream.
+    syncObservables(kind) {
+        if (this.observableRegistrations[kind].size === 0) {
+            return; // skip the meter entirely if this kind is unused
+        }
+        const client = this.metricsClient;
+        if (!client) {
+            return;
+        }
+        for (const [name, { options }] of this.observableRegistrations[kind]) {
+            if (this.observableInstruments[kind].has(name)) {
+                continue; // already attached; options apply only on the first registration
+            }
+            const attached = (result) => {
+                var _a;
+                (_a = this.observableRegistrations[kind].get(name)) === null || _a === void 0 ? void 0 : _a.observe(limitObservableResult(result));
+            };
+            const instrument = kind === 'gauge'
+                ? client.createObservableGauge(name, attached, options)
+                : client.createObservableCounter(name, attached, options);
+            this.observableInstruments[kind].set(name, instrument);
+        }
+    }
+    // Runs once the client is ready. No-op for an app that never calls
+    // registerObservableGauge/Counter/trackCache.
+    flushPendingObservables() {
+        this.syncObservables('gauge');
+        this.syncObservables('counter');
+        if (this.cacheRegistry.size > 0) {
+            this.ensureCacheInstruments();
+        }
+    }
+    // Replacement for the legacy MetricsAccumulator.trackCache() over the same cache
+    // instances; reads getCumulativeStats(), which has no side effects. See METRICS_CATALOG.md.
+    trackCache(name, cacheInstance) {
+        const registration = { cache: cacheInstance };
+        this.cacheRegistry.set(name, registration);
+        this.ensureCacheInstruments();
+        return releaseIfOwner(this.cacheRegistry, name, registration);
+    }
+    ensureCacheInstruments() {
+        if (this.cacheInstruments) {
+            return;
+        }
+        const client = this.metricsClient;
+        if (!client) {
+            return;
+        }
+        const operations = client.createObservableCounter(CACHE_OPERATIONS_METRIC, undefined, {
+            description: 'Hit/miss operations for a VTEX IO app in-memory cache',
+            unit: '1',
+        });
+        const items = client.createObservableGauge(CACHE_ITEMS_METRIC, undefined, {
+            description: 'Current number of items held by a VTEX IO app cache',
+            unit: '1',
+        });
+        const capacity = client.createObservableGauge(CACHE_CAPACITY_METRIC, undefined, {
+            description: 'Capacity of a VTEX IO app cache, in the units that cache uses (item count, unless the LRU was built with a length function)',
+            unit: '1',
+        });
+        const disposed = client.createObservableCounter(CACHE_DISPOSED_METRIC, undefined, {
+            description: 'Items disposed (evicted) from a VTEX IO app cache',
+            unit: '1',
+        });
+        client.addBatchObservableCallback((result) => this.observeCaches(result), [operations.instrument, items.instrument, capacity.instrument, disposed.instrument]);
+        // These live for the process, so only the handles are kept: the wrappers exist
+        // to attach the batch callback above.
+        this.cacheInstruments = {
+            capacity: capacity.instrument,
+            disposed: disposed.instrument,
+            items: items.instrument,
+            operations: operations.instrument,
+        };
+    }
+    // Reads each registered cache's cumulative counters straight into the instruments.
+    observeCaches(result) {
+        if (!this.cacheInstruments) {
+            return;
+        }
+        const { operations, items, capacity, disposed } = this.cacheInstruments;
+        for (const [name, { cache }] of this.cacheRegistry) {
+            let stats;
+            try {
+                stats = cache.getCumulativeStats();
+            }
+            catch (error) {
+                console.error('DiagnosticsMetrics: failed to read stats for cache', name, error);
+                continue;
+            }
+            const attributes = { cache: name };
+            if (typeof stats.hits === 'number' && typeof stats.total === 'number') {
+                result.observe(operations, stats.hits, { ...attributes, cache_state: 'hit' });
+                result.observe(operations, missesOf(stats), { ...attributes, cache_state: 'miss' });
+            }
+            if (typeof stats.itemCount === 'number') {
+                result.observe(items, stats.itemCount, attributes);
+            }
+            if (typeof stats.max === 'number') {
+                result.observe(capacity, capacityOrSentinel(stats.max), attributes);
+            }
+            if (typeof stats.disposedItems === 'number') {
+                result.observe(disposed, stats.disposedItems, attributes);
+            }
         }
-        // Merge base attributes from context with custom attributes (custom attrs are limited internally)
-        const mergedAttributes = this.mergeAttributes(attributes);
-        // Set the gauge value
-        this.gauges.get(name).set(value, mergedAttributes);
     }
 }
 exports.DiagnosticsMetrics = DiagnosticsMetrics;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/api",
-  "version": "7.5.0",
+  "version": "7.5.1-beta.1",
   "description": "VTEX I/O API client",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -53,8 +53,8 @@
     "@opentelemetry/instrumentation-koa": "0.47.1",
     "@types/koa": "^2.11.0",
     "@types/koa-compose": "^3.2.3",
-    "@vtex/diagnostics-nodejs": "0.1.8-io",
-    "@vtex/diagnostics-semconv": "5.5.2",
+    "@vtex/diagnostics-nodejs": "0.1.8-io-beta.4",
+    "@vtex/diagnostics-semconv": "5.5.3",
     "@vtex/node-error-report": "^0.0.3",
     "@wry/equality": "^0.1.9",
     "agentkeepalive": "^4.0.2",
@@ -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",