@vtex/api 6.53.0-beta.0 → 6.53.0-beta.1

package/CHANGELOG.md

@@ -5,14 +5,17 @@ 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).
 
-## [6.53.0-beta.0]
+## [6.53.0-beta.1]
 ### Added
 - Diagnostics metrics observability, backported from the `master` (7.x) line: `DiagnosticsMetrics`
   (`recordLatency`, `incrementCounter`, `setGauge`, `runWithBaseAttributes`), a split
   traces/metrics/logs telemetry client (`@vtex/diagnostics-nodejs@0.1.8-io`,
   `@vtex/diagnostics-semconv`), cluster resource attributes, and automatic Koa + host-metrics
-  instrumentation. Disabled by default; opt in per app with
-  `VTEX_DIAGNOSTICS_TELEMETRY_ENABLED=true`.
+  instrumentation. Metrics are wired into the request pipeline itself, not just exposed as a
+  library API: HTTP handler latency/counters, request closed/aborted/total counters, outbound
+  HTTP client metrics, HTTP agent socket gauges, and the `@metric` GraphQL directive all emit
+  through `DiagnosticsMetrics` at the same points `master` does. Disabled by default; opt in
+  per app with `VTEX_DIAGNOSTICS_TELEMETRY_ENABLED=true`.
 
 ## [6.52.0]
 ### Added

package/lib/HttpClient/middlewares/metrics.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.metricsMiddleware = void 0;
+const constants_1 = require("../../constants");
 const RequestCancelledError_1 = require("../../errors/RequestCancelledError");
 const requestStats_1 = require("../../service/worker/runtime/http/middlewares/requestStats");
 const utils_1 = require("../../utils");
 const retry_1 = require("../../utils/retry");
 const status_1 = require("../../utils/status");
+const DEFAULT_ACCOUNT = 'unknown';
 const metricsMiddleware = ({ metrics, serverTiming, name }) => {
     const serverTimingStart = process.hrtime();
     const serverTimingLabel = (0, utils_1.shrinkTimings)((0, utils_1.formatTimingName)({
@@ -14,6 +16,7 @@ const metricsMiddleware = ({ metrics, serverTiming, name }) => {
         target: name || 'unknown',
     }));
     return async (ctx, next) => {
+        var _a, _b;
         const start = process.hrtime();
         let status = 'unknown';
         let errorCode;
@@ -57,29 +60,73 @@ const metricsMiddleware = ({ metrics, serverTiming, name }) => {
                 const label = `http-client-${ctx.config.metric}`;
                 const extensions = {};
                 Object.assign(extensions, { [status]: 1 });
+                // Determine cache state for diagnostics metrics
+                let cacheState = 'none';
                 if (ctx.cacheHit) {
                     Object.assign(extensions, ctx.cacheHit, { [`${status}-hit`]: 1 });
+                    cacheState = 'hit';
                 }
                 else if (!ctx.inflightHit && !ctx.memoizedHit) {
                     // Lets us know how many calls passed through to origin
                     Object.assign(extensions, { [`${status}-miss`]: 1 });
+                    cacheState = 'miss';
                 }
                 if (ctx.inflightHit) {
                     Object.assign(extensions, { [`${status}-inflight`]: 1 });
+                    cacheState = 'inflight';
                 }
                 if (ctx.memoizedHit) {
                     Object.assign(extensions, { [`${status}-memoized`]: 1 });
+                    cacheState = 'memoized';
                 }
-                if (ctx.config.retryCount) {
-                    const retryCount = ctx.config.retryCount;
-                    if (retryCount > 0) {
-                        extensions[`retry-${status}-${retryCount}`] = 1;
-                    }
+                const retryCount = ctx.config.retryCount || 0;
+                if (retryCount > 0) {
+                    extensions[`retry-${status}-${retryCount}`] = 1;
                 }
                 const end = status === 'success' && !ctx.cacheHit && !ctx.inflightHit && !ctx.memoizedHit
                     ? process.hrtime(start)
                     : undefined;
+                // Legacy metrics (backward compatibility)
                 metrics.batch(label, end, extensions);
+                // New diagnostics metrics with stable names and attributes
+                if (global.diagnosticsMetrics) {
+                    const elapsed = process.hrtime(start);
+                    const rawStatusCode = ((_a = ctx.response) === null || _a === void 0 ? void 0 : _a.status) || errorStatus;
+                    // Extract account from request headers, fallback to default
+                    const account = ((_b = ctx.config.headers) === null || _b === void 0 ? void 0 : _b[constants_1.ACCOUNT_HEADER]) || DEFAULT_ACCOUNT;
+                    const baseAttributes = {
+                        [constants_1.AttributeKeys.VTEX_ACCOUNT_NAME]: account,
+                        component: 'http-client',
+                        client_metric: ctx.config.metric,
+                        status_code: rawStatusCode,
+                        status,
+                    };
+                    // Record latency histogram with all context
+                    global.diagnosticsMetrics.recordLatency(elapsed, {
+                        ...baseAttributes,
+                        cache_state: cacheState,
+                    });
+                    // Increment counters for different event types (replaces extensions behavior)
+                    // Main request counter with status as attribute
+                    global.diagnosticsMetrics.incrementCounter('http_client_requests_total', 1, baseAttributes);
+                    // Cache counter with cache_state as attribute (replaces extensions like 'success-hit', 'error-miss')
+                    if (cacheState !== 'none') {
+                        global.diagnosticsMetrics.incrementCounter('http_client_cache_total', 1, {
+                            ...baseAttributes,
+                            cache_state: cacheState,
+                        });
+                    }
+                    // Retry counter (replaces 'retry-{status}-{count}' extensions)
+                    if (retryCount > 0) {
+                        global.diagnosticsMetrics.incrementCounter('http_client_requests_retried_total', 1, {
+                            ...baseAttributes,
+                            retry_count: retryCount,
+                        });
+                    }
+                }
+                else {
+                    console.warn('DiagnosticsMetrics not available. HTTP client metrics not reported.');
+                }
                 if (ctx.config.verbose) {
                     console.log(`VERBOSE: ${name}.${ctx.config.label}`, {
                         ...extensions,

package/lib/HttpClient/middlewares/request/HttpAgentSingleton.d.ts

@@ -6,6 +6,11 @@ export declare class HttpAgentSingleton {
         pendingRequests: number;
         sockets: number;
     };
+    /**
+     * Update HTTP agent statistics as diagnostics metrics (gauges).
+     * This method should be called periodically to export current HTTP agent state.
+     */
+    static updateHttpAgentMetrics(): void;
     private static httpAgent;
     private static count;
 }

package/lib/HttpClient/middlewares/request/HttpAgentSingleton.js

@@ -19,6 +19,21 @@ class HttpAgentSingleton {
             sockets,
         };
     }
+    /**
+     * Update HTTP agent statistics as diagnostics metrics (gauges).
+     * This method should be called periodically to export current HTTP agent state.
+     */
+    static updateHttpAgentMetrics() {
+        if (!global.diagnosticsMetrics) {
+            console.warn('DiagnosticsMetrics not available. HTTP agent metrics not reported.');
+            return;
+        }
+        const stats = HttpAgentSingleton.httpAgentStats();
+        // Report HTTP agent stats as gauges (current state)
+        global.diagnosticsMetrics.setGauge('http_agent_sockets_current', stats.sockets, {});
+        global.diagnosticsMetrics.setGauge('http_agent_free_sockets_current', stats.freeSockets, {});
+        global.diagnosticsMetrics.setGauge('http_agent_pending_requests_current', stats.pendingRequests, {});
+    }
     static count(obj) {
         try {
             return Object.values(obj).reduce((acc, val) => acc += val.length, 0);

package/lib/service/index.d.ts

@@ -1,2 +1,10 @@
-export declare const startApp: () => void;
+import { DiagnosticsMetrics } from '../metrics/DiagnosticsMetrics';
+export declare const startApp: () => Promise<void>;
 export { appPath } from './loaders';
+declare global {
+    namespace NodeJS {
+        interface Global {
+            diagnosticsMetrics: DiagnosticsMetrics;
+        }
+    }
+}

package/lib/service/index.js

@@ -6,11 +6,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.appPath = exports.startApp = void 0;
 const cluster_1 = __importDefault(require("cluster"));
 const constants_1 = require("../constants");
+const DiagnosticsMetrics_1 = require("../metrics/DiagnosticsMetrics");
 const loaders_1 = require("./loaders");
 const logger_1 = require("./logger");
 const master_1 = require("./master");
+const telemetry_1 = require("./telemetry");
 const worker_1 = require("./worker");
-const startApp = () => {
+const startApp = async () => {
+    await (0, telemetry_1.initializeTelemetry)();
+    global.diagnosticsMetrics = new DiagnosticsMetrics_1.DiagnosticsMetrics();
     const serviceJSON = (0, loaders_1.getServiceJSON)();
     try {
         // if it is a master process then call setting up worker process

package/lib/service/worker/runtime/graphql/schema/schemaDirectives/Metric.js

@@ -21,11 +21,29 @@ class Metric extends graphql_tools_1.SchemaDirectiveVisitor {
                 result = error;
                 failedToResolve = true;
             }
-            ctx.graphql.status = failedToResolve ? 'error' : 'success';
+            const status = failedToResolve ? 'error' : 'success';
+            ctx.graphql.status = status;
             const payload = {
-                [ctx.graphql.status]: 1,
+                [status]: 1,
             };
+            // Legacy metrics (backward compatibility)
             metrics.batch(`graphql-metric-${name}`, failedToResolve ? undefined : ellapsed, payload);
+            // New diagnostics metrics with stable names and attributes
+            if (global.diagnosticsMetrics) {
+                const attributes = {
+                    [__1.AttributeKeys.VTEX_ACCOUNT_NAME]: ctx.vtex.account,
+                    component: 'graphql',
+                    field_name: name,
+                    status,
+                };
+                // Record latency histogram (record all requests, not just successful ones)
+                global.diagnosticsMetrics.recordLatency(ellapsed, attributes);
+                // Increment counter (status is an attribute, not in metric name)
+                global.diagnosticsMetrics.incrementCounter('graphql_field_requests_total', 1, attributes);
+            }
+            else {
+                console.warn('DiagnosticsMetrics not available. GraphQL field metrics not reported.');
+            }
             if (failedToResolve) {
                 throw result;
             }

package/lib/service/worker/runtime/http/middlewares/requestStats.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trackIncomingRequestStats = exports.incomingRequestStats = exports.cancelMessage = void 0;
+const constants_1 = require("../../../../../constants");
 exports.cancelMessage = 'Request cancelled';
 class IncomingRequestStats {
     constructor() {
@@ -22,20 +23,59 @@ class IncomingRequestStats {
     }
 }
 exports.incomingRequestStats = new IncomingRequestStats();
-const requestClosed = () => {
+const requestClosed = (ctx) => () => {
     exports.incomingRequestStats.closed++;
+    // Report to diagnostics metrics (cumulative counter)
+    const { status: statusCode, vtex: { account, route: { id, type } } } = ctx;
+    if (global.diagnosticsMetrics) {
+        global.diagnosticsMetrics.incrementCounter('http_server_requests_closed_total', 1, {
+            [constants_1.AttributeKeys.VTEX_ACCOUNT_NAME]: account,
+            route_id: id,
+            route_type: type,
+            status_code: statusCode,
+        });
+    }
+    else {
+        console.warn('DiagnosticsMetrics not available. Request closed metric not reported.');
+    }
 };
 const requestAborted = (ctx) => () => {
     exports.incomingRequestStats.aborted++;
+    // Report to diagnostics metrics (cumulative counter)
+    const { status: statusCode, vtex: { account, route: { id, type } } } = ctx;
+    if (global.diagnosticsMetrics) {
+        global.diagnosticsMetrics.incrementCounter('http_server_requests_aborted_total', 1, {
+            [constants_1.AttributeKeys.VTEX_ACCOUNT_NAME]: account,
+            route_id: id,
+            route_type: type,
+            status_code: statusCode,
+        });
+    }
+    else {
+        console.warn('DiagnosticsMetrics not available. Request aborted metric not reported.');
+    }
     if (ctx.vtex.cancellation && ctx.vtex.cancellation.cancelable) {
         ctx.vtex.cancellation.source.cancel(exports.cancelMessage);
         ctx.vtex.cancellation.cancelled = true;
     }
 };
 async function trackIncomingRequestStats(ctx, next) {
-    ctx.req.on('close', requestClosed);
+    ctx.req.on('close', requestClosed(ctx));
     ctx.req.on('aborted', requestAborted(ctx));
     exports.incomingRequestStats.total++;
+    // Report total requests to diagnostics metrics (cumulative counter)
+    const { status: statusCode, vtex: { account, route: { id, type } } } = ctx;
+    if (global.diagnosticsMetrics) {
+        global.diagnosticsMetrics.incrementCounter('http_server_requests_total', 1, {
+            [constants_1.AttributeKeys.VTEX_ACCOUNT_NAME]: account,
+            route_id: id,
+            route_type: type,
+            status_code: statusCode,
+        });
+    }
+    else {
+        console.warn('DiagnosticsMetrics not available. Request total metric not reported.');
+    }
     await next();
 }
 exports.trackIncomingRequestStats = trackIncomingRequestStats;

package/lib/service/worker/runtime/http/middlewares/timings.js

@@ -33,14 +33,54 @@ const logBillingInfo = ({ account, workspace, production, route: { id, type } },
     'workspace': workspace,
 });
 async function timings(ctx, next) {
-    // Errors will be caught by the next middleware so we don't have to catch.
-    await next();
-    const { status: statusCode, vtex: { route: { id } }, timings: { total }, vtex } = ctx;
-    const totalMillis = (0, time_1.hrToMillis)(total);
-    console.log(log(ctx, totalMillis));
-    console.log(logBillingInfo(vtex, totalMillis));
-    const status = (0, status_1.statusLabel)(statusCode);
-    // Only batch successful responses so metrics don't consider errors
-    metrics.batch(`http-handler-${id}`, status === 'success' ? total : undefined, { [status]: 1 });
+    const { vtex: { route: { id, type } }, vtex } = ctx;
+    // Set base attributes for all metrics recorded during this request.
+    // This includes metrics recorded by VTEX IO apps during handler execution.
+    // These attributes will be automatically merged with custom attributes.
+    const baseAttributes = {
+        [constants_1.AttributeKeys.VTEX_ACCOUNT_NAME]: vtex.account,
+        component: 'http-handler',
+        route_id: id,
+        route_type: type,
+    };
+    // Wrap the request handling with base attributes context.
+    // All metrics recorded during next() will automatically include these attributes.
+    const executeWithBaseAttributes = async () => {
+        // Errors will be caught by the next middleware so we don't have to catch.
+        await next();
+        const { status: statusCode, timings: { total } } = ctx;
+        const totalMillis = (0, time_1.hrToMillis)(total);
+        console.log(log(ctx, totalMillis));
+        console.log(logBillingInfo(vtex, totalMillis));
+        const status = (0, status_1.statusLabel)(statusCode);
+        // Legacy metrics (backward compatibility)
+        // Only batch successful responses so metrics don't consider errors
+        metrics.batch(`http-handler-${id}`, status === 'success' ? total : undefined, { [status]: 1 });
+        // New diagnostics metrics with stable names and attributes
+        // Note: base attributes (account, route_id, route_type) are automatically merged
+        // We only need to provide the response-specific attributes here
+        if (global.diagnosticsMetrics) {
+            const responseAttributes = {
+                status,
+                status_code: statusCode,
+            };
+            // Record latency histogram (record all requests, not just successful ones)
+            global.diagnosticsMetrics.recordLatency(total, responseAttributes);
+            // Increment counter (status is an attribute, not in metric name)
+            global.diagnosticsMetrics.incrementCounter('http_handler_requests_total', 1, responseAttributes);
+        }
+        else {
+            console.warn('DiagnosticsMetrics not available. HTTP handler metrics not reported.');
+        }
+    };
+    // If diagnosticsMetrics is available, run with base attributes context
+    // Otherwise, run without context (fallback for graceful degradation)
+    if (global.diagnosticsMetrics) {
+        await global.diagnosticsMetrics.runWithBaseAttributes(baseAttributes, executeWithBaseAttributes);
+    }
+    else {
+        console.warn('DiagnosticsMetrics not available. HTTP handler metrics not reported.');
+        await executeWithBaseAttributes();
+    }
 }
 exports.timings = timings;

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

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.broadcastStatusTrack = exports.trackStatus = exports.statusTrackHandler = exports.isStatusTrackBroadcast = exports.isStatusTrack = void 0;
 const cluster_1 = __importDefault(require("cluster"));
+const HttpAgentSingleton_1 = require("../../../HttpClient/middlewares/request/HttpAgentSingleton");
 const constants_1 = require("../../../constants");
 const BROADCAST_STATUS_TRACK = 'broadcastStatusTrack';
 const STATUS_TRACK = 'statusTrack';
@@ -26,6 +27,8 @@ const statusTrackHandler = async (ctx) => {
 };
 exports.statusTrackHandler = statusTrackHandler;
 const trackStatus = () => {
+    // Update diagnostics metrics (gauges for HTTP agent stats)
+    HttpAgentSingleton_1.HttpAgentSingleton.updateHttpAgentMetrics();
     // Flushing resets the metric accumulators, the CPU usage baseline and the
     // incoming request stats, so it must keep running even though nothing
     // consumes the returned metrics anymore.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/api",
-  "version": "6.53.0-beta.0",
+  "version": "6.53.0-beta.1",
   "description": "VTEX I/O API client",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",