@vtex/api 7.4.2-beta.1 → 7.5.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/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/service/master.d.ts

@@ -1,2 +1,4 @@
+import { Worker } from 'cluster';
 import { ServiceJSON } from './worker/runtime/typings';
+export declare const onMessage: (worker: Worker, message: any) => void;
 export declare const startMaster: (service: ServiceJSON) => void;

package/lib/service/master.js

@@ -3,11 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startMaster = void 0;
+exports.startMaster = exports.onMessage = void 0;
 const cluster_1 = __importDefault(require("cluster"));
 const os_1 = require("os");
 const constants_1 = require("../constants");
 const logger_1 = require("./logger");
+const clusterMetricsAggregator_1 = require("./metrics/clusterMetricsAggregator");
 const listeners_1 = require("./worker/listeners");
 const statusTrack_1 = require("./worker/runtime/statusTrack");
 let handledSignal;
@@ -19,7 +20,12 @@ const onMessage = (worker, message) => {
         (0, statusTrack_1.trackStatus)();
         (0, statusTrack_1.broadcastStatusTrack)();
     }
-    else {
+    else if ((0, clusterMetricsAggregator_1.isAggMetricsRequest)(message)) {
+        (0, clusterMetricsAggregator_1.handleWorkerMetricsRequest)(worker, message);
+    }
+    else if (!(0, clusterMetricsAggregator_1.isPromClientMessage)(message)) {
+        // prom-client's own cluster messages are handled by its cluster listener;
+        // anything else that reaches here is genuinely unexpected.
         listeners_1.logger.warn({
             content: message,
             message: 'Worker sent message',
@@ -27,6 +33,7 @@ const onMessage = (worker, message) => {
         });
     }
 };
+exports.onMessage = onMessage;
 const onExit = (worker, code, signal) => {
     if (!constants_1.LINKED && worker.exitedAfterDisconnect === false) {
         listeners_1.logger.error({
@@ -70,6 +77,11 @@ const startMaster = (service) => {
     if (service.deterministicVary) {
         process.env.DETERMINISTIC_VARY = 'true';
     }
+    // Set up the master-side Prometheus aggregator so workers can request a
+    // merged, monotonic /metrics view across the whole cluster over IPC.
+    if (numWorkers > 1) {
+        (0, clusterMetricsAggregator_1.initMasterAggregatorRegistry)();
+    }
     // Setup dubugger
     if (constants_1.LINKED) {
         cluster_1.default.setupMaster({ inspectPort: constants_1.INSPECT_DEBUGGER_PORT });
@@ -82,7 +94,7 @@ const startMaster = (service) => {
     }
     cluster_1.default.on('online', onOnline);
     cluster_1.default.on('exit', onExit);
-    cluster_1.default.on('message', onMessage);
+    cluster_1.default.on('message', exports.onMessage);
     process.on('SIGINT', handleSignal(SIGINT_TIMEOUT_S));
     process.on('SIGTERM', handleSignal(shutdownTimeout));
 };

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

@@ -0,0 +1,72 @@
+import { Worker } from 'cluster';
+import { AggregatorRegistry } from 'prom-client';
+/**
+ * Cluster-wide Prometheus metrics aggregation.
+ *
+ * In multi-worker mode each cluster worker keeps its own prom-client default
+ * registry. Serving `/metrics` from a single (round-robin selected) worker
+ * therefore exposes only that worker's local counters, which makes Prometheus
+ * treat the per-scrape braid of independent counters as counter resets and
+ * inflates `rate()`/`increase()` by orders of magnitude.
+ *
+ * This module uses prom-client's `AggregatorRegistry` cluster IPC protocol so
+ * that the worker answering a scrape asks the master for a merged, monotonic
+ * view built from every worker's registry in one pass (no double-counting of
+ * the answering worker).
+ */
+/** Tagged IPC message: worker -> master, "please build the cluster aggregate". */
+export declare const AGG_METRICS_REQ = "vtex-api:aggMetricsReq";
+/** Tagged IPC message: master -> worker, carries the aggregate (or an error). */
+export declare const AGG_METRICS_RES = "vtex-api:aggMetricsRes";
+export interface AggMetricsReqMessage {
+    type: typeof AGG_METRICS_REQ;
+    id: number;
+}
+export interface AggMetricsResMessage {
+    type: typeof AGG_METRICS_RES;
+    id: number;
+    body?: string;
+    error?: string;
+}
+export declare const isAggMetricsRequest: (message: any) => message is AggMetricsReqMessage;
+export declare const isAggMetricsResponse: (message: any) => message is AggMetricsResMessage;
+/**
+ * prom-client's cluster protocol emits its own tagged IPC messages
+ * (`prom-client:getMetricsReq` / `prom-client:getMetricsRes`). They are handled
+ * by prom-client's own cluster listeners, so our `onMessage` handlers must
+ * ignore them instead of warning about "unknown" messages.
+ */
+export declare const isPromClientMessage: (message: any) => boolean;
+/**
+ * Constructs the master-side `AggregatorRegistry` (idempotent). Its constructor
+ * installs prom-client's master `cluster.on('message')` collector, which is
+ * what makes `clusterMetrics()` work. Must be called in the master before any
+ * worker can answer a scrape.
+ */
+export declare const initMasterAggregatorRegistry: () => AggregatorRegistry;
+/**
+ * Handles an `AGG_METRICS_REQ` from a worker: builds the cluster aggregate and
+ * replies to that worker only. prom-client fans the request out to *all*
+ * connected workers (including the requester), so the requester is one of the N
+ * merged sources and is never double-counted.
+ */
+export declare const handleWorkerMetricsRequest: (worker: Worker, message: AggMetricsReqMessage) => Promise<void>;
+/**
+ * Constructs the worker-side `AggregatorRegistry` (idempotent). Its constructor
+ * installs prom-client's worker `process.on('message')` responder that answers
+ * the master's `getMetricsReq` with this worker's registry JSON.
+ */
+export declare const ensureWorkerAggregatorRegistry: () => AggregatorRegistry;
+/**
+ * Requests the cluster aggregate from the master over IPC and resolves with the
+ * merged exposition string. On timeout or any error it falls back to this
+ * worker's local `register.metrics()` so `/metrics` always answers promptly.
+ */
+export declare const requestAggregatedMetrics: () => Promise<string>;
+/**
+ * Resolves the pending `requestAggregatedMetrics` promise correlated by id when
+ * the master replies. On error it falls back to the local registry.
+ */
+export declare const handleMasterMetricsResponse: (message: AggMetricsResMessage) => void;
+/** Test-only helper to reset module state between test cases. */
+export declare const __resetForTests: () => void;

package/lib/service/metrics/clusterMetricsAggregator.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__resetForTests = exports.handleMasterMetricsResponse = exports.requestAggregatedMetrics = exports.ensureWorkerAggregatorRegistry = exports.handleWorkerMetricsRequest = exports.initMasterAggregatorRegistry = exports.isPromClientMessage = exports.isAggMetricsResponse = exports.isAggMetricsRequest = exports.AGG_METRICS_RES = exports.AGG_METRICS_REQ = void 0;
+const prom_client_1 = require("prom-client");
+const listeners_1 = require("../worker/listeners");
+/**
+ * Cluster-wide Prometheus metrics aggregation.
+ *
+ * In multi-worker mode each cluster worker keeps its own prom-client default
+ * registry. Serving `/metrics` from a single (round-robin selected) worker
+ * therefore exposes only that worker's local counters, which makes Prometheus
+ * treat the per-scrape braid of independent counters as counter resets and
+ * inflates `rate()`/`increase()` by orders of magnitude.
+ *
+ * This module uses prom-client's `AggregatorRegistry` cluster IPC protocol so
+ * that the worker answering a scrape asks the master for a merged, monotonic
+ * view built from every worker's registry in one pass (no double-counting of
+ * the answering worker).
+ */
+/** Tagged IPC message: worker -> master, "please build the cluster aggregate". */
+exports.AGG_METRICS_REQ = 'vtex-api:aggMetricsReq';
+/** Tagged IPC message: master -> worker, carries the aggregate (or an error). */
+exports.AGG_METRICS_RES = 'vtex-api:aggMetricsRes';
+/**
+ * Upper bound for a worker waiting on the master aggregate. prom-client's own
+ * `clusterMetrics()` has a 5s timeout collecting worker registries; we guard
+ * slightly above that and fall back to the local registry on expiry so that
+ * `/metrics` never hangs or returns empty.
+ */
+const AGG_METRICS_TIMEOUT_MS = 6000;
+const isAggMetricsRequest = (message) => (message === null || message === void 0 ? void 0 : message.type) === exports.AGG_METRICS_REQ && typeof (message === null || message === void 0 ? void 0 : message.id) === 'number';
+exports.isAggMetricsRequest = isAggMetricsRequest;
+const isAggMetricsResponse = (message) => (message === null || message === void 0 ? void 0 : message.type) === exports.AGG_METRICS_RES && typeof (message === null || message === void 0 ? void 0 : message.id) === 'number';
+exports.isAggMetricsResponse = isAggMetricsResponse;
+/**
+ * prom-client's cluster protocol emits its own tagged IPC messages
+ * (`prom-client:getMetricsReq` / `prom-client:getMetricsRes`). They are handled
+ * by prom-client's own cluster listeners, so our `onMessage` handlers must
+ * ignore them instead of warning about "unknown" messages.
+ */
+const isPromClientMessage = (message) => typeof (message === null || message === void 0 ? void 0 : message.type) === 'string' && message.type.startsWith('prom-client:');
+exports.isPromClientMessage = isPromClientMessage;
+// ---------------------------------------------------------------------------
+// Master side
+// ---------------------------------------------------------------------------
+let masterAggregatorRegistry;
+/**
+ * Constructs the master-side `AggregatorRegistry` (idempotent). Its constructor
+ * installs prom-client's master `cluster.on('message')` collector, which is
+ * what makes `clusterMetrics()` work. Must be called in the master before any
+ * worker can answer a scrape.
+ */
+const initMasterAggregatorRegistry = () => {
+    if (!masterAggregatorRegistry) {
+        masterAggregatorRegistry = new prom_client_1.AggregatorRegistry();
+    }
+    return masterAggregatorRegistry;
+};
+exports.initMasterAggregatorRegistry = initMasterAggregatorRegistry;
+/**
+ * Handles an `AGG_METRICS_REQ` from a worker: builds the cluster aggregate and
+ * replies to that worker only. prom-client fans the request out to *all*
+ * connected workers (including the requester), so the requester is one of the N
+ * merged sources and is never double-counted.
+ */
+const handleWorkerMetricsRequest = async (worker, message) => {
+    var _a, _b;
+    const aggregator = (0, exports.initMasterAggregatorRegistry)();
+    let response;
+    try {
+        const body = await aggregator.clusterMetrics();
+        response = { type: exports.AGG_METRICS_RES, id: message.id, body };
+    }
+    catch (err) {
+        response = { type: exports.AGG_METRICS_RES, id: message.id, error: (_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : String(err) };
+    }
+    // `worker.send` can throw (e.g. the worker disconnected between the request
+    // and the reply). This handler is invoked without `await` from the master's
+    // message listener, so a thrown send would surface as an unhandled rejection
+    // in the master process. Swallow and log it instead.
+    try {
+        worker.send(response);
+    }
+    catch (err) {
+        listeners_1.logger.warn({
+            content: (_b = err === null || err === void 0 ? void 0 : err.message) !== null && _b !== void 0 ? _b : String(err),
+            message: 'Failed to send aggregated cluster metrics to worker',
+            pid: process.pid,
+            workerId: worker.id,
+        });
+    }
+};
+exports.handleWorkerMetricsRequest = handleWorkerMetricsRequest;
+// ---------------------------------------------------------------------------
+// Worker side
+// ---------------------------------------------------------------------------
+let workerAggregatorRegistry;
+const pendingRequests = new Map();
+let requestCounter = 0;
+/**
+ * Constructs the worker-side `AggregatorRegistry` (idempotent). Its constructor
+ * installs prom-client's worker `process.on('message')` responder that answers
+ * the master's `getMetricsReq` with this worker's registry JSON.
+ */
+const ensureWorkerAggregatorRegistry = () => {
+    if (!workerAggregatorRegistry) {
+        workerAggregatorRegistry = new prom_client_1.AggregatorRegistry();
+    }
+    return workerAggregatorRegistry;
+};
+exports.ensureWorkerAggregatorRegistry = ensureWorkerAggregatorRegistry;
+/**
+ * Requests the cluster aggregate from the master over IPC and resolves with the
+ * merged exposition string. On timeout or any error it falls back to this
+ * worker's local `register.metrics()` so `/metrics` always answers promptly.
+ */
+const requestAggregatedMetrics = async () => {
+    if (typeof process.send !== 'function') {
+        return prom_client_1.register.metrics();
+    }
+    const id = requestCounter++;
+    return new Promise((resolve) => {
+        var _a;
+        const timer = setTimeout(() => {
+            pendingRequests.delete(id);
+            listeners_1.logger.warn({
+                message: 'Timed out waiting for aggregated cluster metrics; falling back to local registry',
+                pid: process.pid,
+            });
+            prom_client_1.register.metrics().then(resolve).catch(() => resolve(''));
+        }, AGG_METRICS_TIMEOUT_MS);
+        pendingRequests.set(id, { resolve, timer });
+        try {
+            process.send({ type: exports.AGG_METRICS_REQ, id });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            pendingRequests.delete(id);
+            listeners_1.logger.warn({
+                content: (_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : String(err),
+                message: 'Failed to request aggregated cluster metrics; falling back to local registry',
+                pid: process.pid,
+            });
+            prom_client_1.register.metrics().then(resolve).catch(() => resolve(''));
+        }
+    });
+};
+exports.requestAggregatedMetrics = requestAggregatedMetrics;
+/**
+ * Resolves the pending `requestAggregatedMetrics` promise correlated by id when
+ * the master replies. On error it falls back to the local registry.
+ */
+const handleMasterMetricsResponse = (message) => {
+    const pending = pendingRequests.get(message.id);
+    if (!pending) {
+        return;
+    }
+    pendingRequests.delete(message.id);
+    clearTimeout(pending.timer);
+    if (message.error != null || message.body == null) {
+        listeners_1.logger.warn({
+            content: message.error,
+            message: 'Master failed to aggregate cluster metrics; falling back to local registry',
+            pid: process.pid,
+        });
+        prom_client_1.register.metrics().then(pending.resolve).catch(() => pending.resolve(''));
+        return;
+    }
+    pending.resolve(message.body);
+};
+exports.handleMasterMetricsResponse = handleMasterMetricsResponse;
+/** Test-only helper to reset module state between test cases. */
+const __resetForTests = () => {
+    masterAggregatorRegistry = undefined;
+    workerAggregatorRegistry = undefined;
+    pendingRequests.forEach((p) => clearTimeout(p.timer));
+    pendingRequests.clear();
+    requestCounter = 0;
+};
+exports.__resetForTests = __resetForTests;

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

@@ -1,3 +1,4 @@
 import Koa from 'koa';
 import { ServiceJSON } from './runtime/typings';
+export declare const onMessage: (service: ServiceJSON) => (message: any) => void;
 export declare const startWorker: (serviceJSON: ServiceJSON) => Koa<Koa.DefaultState, Koa.DefaultContext>;

package/lib/service/worker/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startWorker = void 0;
+exports.startWorker = exports.onMessage = void 0;
 const diagnostics_nodejs_1 = require("@vtex/diagnostics-nodejs");
 const http_1 = require("http");
 const koa_1 = __importDefault(require("koa"));
@@ -14,6 +14,7 @@ const constants_1 = require("../../constants");
 const loaders_1 = require("../loaders");
 const console_1 = require("../logger/console");
 const loggerTypes_1 = require("../logger/loggerTypes");
+const clusterMetricsAggregator_1 = require("../metrics/clusterMetricsAggregator");
 const otelRequestMetricsMiddleware_1 = require("../metrics/otelRequestMetricsMiddleware");
 const requestMetricsMiddleware_1 = require("../metrics/requestMetricsMiddleware");
 const TracerSingleton_1 = require("../tracing/TracerSingleton");
@@ -55,7 +56,12 @@ const onMessage = (service) => (message) => {
     else if ((0, statusTrack_1.isStatusTrack)(message)) {
         (0, statusTrack_1.trackStatus)();
     }
-    else {
+    else if ((0, clusterMetricsAggregator_1.isAggMetricsResponse)(message)) {
+        (0, clusterMetricsAggregator_1.handleMasterMetricsResponse)(message);
+    }
+    else if (!(0, clusterMetricsAggregator_1.isPromClientMessage)(message)) {
+        // prom-client's own cluster messages are handled by its worker listener;
+        // anything else that reaches here is genuinely unexpected.
         listeners_1.logger.warn({
             content: message,
             message: 'Master sent message',
@@ -63,6 +69,7 @@ const onMessage = (service) => (message) => {
         });
     }
 };
+exports.onMessage = onMessage;
 const createAppHttpHandlers = ({ config: { routes, clients } }, serviceJSON, globalLimiter) => {
     if (routes && clients) {
         return Object.keys(routes).reduce((acc, routeId) => {
@@ -154,12 +161,17 @@ const startWorker = (serviceJSON) => {
     var _a, _b;
     (0, listeners_1.addProcessListeners)();
     const tracer = TracerSingleton_1.TracerSingleton.getTracer();
+    // In multi-worker mode install prom-client's worker-side cluster responder so
+    // the master can collect this worker's registry for the aggregated /metrics.
+    if (serviceJSON.workers > 1) {
+        (0, clusterMetricsAggregator_1.ensureWorkerAggregatorRegistry)();
+    }
     const app = new koa_1.default();
     app.proxy = true;
     app
         .use(error_1.error)
         .use(diagnostics_nodejs_1.Instrumentation.Middlewares.ContextMiddlewares.Koa.ContextPropagationMiddleware())
-        .use((0, middlewares_1.prometheusLoggerMiddleware)())
+        .use((0, middlewares_1.prometheusLoggerMiddleware)(serviceJSON.workers))
         .use((0, tracingMiddlewares_1.addTracingMiddleware)(tracer))
         .use((0, requestMetricsMiddleware_1.addRequestMetricsMiddleware)())
         .use((0, otelRequestMetricsMiddleware_1.addOtelRequestMetricsMiddleware)())
@@ -182,9 +194,8 @@ const startWorker = (serviceJSON) => {
         appGraphQLHandlers,
         runtimeHttpHandlers,
     ]
-        .filter(x => x != null)
-        // TODO: Fix ramda typings. Apparently there was an update that broke things
-        .reduce(ramda_1.mergeDeepRight);
+        .filter((x) => x != null)
+        .reduce((acc, handler) => (0, ramda_1.mergeDeepRight)(acc, handler), {});
     if (httpHandlers === null || httpHandlers === void 0 ? void 0 : httpHandlers.pub) {
         const publicHandlersRouter = (0, router_2.routerFromPublicHttpHandlers)(httpHandlers.pub);
         app.use(publicHandlersRouter);
@@ -193,7 +204,7 @@ const startWorker = (serviceJSON) => {
         const privateHandlersRouter = routerFromPrivateHttpHandlers(httpHandlers.pvt);
         app.use(privateHandlersRouter.routes());
     }
-    process.on('message', onMessage(serviceJSON));
+    process.on('message', (0, exports.onMessage)(serviceJSON));
     return app;
 };
 exports.startWorker = startWorker;

package/lib/service/worker/runtime/builtIn/middlewares.d.ts

@@ -1,4 +1,4 @@
 import { ServiceContext } from '../typings';
 export declare function recorderMiddleware(ctx: ServiceContext, next: () => Promise<void>): Promise<void>;
 export declare const addMetricsLoggerMiddleware: () => (ctx: ServiceContext, next: () => Promise<void>) => Promise<void>;
-export declare const prometheusLoggerMiddleware: () => (ctx: ServiceContext, next: () => Promise<void>) => Promise<void>;
+export declare const prometheusLoggerMiddleware: (workers?: number) => (ctx: ServiceContext, next: () => Promise<void>) => Promise<void>;

package/lib/service/worker/runtime/builtIn/middlewares.js

@@ -4,6 +4,7 @@ exports.prometheusLoggerMiddleware = exports.addMetricsLoggerMiddleware = export
 const prom_client_1 = require("prom-client");
 const constants_1 = require("../../../../constants");
 const metricsLogger_1 = require("../../../logger/metricsLogger");
+const clusterMetricsAggregator_1 = require("../../../metrics/clusterMetricsAggregator");
 const EventLoopLagMeasurer_1 = require("../../../tracing/metrics/measurers/EventLoopLagMeasurer");
 const recorder_1 = require("../utils/recorder");
 async function recorderMiddleware(ctx, next) {
@@ -22,10 +23,14 @@ const addMetricsLoggerMiddleware = () => {
     };
 };
 exports.addMetricsLoggerMiddleware = addMetricsLoggerMiddleware;
-const prometheusLoggerMiddleware = () => {
+const prometheusLoggerMiddleware = (workers = 1) => {
     (0, prom_client_1.collectDefaultMetrics)();
     const eventLoopLagMeasurer = new EventLoopLagMeasurer_1.EventLoopLagMeasurer();
     eventLoopLagMeasurer.start();
+    // In multi-worker mode each worker holds only its own registry, so /metrics
+    // must serve the cluster-wide aggregate requested from the master over IPC.
+    // In single-worker mode (LINKED / workers:1) the local registry is complete.
+    const isMultiWorker = workers > 1;
     return async (ctx, next) => {
         if (ctx.request.path !== '/metrics') {
             return next();
@@ -36,7 +41,7 @@ const prometheusLoggerMiddleware = () => {
         }
         await eventLoopLagMeasurer.updateInstrumentsAndReset();
         ctx.set('Content-Type', prom_client_1.register.contentType);
-        ctx.body = await prom_client_1.register.metrics();
+        ctx.body = isMultiWorker ? await (0, clusterMetricsAggregator_1.requestAggregatedMetrics)() : await prom_client_1.register.metrics();
         ctx.status = 200;
     };
 };

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-beta.1",
+  "version": "7.5.0",
   "description": "VTEX I/O API client",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -54,7 +54,7 @@
     "@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-semconv": "5.5.2",
     "@vtex/node-error-report": "^0.0.3",
     "@wry/equality": "^0.1.9",
     "agentkeepalive": "^4.0.2",