@vtex/api 7.5.0 → 7.5.1-beta.0

package/lib/caches/DiskCache.d.ts

@@ -1,5 +1,5 @@
 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;
@@ -8,9 +8,11 @@ export declare class DiskCache<V> implements CacheLayer<string, V> {
     private hits;
     private total;
     private lock;
+    private reported;
     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

@@ -14,20 +14,24 @@ class DiskCache {
         this.writeFile = writeFile;
         this.hits = 0;
         this.total = 0;
+        this.reported = { hits: 0, total: 0 };
         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,
+                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;
         };
+        this.getCumulativeStats = () => ({
+            hits: this.hits,
+            total: this.total,
+        });
         this.get = async (key) => {
             const pathKey = this.getPathKey(key);
             this.total += 1;

package/lib/caches/LRUCache.d.ts

@@ -1,16 +1,18 @@
 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 reported;
     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

@@ -20,24 +20,33 @@ class LRUCache {
         this.set = (key, value, maxAge) => this.storage.set(key, value, maxAge);
         this.has = (key) => this.storage.has(key);
         this.getStats = (name = 'lru-cache') => {
+            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;
         };
+        this.getCumulativeStats = () => ({
+            disposedItems: this.disposed,
+            hits: this.hits,
+            itemCount: this.storage.itemCount,
+            length: this.storage.length,
+            max: this.storage.max,
+            total: this.total,
+        });
         this.hits = 0;
         this.total = 0;
         this.disposed = 0;
+        this.reported = { disposed: 0, hits: 0, total: 0 };
         this.storage = new lru_cache_1.default({
             ...options,
             dispose: () => this.disposed += 1,

package/lib/caches/LRUDiskCache.d.ts

@@ -1,5 +1,5 @@
 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;
@@ -11,9 +11,11 @@ export declare class LRUDiskCache<V> implements CacheLayer<string, V> {
     private total;
     private lruStorage;
     private keyToBeDeleted;
+    private reported;
     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

@@ -15,23 +15,32 @@ class LRUDiskCache {
         this.writeFile = writeFile;
         this.hits = 0;
         this.total = 0;
+        this.reported = { disposed: 0, hits: 0, total: 0 };
         this.has = (key) => this.lruStorage.has(key);
         this.getStats = (name = 'disk-lru-cache') => {
+            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;
         };
+        this.getCumulativeStats = () => ({
+            disposedItems: this.disposed,
+            hits: this.hits,
+            itemCount: this.lruStorage.itemCount,
+            length: this.lruStorage.length,
+            max: this.lruStorage.max,
+            total: this.total,
+        });
         this.get = async (key) => {
             const timeOfDeath = this.lruStorage.get(key);
             this.total += 1;

package/lib/caches/MultilayeredCache.d.ts

@@ -1,14 +1,15 @@
 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 reported;
     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

@@ -7,6 +7,7 @@ class MultilayeredCache {
         this.caches = caches;
         this.hits = 0;
         this.total = 0;
+        this.reported = { hits: 0, total: 0 };
         this.get = async (key, fetcher) => {
             let value = undefined;
             let maxAge;
@@ -40,15 +41,21 @@ class MultilayeredCache {
             return (0, ramda_1.any)(item => item, hasList);
         };
         this.getStats = (name = 'multilayred-cache') => {
+            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;
         };
+        this.getCumulativeStats = () => ({
+            hits: this.hits,
+            total: this.total,
+        });
         this.findIndex = async (func, array) => {
             this.total += 1;
             for (let index = 0; index < array.length; index++) {
@@ -61,9 +68,5 @@ class MultilayeredCache {
             return -1;
         };
     }
-    resetCounters() {
-        this.hits = 0;
-        this.total = 0;
-    }
 }
 exports.MultilayeredCache = MultilayeredCache;

package/lib/caches/typings.d.ts

@@ -17,6 +17,14 @@ export type LRUStats = {
     name: string;
     total: number;
 };
+export type CumulativeStats = {
+    hits: number;
+    total: 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.
@@ -186,4 +194,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,11 @@ 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';
 /**
  * Converts an hrtime tuple [seconds, nanoseconds] to milliseconds.
  */
@@ -46,6 +51,16 @@ function limitCustomAttributes(customAttributes) {
     }
     return Object.fromEntries(entries.slice(0, MAX_CUSTOM_ATTRIBUTES));
 }
+/**
+ * Applies the same cardinality limit the push-based methods use to whatever an
+ * observable callback reports. Observables run outside any request, so there are no
+ * base attributes to merge — every attribute here is a custom one.
+ */
+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 +118,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 +142,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) {
@@ -338,5 +359,156 @@ class DiagnosticsMetrics {
         // Set the gauge value
         this.gauges.get(name).set(value, mergedAttributes);
     }
+    // Registers (or replaces) a pull-based gauge: OTel calls `observe` on its own
+    // schedule, with `result.observe(value, attributes?)`. No base-attribute merging —
+    // there's no request in progress when this runs — but the attributes reported are
+    // held to the same MAX_CUSTOM_ATTRIBUTES limit as the push-based methods.
+    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) {
+        // The same name registered as both kinds produces two same-named streams of
+        // different types in one meter, which the SDK accepts silently and the collector
+        // then rejects. Refuse the second one instead of publishing a broken metric.
+        const otherKind = kind === 'gauge' ? 'counter' : 'gauge';
+        if (this.observableRegistrations[otherKind].has(name)) {
+            console.error(`DiagnosticsMetrics: '${name}' is already registered as an observable ${otherKind}; ` +
+                `ignoring the ${kind} registration. Pick a distinct metric name.`);
+            return () => undefined;
+        }
+        this.observableRegistrations[kind].set(name, { observe, options });
+        this.syncObservables(kind);
+        return () => {
+            var _a, _b;
+            // A later registration for the same name owns the instrument now; disposing
+            // this one must not tear that down.
+            if (((_a = this.observableRegistrations[kind].get(name)) === null || _a === void 0 ? void 0 : _a.observe) !== observe) {
+                return;
+            }
+            this.observableRegistrations[kind].delete(name);
+            (_b = this.observableInstruments[kind].get(name)) === null || _b === void 0 ? void 0 : _b.remove();
+            this.observableInstruments[kind].delete(name);
+        };
+    }
+    // Attaches every `kind` registration to its instrument. A no-op if there's nothing
+    // registered or the client isn't ready — safe to call anytime, including from
+    // flushPendingObservables() once the client becomes ready.
+    //
+    // One instrument per name, carrying one callback for its whole life: the callback
+    // is a trampoline that reads whatever registration is current, so replacing the
+    // app's function is a map update and never touches the SDK. Re-creating the
+    // instrument instead would leave the meter holding a stream the collector sees as
+    // a duplicate type for the same name.
+    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;
+            }
+            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() — same cache instances,
+    // see METRICS_CATALOG.md for the metrics emitted. Reads getCumulativeStats(), which
+    // has no side effects, so this can run alongside the legacy trackCache().
+    trackCache(name, cacheInstance) {
+        this.cacheRegistry.set(name, cacheInstance);
+        this.ensureCacheInstruments();
+        return () => {
+            this.cacheRegistry.delete(name);
+        };
+    }
+    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 = {
+            operations: operations.instrument,
+            items: items.instrument,
+            capacity: capacity.instrument,
+            disposed: disposed.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, Math.max(stats.total - stats.hits, 0), { ...attributes, cache_state: 'miss' });
+            }
+            if (typeof stats.itemCount === 'number') {
+                result.observe(items, stats.itemCount, attributes);
+            }
+            if (typeof stats.max === 'number') {
+                result.observe(capacity, stats.max, attributes);
+            }
+            if (typeof stats.disposedItems === 'number') {
+                result.observe(disposed, stats.disposedItems, attributes);
+            }
+        }
+    }
 }
 exports.DiagnosticsMetrics = DiagnosticsMetrics;

package/package.json

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