@vtex/api 6.51.3 → 6.53.0-beta.0

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

@@ -0,0 +1,2 @@
+import { Types } from '@vtex/diagnostics-nodejs';
+export declare const getMetricClient: () => Promise<Types.MetricClient>;

package/lib/service/metrics/client.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMetricClient = void 0;
+const telemetry_1 = require("../telemetry");
+class MetricClientSingleton {
+    constructor() { }
+    static getInstance() {
+        if (!MetricClientSingleton.instance) {
+            MetricClientSingleton.instance = new MetricClientSingleton();
+        }
+        return MetricClientSingleton.instance;
+    }
+    async getClient() {
+        if (this.client) {
+            return this.client;
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.initPromise = this.initializeClient();
+        return this.initPromise;
+    }
+    async initializeClient() {
+        try {
+            const { metricsClient } = await (0, telemetry_1.initializeTelemetry)();
+            this.client = metricsClient;
+            this.initPromise = undefined;
+            return metricsClient;
+        }
+        catch (error) {
+            console.error('Failed to initialize metrics client:', error);
+            this.initPromise = undefined;
+            throw error;
+        }
+    }
+}
+const getMetricClient = () => MetricClientSingleton.getInstance().getClient();
+exports.getMetricClient = getMetricClient;

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,181 @@
+"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. */
+// tslint:disable-next-line:variable-name
+const __resetForTests = () => {
+    masterAggregatorRegistry = undefined;
+    workerAggregatorRegistry = undefined;
+    pendingRequests.forEach((p) => clearTimeout(p.timer));
+    pendingRequests.clear();
+    requestCounter = 0;
+};
+exports.__resetForTests = __resetForTests;

package/lib/service/metrics/instruments/hostMetrics.d.ts

@@ -0,0 +1,14 @@
+import { MeterProvider } from '@opentelemetry/api';
+import { InstrumentationBase, InstrumentationConfig } from '@opentelemetry/instrumentation';
+interface HostMetricsInstrumentationConfig extends InstrumentationConfig {
+    name?: string;
+    meterProvider?: MeterProvider;
+}
+export declare class HostMetricsInstrumentation extends InstrumentationBase<HostMetricsInstrumentationConfig> {
+    private hostMetrics?;
+    constructor(config?: HostMetricsInstrumentationConfig);
+    init(): void;
+    enable(): void;
+    disable(): void;
+}
+export {};

package/lib/service/metrics/instruments/hostMetrics.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostMetricsInstrumentation = void 0;
+const host_metrics_1 = require("@opentelemetry/host-metrics");
+const instrumentation_1 = require("@opentelemetry/instrumentation");
+class HostMetricsInstrumentation extends instrumentation_1.InstrumentationBase {
+    constructor(config = {}) {
+        const instrumentationName = config.name || 'host-metrics-instrumentation';
+        const instrumentationVersion = '1.0.0';
+        super(instrumentationName, instrumentationVersion, config);
+    }
+    init() {
+        // No-op: instrumentation is started explicitly in enable().
+    }
+    enable() {
+        if (!this._config.meterProvider) {
+            throw new Error('MeterProvider is required for HostMetricsInstrumentation');
+        }
+        this.hostMetrics = new host_metrics_1.HostMetrics({
+            meterProvider: this._config.meterProvider,
+            name: this._config.name || 'host-metrics',
+        });
+        this.hostMetrics.start();
+        console.debug('HostMetricsInstrumentation enabled');
+    }
+    disable() {
+        if (this.hostMetrics) {
+            this.hostMetrics = undefined;
+            console.debug('HostMetricsInstrumentation disabled');
+        }
+    }
+}
+exports.HostMetricsInstrumentation = HostMetricsInstrumentation;

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

@@ -1,3 +1,11 @@
+import { Logs, Metrics, Traces } from '@vtex/diagnostics-nodejs';
 import { TelemetryClient } from '@vtex/diagnostics-nodejs/dist/telemetry';
+interface TelemetryClients {
+    logsClient: Logs.LogClient;
+    metricsClient: Metrics.MetricsClient;
+    tracesClient: Traces.TraceClient;
+}
+export declare function initializeTelemetry(): Promise<TelemetryClients>;
 export declare function getTelemetryClient(): Promise<TelemetryClient>;
-export declare function resetTelemetryClient(): void;
+export declare function resetTelemetry(): void;
+export {};

package/lib/service/telemetry/client.js

@@ -1,57 +1,123 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetTelemetryClient = exports.getTelemetryClient = void 0;
+exports.resetTelemetry = exports.getTelemetryClient = exports.initializeTelemetry = void 0;
+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 {
-    constructor() {
-        this.initializationPromise = undefined;
-    }
     static getInstance() {
         if (!TelemetryClientSingleton.instance) {
             TelemetryClientSingleton.instance = new TelemetryClientSingleton();
         }
         return TelemetryClientSingleton.instance;
     }
-    async initTelemetryClient() {
+    constructor() {
+        this.initializationPromise = undefined;
+        this.initializeTracesClient = async (telemetryClient) => await telemetryClient.newTracesClient({
+            exporter: diagnostics_nodejs_1.Exporters.CreateExporter(diagnostics_nodejs_1.Exporters.CreateTracesExporterConfig({
+                endpoint: constants_1.OTEL_EXPORTER_OTLP_ENDPOINT,
+            }), 'otlp'),
+        });
+        this.initializeMetricsClient = async (telemetryClient) => await telemetryClient.newMetricsClient({
+            exporter: diagnostics_nodejs_1.Exporters.CreateExporter(diagnostics_nodejs_1.Exporters.CreateMetricsExporterConfig({
+                endpoint: constants_1.OTEL_EXPORTER_OTLP_ENDPOINT,
+                interval: 60,
+                temporality: 'delta',
+                timeoutSeconds: 60,
+            }), 'otlp'),
+        });
+        this.initializeLogsClient = async (telemetryClient) => await telemetryClient.newLogsClient({
+            exporter: diagnostics_nodejs_1.Exporters.CreateExporter(diagnostics_nodejs_1.Exporters.CreateLogsExporterConfig({
+                endpoint: constants_1.OTEL_EXPORTER_OTLP_ENDPOINT,
+            }), 'otlp'),
+            loggerName: `node-vtex-api-${APPLICATION_ID}`,
+        });
+    }
+    async getTelemetryClients() {
+        if (this.telemetryClients) {
+            return this.telemetryClients;
+        }
+        if (this.initializationPromise) {
+            return this.initializationPromise;
+        }
+        this.initializationPromise = this.initializeTelemetryClients();
+        return this.initializationPromise;
+    }
+    /**
+     * Exposes the raw @vtex/diagnostics-nodejs TelemetryClient (rather than one of the three
+     * pre-built traces/metrics/logs clients) for consumers that need to build their own client
+     * with per-call configuration — e.g. the structured logger's per-request loggerName.
+     */
+    async getRawTelemetryClient() {
+        await this.getTelemetryClients();
+        return this.rawTelemetryClient;
+    }
+    reset() {
+        this.telemetryClients = undefined;
+        this.rawTelemetryClient = undefined;
+        this.initializationPromise = undefined;
+    }
+    async initializeTelemetryClients() {
         try {
-            const telemetryClient = await (0, diagnostics_nodejs_1.NewTelemetryClient)('node-vtex-api', constants_1.APP.ID || 'vtex-app', {
+            const telemetryClient = await (0, diagnostics_nodejs_1.NewTelemetryClient)(constants_1.DK_APP_ID, 'node-vtex-api', APPLICATION_ID, {
                 additionalAttrs: {
+                    [constants_1.AttributeKeys.VTEX_IO_APP_ID]: APPLICATION_ID,
+                    'vendor': constants_1.APP.VENDOR,
                     'version': constants_1.APP.VERSION || '',
-                    'environment': process.env.VTEX_WORKSPACE || 'development',
+                    [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,
             });
-            this.telemetryClient = telemetryClient;
-            return telemetryClient;
+            this.rawTelemetryClient = telemetryClient;
+            const [tracesClient, metricsClient, logsClient] = await Promise.all([
+                this.initializeTracesClient(telemetryClient),
+                this.initializeMetricsClient(telemetryClient),
+                this.initializeLogsClient(telemetryClient),
+            ]);
+            if (constants_1.DIAGNOSTICS_TELEMETRY_ENABLED) {
+                console.log(`Telemetry enabled for app: ${constants_1.APP.ID} (vendor: ${constants_1.APP.VENDOR})`);
+                const instrumentations = [
+                    ...diagnostics_nodejs_1.Instrumentation.CommonInstrumentations.minimal(),
+                    new instrumentation_koa_1.KoaInstrumentation(),
+                    new hostMetrics_1.HostMetricsInstrumentation({
+                        meterProvider: metricsClient.provider(),
+                        name: 'host-metrics-instrumentation',
+                    }),
+                ];
+                telemetryClient.registerInstrumentations(instrumentations);
+            }
+            const clients = {
+                logsClient,
+                metricsClient,
+                tracesClient,
+            };
+            this.telemetryClients = clients;
+            return clients;
         }
         catch (error) {
-            console.error('Failed to initialize telemetry client:', error);
+            console.error('Failed to initialize telemetry clients:', error);
             throw error;
         }
         finally {
             this.initializationPromise = undefined;
         }
     }
-    async getClient() {
-        if (this.telemetryClient) {
-            return this.telemetryClient;
-        }
-        if (this.initializationPromise) {
-            return this.initializationPromise;
-        }
-        this.initializationPromise = this.initTelemetryClient();
-        return this.initializationPromise;
-    }
-    reset() {
-        this.telemetryClient = undefined;
-        this.initializationPromise = undefined;
-    }
 }
+async function initializeTelemetry() {
+    return TelemetryClientSingleton.getInstance().getTelemetryClients();
+}
+exports.initializeTelemetry = initializeTelemetry;
 async function getTelemetryClient() {
-    return TelemetryClientSingleton.getInstance().getClient();
+    return TelemetryClientSingleton.getInstance().getRawTelemetryClient();
 }
 exports.getTelemetryClient = getTelemetryClient;
-function resetTelemetryClient() {
+function resetTelemetry() {
     TelemetryClientSingleton.getInstance().reset();
 }
-exports.resetTelemetryClient = resetTelemetryClient;
+exports.resetTelemetry = resetTelemetry;

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

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