@vtex/api 7.4.2 → 7.5.1-beta.0

package/CHANGELOG.md

@@ -5,7 +5,29 @@ 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).
 
-## [Unreleased]
+## [7.5.0]
+
+### Added
+
+- Kubernetes cluster identity and role (`VTEX_CLUSTER_ID` → `cluster_id`,
+  `VTEX_CLUSTER_ROLE` → `cluster_role`) as shared diagnostics resource
+  attributes, applied centrally to diagnostics metrics and logs. Values are
+  trimmed and omitted independently when empty, enabling cross-cluster
+  dashboards and incident isolation without consuming per-call custom
+  attribute limits.
+
+### Fixed
+
+- `runtime_http_*` metrics no longer emit samples without a `handler` label. Requests
+  that never reach a named handler (unmatched paths, replica-level rate limit
+  rejections, errors before the route pipeline) were counted with
+  `handler: undefined`; Node's cluster IPC serializes worker registries as JSON, which
+  drops `undefined` values, so the aggregated `/metrics` exposed a second, unnamed
+  series that Prometheus reads as `handler=""`. Those requests are now labelled
+  `handler="undefined"` — the same value prom-client rendered locally before cluster
+  aggregation — keeping dashboards and alerts that filter on it working.
+- `/_status` requests are now reported as `handler="builtin:status-track"`, matching
+  the other builtin handlers, instead of falling into the unnamed bucket.
 
 ## [7.4.0] - 2026-06-22
 ### Changed

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/constants.d.ts

@@ -45,6 +45,8 @@ export declare const AttributeKeys: {
     VTEX_IO_WORKSPACE_TYPE: "vtex_io.workspace.type";
     VTEX_IO_APP_ID: "vtex_io.app.id";
     VTEX_IO_APP_AUTHOR_TYPE: "vtex_io.app.author_type";
+    VTEX_IO_CLUSTER_ID: "vtex_io.cluster.id";
+    VTEX_IO_CLUSTER_ROLE: "vtex_io.cluster.role";
 };
 /** @deprecated Use HeaderKeys.CACHE_CONTROL instead */
 export declare const CACHE_CONTROL_HEADER: string;
@@ -114,6 +116,8 @@ export declare const HTTP_SERVER_PORT = 5050;
 export declare const MAX_WORKERS = 4;
 export declare const LINKED: boolean;
 export declare const REGION: string;
+export declare const CLUSTER_ID: string;
+export declare const CLUSTER_ROLE: string;
 export declare const PUBLIC_ENDPOINT: string;
 export declare const APP: {
     ID: string;

package/lib/constants.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOG_CLIENT_INIT_TIMEOUT_MS = exports.cancellableMethods = exports.INSPECT_DEBUGGER_PORT = exports.PRODUCTION = exports.WORKSPACE = exports.ACCOUNT = exports.NODE_ENV = exports.APP = exports.PUBLIC_ENDPOINT = exports.REGION = exports.LINKED = exports.MAX_WORKERS = exports.HTTP_SERVER_PORT = exports.MAX_AGE = exports.UP_SIGNAL = exports.BODY_HASH = exports.PROVIDER_HEADER = exports.TRACE_ID_HEADER = exports.COLOSSUS_PARAMS_HEADER = exports.COLOSSUS_ROUTE_ID_HEADER = exports.COLOSSUS_ROUTE_DECLARER_HEADER = exports.EVENT_HANDLER_ID_HEADER = exports.EVENT_SUBJECT_HEADER = exports.EVENT_SENDER_HEADER = exports.EVENT_KEY_HEADER = exports.WORKSPACE_HEADER = exports.WORKSPACE_IS_PRODUCTION_HEADER = exports.PLATFORM_HEADER = exports.OPERATION_ID_HEADER = exports.ROUTER_CACHE_HEADER = exports.REQUEST_ID_HEADER = exports.CREDENTIAL_HEADER = exports.ACCOUNT_HEADER = exports.ETAG_HEADER = exports.META_HEADER_BUCKET = exports.META_HEADER = exports.BINDING_HEADER = exports.TENANT_HEADER = exports.FORWARDED_HOST_HEADER = exports.LOCALE_HEADER = exports.PRODUCT_HEADER = exports.SESSION_HEADER = exports.SEGMENT_HEADER = exports.CACHE_CONTROL_HEADER = exports.AttributeKeys = exports.HeaderKeys = exports.PID = exports.IS_IO = exports.DEFAULT_WORKSPACE = exports.NODE_VTEX_API_VERSION = void 0;
-exports.DIAGNOSTICS_TELEMETRY_ENABLED = exports.DK_APP_ID = exports.OTEL_EXPORTER_OTLP_ENDPOINT = exports.METRIC_CLIENT_INIT_TIMEOUT_MS = void 0;
+exports.INSPECT_DEBUGGER_PORT = exports.PRODUCTION = exports.WORKSPACE = exports.ACCOUNT = exports.NODE_ENV = exports.APP = exports.PUBLIC_ENDPOINT = exports.CLUSTER_ROLE = exports.CLUSTER_ID = exports.REGION = exports.LINKED = exports.MAX_WORKERS = exports.HTTP_SERVER_PORT = exports.MAX_AGE = exports.UP_SIGNAL = exports.BODY_HASH = exports.PROVIDER_HEADER = exports.TRACE_ID_HEADER = exports.COLOSSUS_PARAMS_HEADER = exports.COLOSSUS_ROUTE_ID_HEADER = exports.COLOSSUS_ROUTE_DECLARER_HEADER = exports.EVENT_HANDLER_ID_HEADER = exports.EVENT_SUBJECT_HEADER = exports.EVENT_SENDER_HEADER = exports.EVENT_KEY_HEADER = exports.WORKSPACE_HEADER = exports.WORKSPACE_IS_PRODUCTION_HEADER = exports.PLATFORM_HEADER = exports.OPERATION_ID_HEADER = exports.ROUTER_CACHE_HEADER = exports.REQUEST_ID_HEADER = exports.CREDENTIAL_HEADER = exports.ACCOUNT_HEADER = exports.ETAG_HEADER = exports.META_HEADER_BUCKET = exports.META_HEADER = exports.BINDING_HEADER = exports.TENANT_HEADER = exports.FORWARDED_HOST_HEADER = exports.LOCALE_HEADER = exports.PRODUCT_HEADER = exports.SESSION_HEADER = exports.SEGMENT_HEADER = exports.CACHE_CONTROL_HEADER = exports.AttributeKeys = exports.HeaderKeys = exports.PID = exports.IS_IO = exports.DEFAULT_WORKSPACE = exports.NODE_VTEX_API_VERSION = void 0;
+exports.DIAGNOSTICS_TELEMETRY_ENABLED = exports.DK_APP_ID = exports.OTEL_EXPORTER_OTLP_ENDPOINT = exports.METRIC_CLIENT_INIT_TIMEOUT_MS = exports.LOG_CLIENT_INIT_TIMEOUT_MS = exports.cancellableMethods = void 0;
 const app_1 = require("./utils/app");
 const diagnostics_semconv_1 = require("@vtex/diagnostics-semconv");
 // tslint:disable-next-line
@@ -55,6 +55,8 @@ exports.AttributeKeys = {
     VTEX_IO_WORKSPACE_TYPE: diagnostics_semconv_1.ATTR_VTEX_IO_WORKSPACE_TYPE,
     VTEX_IO_APP_ID: diagnostics_semconv_1.ATTR_VTEX_IO_APP_ID,
     VTEX_IO_APP_AUTHOR_TYPE: diagnostics_semconv_1.ATTR_VTEX_IO_APP_AUTHOR_TYPE,
+    VTEX_IO_CLUSTER_ID: diagnostics_semconv_1.ATTR_VTEX_IO_CLUSTER_ID,
+    VTEX_IO_CLUSTER_ROLE: diagnostics_semconv_1.ATTR_VTEX_IO_CLUSTER_ROLE,
 };
 /** @deprecated Use HeaderKeys.CACHE_CONTROL instead */
 exports.CACHE_CONTROL_HEADER = exports.HeaderKeys.CACHE_CONTROL;
@@ -123,6 +125,8 @@ exports.HTTP_SERVER_PORT = 5050;
 exports.MAX_WORKERS = 4;
 exports.LINKED = !!process.env.VTEX_APP_LINK;
 exports.REGION = process.env.VTEX_REGION;
+exports.CLUSTER_ID = process.env.VTEX_CLUSTER_ID;
+exports.CLUSTER_ROLE = process.env.VTEX_CLUSTER_ROLE;
 exports.PUBLIC_ENDPOINT = process.env.VTEX_PUBLIC_ENDPOINT || 'myvtex.com';
 exports.APP = {
     ID: process.env.VTEX_APP_ID,

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/lib/service/metrics/otelRequestMetricsMiddleware.js

@@ -4,6 +4,7 @@ exports.addOtelRequestMetricsMiddleware = void 0;
 const stream_1 = require("stream");
 const utils_1 = require("../../utils");
 const metrics_1 = require("./metrics");
+const requestHandlerLabel_1 = require("./requestHandlerLabel");
 const INSTRUMENTS_INITIALIZATION_TIMEOUT = 500;
 const addOtelRequestMetricsMiddleware = () => {
     let instruments;
@@ -31,7 +32,9 @@ const addOtelRequestMetricsMiddleware = () => {
         instruments.concurrentRequests.add(1);
         ctx.req.once('aborted', () => {
             if (instruments) {
-                instruments.abortedRequests.add(1, { [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: ctx.requestHandlerName });
+                instruments.abortedRequests.add(1, {
+                    [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName),
+                });
             }
         });
         let responseClosed = false;
@@ -43,14 +46,14 @@ const addOtelRequestMetricsMiddleware = () => {
             const responseLength = ctx.response.length;
             if (responseLength && instruments) {
                 instruments.responseSizes.record(responseLength, {
-                    [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: ctx.requestHandlerName,
+                    [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName),
                     [metrics_1.RequestsMetricLabels.STATUS_CODE]: ctx.response.status,
                     [metrics_1.RequestsMetricLabels.ACCOUNT_NAME]: ((_a = ctx.vtex) === null || _a === void 0 ? void 0 : _a.account) || 'unknown',
                 });
             }
             if (instruments) {
                 instruments.totalRequests.add(1, {
-                    [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: ctx.requestHandlerName,
+                    [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName),
                     [metrics_1.RequestsMetricLabels.STATUS_CODE]: ctx.response.status,
                     [metrics_1.RequestsMetricLabels.ACCOUNT_NAME]: ((_b = ctx.vtex) === null || _b === void 0 ? void 0 : _b.account) || 'unknown',
                 });
@@ -59,7 +62,7 @@ const addOtelRequestMetricsMiddleware = () => {
                 var _a;
                 if (instruments) {
                     instruments.requestTimings.record((0, utils_1.hrToMillisFloat)(process.hrtime(start)), {
-                        [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: ctx.requestHandlerName,
+                        [metrics_1.RequestsMetricLabels.REQUEST_HANDLER]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName),
                         [metrics_1.RequestsMetricLabels.STATUS_CODE]: ctx.response.status,
                         [metrics_1.RequestsMetricLabels.ACCOUNT_NAME]: ((_a = ctx.vtex) === null || _a === void 0 ? void 0 : _a.account) || 'unknown',
                     });

package/lib/service/metrics/requestHandlerLabel.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Label value reported for requests that never reached a named handler: unmatched
+ * paths (Koa answers its default 404), requests rejected before the route pipeline
+ * (replica-level rate limiter, errors in compress/recorder), and handlers that
+ * don't set `ctx.requestHandlerName`.
+ *
+ * The value must be a non-empty string. `ctx.requestHandlerName` is `undefined`
+ * for those requests, and Node's cluster IPC serializes each worker's registry as
+ * JSON, which drops properties whose value is `undefined`. The sample then reaches
+ * the aggregated `/metrics` with the `handler` label missing altogether, which
+ * Prometheus reads as `handler=""` — a distinct, unnamed series that shows up as
+ * an extra "Value" line in dashboards.
+ *
+ * `'undefined'` is deliberate rather than a nicer word: prom-client's local
+ * exposition already rendered `handler: undefined` as `handler="undefined"` before
+ * the cluster aggregation was introduced, so keeping that value makes the
+ * aggregated output match the historical series identity and keeps existing
+ * dashboards, filters and alerts (e.g. `handler!~"builtin:.*|undefined"`) working.
+ */
+export declare const UNNAMED_REQUEST_HANDLER = "undefined";
+/**
+ * Resolves the `handler` label value for a request, falling back to
+ * {@link UNNAMED_REQUEST_HANDLER} when the pipeline never named the handler.
+ * Empty strings fall back too, so the label is never emitted empty.
+ */
+export declare const requestHandlerLabel: (requestHandlerName?: string) => string;

package/lib/service/metrics/requestHandlerLabel.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestHandlerLabel = exports.UNNAMED_REQUEST_HANDLER = void 0;
+/**
+ * Label value reported for requests that never reached a named handler: unmatched
+ * paths (Koa answers its default 404), requests rejected before the route pipeline
+ * (replica-level rate limiter, errors in compress/recorder), and handlers that
+ * don't set `ctx.requestHandlerName`.
+ *
+ * The value must be a non-empty string. `ctx.requestHandlerName` is `undefined`
+ * for those requests, and Node's cluster IPC serializes each worker's registry as
+ * JSON, which drops properties whose value is `undefined`. The sample then reaches
+ * the aggregated `/metrics` with the `handler` label missing altogether, which
+ * Prometheus reads as `handler=""` — a distinct, unnamed series that shows up as
+ * an extra "Value" line in dashboards.
+ *
+ * `'undefined'` is deliberate rather than a nicer word: prom-client's local
+ * exposition already rendered `handler: undefined` as `handler="undefined"` before
+ * the cluster aggregation was introduced, so keeping that value makes the
+ * aggregated output match the historical series identity and keeps existing
+ * dashboards, filters and alerts (e.g. `handler!~"builtin:.*|undefined"`) working.
+ */
+exports.UNNAMED_REQUEST_HANDLER = 'undefined';
+/**
+ * Resolves the `handler` label value for a request, falling back to
+ * {@link UNNAMED_REQUEST_HANDLER} when the pipeline never named the handler.
+ * Empty strings fall back too, so the label is never emitted empty.
+ */
+const requestHandlerLabel = (requestHandlerName) => requestHandlerName || exports.UNNAMED_REQUEST_HANDLER;
+exports.requestHandlerLabel = requestHandlerLabel;

package/lib/service/metrics/requestMetricsMiddleware.js

@@ -4,6 +4,7 @@ exports.addRequestMetricsMiddleware = void 0;
 const stream_1 = require("stream");
 const utils_1 = require("../../utils");
 const instruments_1 = require("../tracing/metrics/instruments");
+const requestHandlerLabel_1 = require("./requestHandlerLabel");
 const addRequestMetricsMiddleware = () => {
     const concurrentRequests = (0, instruments_1.createConcurrentRequestsInstrument)();
     const requestTimings = (0, instruments_1.createRequestsTimingsInstrument)();
@@ -13,7 +14,7 @@ const addRequestMetricsMiddleware = () => {
     return async function addRequestMetrics(ctx, next) {
         const start = process.hrtime();
         concurrentRequests.inc(1);
-        ctx.req.once('aborted', () => abortedRequests.inc({ ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: ctx.requestHandlerName }, 1));
+        ctx.req.once('aborted', () => abortedRequests.inc({ ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName) }, 1));
         let responseClosed = false;
         ctx.res.once('close', () => (responseClosed = true));
         try {
@@ -22,15 +23,15 @@ const addRequestMetricsMiddleware = () => {
         finally {
             const responseLength = ctx.response.length;
             if (responseLength) {
-                responseSizes.observe({ ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: ctx.requestHandlerName }, responseLength);
+                responseSizes.observe({ ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName) }, responseLength);
             }
             totalRequests.inc({
-                ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: ctx.requestHandlerName,
+                ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName),
                 ["status_code" /* RequestsMetricLabels.STATUS_CODE */]: ctx.response.status,
             }, 1);
             const onResFinished = () => {
                 requestTimings.observe({
-                    ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: ctx.requestHandlerName,
+                    ["handler" /* RequestsMetricLabels.REQUEST_HANDLER */]: (0, requestHandlerLabel_1.requestHandlerLabel)(ctx.requestHandlerName),
                 }, (0, utils_1.hrToMillisFloat)(process.hrtime(start)));
                 concurrentRequests.dec(1);
             };

package/lib/service/telemetry/client.js

@@ -5,6 +5,7 @@ const instrumentation_koa_1 = require("@opentelemetry/instrumentation-koa");
 const diagnostics_nodejs_1 = require("@vtex/diagnostics-nodejs");
 const constants_1 = require("../../constants");
 const hostMetrics_1 = require("../metrics/instruments/hostMetrics");
+const resourceAttributes_1 = require("./resourceAttributes");
 const APPLICATION_ID = constants_1.APP.ID || 'vtex-io-app';
 class TelemetryClientSingleton {
     static getInstance() {
@@ -58,6 +59,7 @@ class TelemetryClientSingleton {
                     'version': constants_1.APP.VERSION || '',
                     [constants_1.AttributeKeys.VTEX_IO_WORKSPACE_NAME]: constants_1.WORKSPACE,
                     [constants_1.AttributeKeys.VTEX_IO_WORKSPACE_TYPE]: constants_1.PRODUCTION ? 'production' : 'development',
+                    ...(0, resourceAttributes_1.getClusterResourceAttributes)(constants_1.CLUSTER_ID, constants_1.CLUSTER_ROLE),
                 },
                 // Use built-in no-op functionality when telemetry is disabled
                 noop: !constants_1.DIAGNOSTICS_TELEMETRY_ENABLED,

package/lib/service/telemetry/resourceAttributes.d.ts

@@ -0,0 +1 @@
+export declare const getClusterResourceAttributes: (clusterId?: string, clusterRole?: string) => Record<string, string>;

package/lib/service/telemetry/resourceAttributes.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClusterResourceAttributes = void 0;
+const constants_1 = require("../../constants");
+const normalizeAttribute = (value) => {
+    const normalized = value === null || value === void 0 ? void 0 : value.trim();
+    return normalized || undefined;
+};
+const getClusterResourceAttributes = (clusterId, clusterRole) => {
+    const attributes = {};
+    const normalizedClusterId = normalizeAttribute(clusterId);
+    const normalizedClusterRole = normalizeAttribute(clusterRole);
+    if (normalizedClusterId) {
+        attributes[constants_1.AttributeKeys.VTEX_IO_CLUSTER_ID] = normalizedClusterId;
+    }
+    if (normalizedClusterRole) {
+        attributes[constants_1.AttributeKeys.VTEX_IO_CLUSTER_ROLE] = normalizedClusterRole;
+    }
+    return attributes;
+};
+exports.getClusterResourceAttributes = getClusterResourceAttributes;

package/lib/service/worker/runtime/statusTrack.js

@@ -15,7 +15,10 @@ const isStatusTrackBroadcast = (message) => message === BROADCAST_STATUS_TRACK;
 exports.isStatusTrackBroadcast = isStatusTrackBroadcast;
 const statusTrackHandler = async (ctx) => {
     var _a, _b, _c;
-    (_b = (_a = ctx.tracing) === null || _a === void 0 ? void 0 : _a.currentSpan) === null || _b === void 0 ? void 0 : _b.setOperationName('builtin:status-track');
+    // Parity with the other builtin handlers: name the request so its samples don't
+    // land in the catch-all `handler="undefined"` bucket.
+    ctx.requestHandlerName = 'builtin:status-track';
+    (_b = (_a = ctx.tracing) === null || _a === void 0 ? void 0 : _a.currentSpan) === null || _b === void 0 ? void 0 : _b.setOperationName(ctx.requestHandlerName);
     if (!constants_1.LINKED) {
         (_c = process.send) === null || _c === void 0 ? void 0 : _c.call(process, BROADCAST_STATUS_TRACK);
     }

package/package.json

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