@vtex/api 7.4.2 → 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/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.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",