@vtex/api 7.5.1-beta.0 → 7.5.1-beta.2

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.2]
+
+### 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`)
+
+### Changed
+
+- `@vtex/diagnostics-nodejs` pinned to `0.2.0-io`, the IO line's current tag, replacing the
+  `0.1.8-io-beta.4` beta
+
 ## [7.5.0]
 
 ### Added

package/lib/caches/DiskCache.d.ts

@@ -5,10 +5,8 @@ export declare class DiskCache<V> implements CacheLayer<string, V> {
     private cachePath;
     private readFile;
     private writeFile;
-    private hits;
-    private total;
+    private readonly counters;
     private lock;
-    private reported;
     constructor(cachePath: string, readFile?: typeof readJSON, writeFile?: typeof outputJSON);
     has: (key: string) => boolean;
     getStats: (name?: string) => DiskStats;

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,39 +13,33 @@ class DiskCache {
         this.cachePath = cachePath;
         this.readFile = readFile;
         this.writeFile = writeFile;
-        this.hits = 0;
-        this.total = 0;
-        this.reported = { hits: 0, 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 - this.reported.hits,
-                name,
-                total: this.total - this.reported.total,
-            };
-            this.reported = { hits: this.hits, total: this.total };
-            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.getCumulativeStats = () => ({
-            hits: this.hits,
-            total: this.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);
                     }
                 });
@@ -60,7 +55,7 @@ class DiskCache {
                         release();
                         resolve(writePromise);
                     }
-                    catch (e) {
+                    catch {
                         release();
                         resolve(true);
                     }

package/lib/caches/LRUCache.d.ts

@@ -4,10 +4,7 @@ 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;
+    private readonly counters;
     constructor(options: LRU.Options<K, V>);
     get: (key: K) => V | void;
     getOrSet: (key: K, fetcher?: () => Promise<FetchResult<V>>) => Promise<V | void>;

package/lib/caches/LRUCache.js

@@ -6,24 +6,27 @@ 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 hits = this.hits - this.reported.hits;
-            const total = this.total - this.reported.total;
-            const stats = {
-                disposedItems: this.disposed - this.reported.disposed,
+            const { disposed, hits, total } = this.counters.windowed();
+            return {
+                disposedItems: disposed,
                 hitRate: total > 0 ? hits / total : undefined,
                 hits,
                 itemCount: this.storage.itemCount,
@@ -32,24 +35,23 @@ class LRUCache {
                 name,
                 total,
             };
-            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.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.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

@@ -6,12 +6,9 @@ export declare class LRUDiskCache<V> implements CacheLayer<string, V> {
     private readFile;
     private writeFile;
     private lock;
-    private disposed;
-    private hits;
-    private total;
+    private readonly counters;
     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;

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,15 +14,11 @@ class LRUDiskCache {
         this.cachePath = cachePath;
         this.readFile = readFile;
         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 - this.reported.disposed,
+            const { disposed, hits, total } = this.counters.windowed();
+            return {
+                disposedItems: disposed,
                 hitRate: total > 0 ? hits / total : undefined,
                 hits,
                 itemCount: this.lruStorage.itemCount,
@@ -30,21 +27,24 @@ class LRUDiskCache {
                 name,
                 total,
             };
-            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.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.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);
@@ -57,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);
                     }
                 });
@@ -93,7 +94,7 @@ class LRUDiskCache {
                         release();
                         resolve(writePromise);
                     }
-                    catch (e) {
+                    catch {
                         release();
                         resolve(true);
                     }
@@ -114,7 +115,7 @@ class LRUDiskCache {
                         release();
                         resolve(removePromise);
                     }
-                    catch (e) {
+                    catch {
                         release();
                         resolve(true);
                     }
@@ -122,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

@@ -2,9 +2,7 @@ import { CacheLayer } from './CacheLayer';
 import { CumulativeStats, FetchResult, MultilayerStats } from './typings';
 export declare class MultilayeredCache<K, V> implements CacheLayer<K, V> {
     private caches;
-    private hits;
-    private total;
-    private reported;
+    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>;

package/lib/caches/MultilayeredCache.js

@@ -2,12 +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.reported = { hits: 0, total: 0 };
+        this.counters = new WindowedCounters_1.WindowedCounters();
         this.get = async (key, fetcher) => {
             let value = undefined;
             let maxAge;
@@ -41,30 +40,28 @@ 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 = {
+            const { hits, total } = this.counters.windowed();
+            return {
                 hitRate: total > 0 ? hits / total : undefined,
                 hits,
                 name,
                 total,
             };
-            this.reported = { hits: this.hits, total: this.total };
-            return multilayerStats;
         };
-        this.getCumulativeStats = () => ({
-            hits: this.hits,
-            total: this.total,
-        });
+        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;
         };
     }

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

@@ -18,8 +18,9 @@ export type LRUStats = {
     total: number;
 };
 export type CumulativeStats = {
-    hits: number;
-    total: number;
+    hits?: number;
+    total?: number;
+    misses?: number;
     disposedItems?: number;
     itemCount?: number;
     length?: number;

package/lib/metrics/DiagnosticsMetrics.d.ts

@@ -3,6 +3,7 @@ import { CumulativeStats } from '../caches/typings';
 export interface TrackedCache {
     getCumulativeStats(): CumulativeStats;
 }
+type ObservableMetricOptions = Pick<MetricOptions, 'description' | 'unit'>;
 /**
  * DiagnosticsMetrics provides a high-level API for recording metrics using
  * the @vtex/diagnostics-nodejs library. It completely abstracts instrument
@@ -72,6 +73,7 @@ export declare class DiagnosticsMetrics {
      * Called automatically in constructor.
      */
     private initMetricClient;
+    private warnPendingRegistrations;
     /**
      * Create the single shared histogram for all latency measurements.
      * Called after metric client is initialized.
@@ -126,20 +128,34 @@ 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.
+     *
+     * Disposing leaves a gap: remove() only detaches the callback, so the meter keeps the
+     * instrument and this check stops seeing the name. Reusing it under the other kind from
+     * then on would duplicate the stream, which only bites under cumulative temporality (a
+     * delta export drops the orphan). Re-registering the same kind after dispose is safe.
+     */
+    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
@@ -156,16 +172,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
@@ -177,16 +189,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
@@ -194,8 +202,8 @@ 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;
+    registerObservableGauge(name: string, observe: ObservableCallback, options?: ObservableMetricOptions): () => void;
+    registerObservableCounter(name: string, observe: ObservableCallback, options?: ObservableMetricOptions): () => void;
     private registerObservable;
     private syncObservables;
     private flushPendingObservables;
@@ -203,3 +211,4 @@ export declare class DiagnosticsMetrics {
     private ensureCacheInstruments;
     private observeCaches;
 }
+export {};

package/lib/metrics/DiagnosticsMetrics.js

@@ -22,6 +22,14 @@ 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.
  */
@@ -52,9 +60,43 @@ 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.
+ * 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 {
@@ -132,10 +174,11 @@ class DiagnosticsMetrics {
             return this.clientInitPromise;
         }
         this.clientInitPromise = (async () => {
+            let timeoutId;
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error('Metric client initialization timeout')), constants_1.METRIC_CLIENT_INIT_TIMEOUT_MS);
+            });
             try {
-                const timeoutPromise = new Promise((_, reject) => {
-                    setTimeout(() => reject(new Error('Metric client initialization timeout')), constants_1.METRIC_CLIENT_INIT_TIMEOUT_MS);
-                });
                 this.metricsClient = await Promise.race([
                     (0, client_1.getMetricClient)(),
                     timeoutPromise
@@ -143,17 +186,39 @@ 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();
+                try {
+                    this.flushPendingObservables();
+                }
+                catch (error) {
+                    // The client is up; only the pending registrations failed to attach.
+                    console.error('Failed to attach the pending observable registrations:', error);
+                }
                 return this.metricsClient;
             }
             catch (error) {
                 console.error('Failed to initialize metric client:', error);
+                this.warnPendingRegistrations();
                 return undefined;
             }
+            finally {
+                // Promise.race leaves the loser running, so the timeout timer needs clearing.
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+            }
         })();
         return this.clientInitPromise;
     }
+    // Registrations that never attach should be reported once, not left for an app to
+    // discover through a dashboard with missing series.
+    warnPendingRegistrations() {
+        const pending = this.cacheRegistry.size +
+            this.observableRegistrations.gauge.size +
+            this.observableRegistrations.counter.size;
+        if (pending > 0) {
+            console.warn(`DiagnosticsMetrics: metric client unavailable; ${pending} pending registration(s) are not being published.`);
+        }
+    }
     /**
      * Create the single shared histogram for all latency measurements.
      * Called after metric client is initialized.
@@ -246,20 +311,53 @@ 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.
+     *
+     * Disposing leaves a gap: remove() only detaches the callback, so the meter keeps the
+     * instrument and this check stops seeing the name. Reusing it under the other kind from
+     * then on would duplicate the stream, which only bites under cumulative temporality (a
+     * delta export drops the orphan). Re-registering the same kind after dispose is safe.
+     */
+    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
@@ -287,16 +385,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
@@ -308,33 +402,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
@@ -346,23 +432,18 @@ 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;
         }
-        // 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);
+        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 —
-    // 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.
+    // 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);
     }
@@ -372,38 +453,24 @@ class DiagnosticsMetrics {
         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.`);
+        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;
         }
-        this.observableRegistrations[kind].set(name, { observe, options });
+        const registration = { observe, options };
+        this.observableRegistrations[kind].set(name, registration);
         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();
+        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 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.
+    // 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
@@ -414,7 +481,7 @@ class DiagnosticsMetrics {
         }
         for (const [name, { options }] of this.observableRegistrations[kind]) {
             if (this.observableInstruments[kind].has(name)) {
-                continue;
+                continue; // already attached; options apply only on the first registration
             }
             const attached = (result) => {
                 var _a;
@@ -435,15 +502,19 @@ class DiagnosticsMetrics {
             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().
+    // 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) {
-        this.cacheRegistry.set(name, cacheInstance);
+        // TrackedCache is a compile-time contract only: a JS caller, or a cache built by
+        // another copy of @vtex/api, would otherwise throw on every collection cycle.
+        if (typeof (cacheInstance === null || cacheInstance === void 0 ? void 0 : cacheInstance.getCumulativeStats) !== 'function') {
+            console.error(`DiagnosticsMetrics: '${name}' does not implement getCumulativeStats(); ignoring the cache registration.`);
+            return () => undefined;
+        }
+        const registration = { cache: cacheInstance };
+        this.cacheRegistry.set(name, registration);
         this.ensureCacheInstruments();
-        return () => {
-            this.cacheRegistry.delete(name);
-        };
+        return releaseIfOwner(this.cacheRegistry, name, registration);
     }
     ensureCacheInstruments() {
         if (this.cacheInstruments) {
@@ -473,10 +544,10 @@ class DiagnosticsMetrics {
         // 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,
+            items: items.instrument,
+            operations: operations.instrument,
         };
     }
     // Reads each registered cache's cumulative counters straight into the instruments.
@@ -485,7 +556,7 @@ class DiagnosticsMetrics {
             return;
         }
         const { operations, items, capacity, disposed } = this.cacheInstruments;
-        for (const [name, cache] of this.cacheRegistry) {
+        for (const [name, { cache }] of this.cacheRegistry) {
             let stats;
             try {
                 stats = cache.getCumulativeStats();
@@ -497,13 +568,13 @@ class DiagnosticsMetrics {
             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' });
+                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, stats.max, attributes);
+                result.observe(capacity, capacityOrSentinel(stats.max), attributes);
             }
             if (typeof stats.disposedItems === 'number') {
                 result.observe(disposed, stats.disposedItems, attributes);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/api",
-  "version": "7.5.1-beta.0",
+  "version": "7.5.1-beta.2",
   "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-beta.4",
-    "@vtex/diagnostics-semconv": "5.5.2",
+    "@vtex/diagnostics-nodejs": "0.2.0-io",
+    "@vtex/diagnostics-semconv": "5.5.3",
     "@vtex/node-error-report": "^0.0.3",
     "@wry/equality": "^0.1.9",
     "agentkeepalive": "^4.0.2",