@vtex/api 7.5.1-beta.1 → 7.6.0

package/CHANGELOG.md

@@ -5,7 +5,7 @@ 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]
+## [7.6.0]
 
 ### Added
 
@@ -18,6 +18,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - `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/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.
@@ -132,6 +134,11 @@ export declare class DiagnosticsMetrics {
      * 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;
@@ -195,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;
@@ -204,3 +211,4 @@ export declare class DiagnosticsMetrics {
     private ensureCacheInstruments;
     private observeCaches;
 }
+export {};

package/lib/metrics/DiagnosticsMetrics.js

@@ -174,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
@@ -185,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.
@@ -294,6 +317,11 @@ class DiagnosticsMetrics {
      * 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)) {
@@ -477,6 +505,12 @@ class DiagnosticsMetrics {
     // 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) {
+        // 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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/api",
-  "version": "7.5.1-beta.1",
+  "version": "7.6.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-beta.4",
+    "@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",