@vtex/api 6.51.3 → 6.53.0-beta.0

package/CHANGELOG.md

@@ -5,7 +5,39 @@ 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]
+## [6.53.0-beta.0]
+### 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`.
+
+## [6.52.0]
+### Added
+- Cluster-wide Prometheus `/metrics` aggregation. Each cluster worker keeps its own
+  prom-client registry, so serving `/metrics` from a single round-robin selected
+  worker exposed only that worker's counters; Prometheus read the per-scrape braid
+  of independent monotonic counters as counter resets and inflated `rate()` /
+  `increase()` on `runtime_http_*` counters by orders of magnitude. In multi-worker
+  mode the worker answering a scrape now asks the master for a merged, monotonic
+  view built from every worker's registry over the existing cluster IPC (via
+  prom-client's `AggregatorRegistry`), with a bounded timeout and a local-registry
+  fallback. Single-worker mode (`workers === 1`, includes `LINKED`) is unchanged.
+  Backport of #667 to the 6.x line.
+### 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. Backport of
+  #673 to the 6.x line.
+- `/_status` requests are now reported as `handler="builtin:status-track"`, matching
+  the other builtin handlers, instead of falling into the unnamed bucket.
 
 ## [6.51.0] - 2026-06-23
 ### Added

package/lib/constants.d.ts

@@ -2,6 +2,8 @@ export declare const NODE_VTEX_API_VERSION: any;
 export declare const DEFAULT_WORKSPACE = "master";
 export declare const IS_IO: string | undefined;
 export declare const PID: number;
+export declare const CLUSTER_ID: string;
+export declare const CLUSTER_ROLE: string;
 export declare const CACHE_CONTROL_HEADER = "cache-control";
 export declare const SEGMENT_HEADER = "x-vtex-segment";
 export declare const SESSION_HEADER = "x-vtex-session";
@@ -40,6 +42,15 @@ export declare const MAX_AGE: {
 };
 export declare const HTTP_SERVER_PORT = 5050;
 export declare const MAX_WORKERS = 4;
+export declare const AttributeKeys: {
+    VTEX_ACCOUNT_NAME: "vtex.account.name";
+    VTEX_IO_APP_AUTHOR_TYPE: "vtex_io.app.author_type";
+    VTEX_IO_APP_ID: "vtex_io.app.id";
+    VTEX_IO_CLUSTER_ID: "vtex_io.cluster.id";
+    VTEX_IO_CLUSTER_ROLE: "vtex_io.cluster.role";
+    VTEX_IO_WORKSPACE_NAME: "vtex_io.workspace.name";
+    VTEX_IO_WORKSPACE_TYPE: "vtex_io.workspace.type";
+};
 export declare const LINKED: boolean;
 export declare const REGION: string;
 export declare const PUBLIC_ENDPOINT: string;
@@ -58,3 +69,7 @@ export declare const PRODUCTION: boolean;
 export declare const INSPECT_DEBUGGER_PORT = 5858;
 export declare const cancellableMethods: Set<string>;
 export declare const LOG_CLIENT_INIT_TIMEOUT_MS = 5000;
+export declare const METRIC_CLIENT_INIT_TIMEOUT_MS = 5000;
+export declare const OTEL_EXPORTER_OTLP_ENDPOINT: string;
+export declare const DK_APP_ID: string;
+export declare const DIAGNOSTICS_TELEMETRY_ENABLED: boolean;

package/lib/constants.js

@@ -1,6 +1,8 @@
 "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.PID = exports.IS_IO = exports.DEFAULT_WORKSPACE = exports.NODE_VTEX_API_VERSION = void 0;
+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.AttributeKeys = 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.CLUSTER_ROLE = exports.CLUSTER_ID = 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 = void 0;
+const diagnostics_semconv_1 = require("@vtex/diagnostics-semconv");
 const app_1 = require("./utils/app");
 // tslint:disable-next-line
 const pkg = require('../package.json');
@@ -8,6 +10,8 @@ exports.NODE_VTEX_API_VERSION = pkg.version;
 exports.DEFAULT_WORKSPACE = 'master';
 exports.IS_IO = process.env.VTEX_IO;
 exports.PID = process.pid;
+exports.CLUSTER_ID = process.env.VTEX_CLUSTER_ID;
+exports.CLUSTER_ROLE = process.env.VTEX_CLUSTER_ROLE;
 exports.CACHE_CONTROL_HEADER = 'cache-control';
 exports.SEGMENT_HEADER = 'x-vtex-segment';
 exports.SESSION_HEADER = 'x-vtex-session';
@@ -45,6 +49,15 @@ exports.MAX_AGE = {
 };
 exports.HTTP_SERVER_PORT = 5050;
 exports.MAX_WORKERS = 4;
+exports.AttributeKeys = {
+    VTEX_ACCOUNT_NAME: diagnostics_semconv_1.ATTR_VTEX_ACCOUNT_NAME,
+    VTEX_IO_APP_AUTHOR_TYPE: diagnostics_semconv_1.ATTR_VTEX_IO_APP_AUTHOR_TYPE,
+    VTEX_IO_APP_ID: diagnostics_semconv_1.ATTR_VTEX_IO_APP_ID,
+    VTEX_IO_CLUSTER_ID: diagnostics_semconv_1.ATTR_VTEX_IO_CLUSTER_ID,
+    VTEX_IO_CLUSTER_ROLE: diagnostics_semconv_1.ATTR_VTEX_IO_CLUSTER_ROLE,
+    VTEX_IO_WORKSPACE_NAME: diagnostics_semconv_1.ATTR_VTEX_IO_WORKSPACE_NAME,
+    VTEX_IO_WORKSPACE_TYPE: diagnostics_semconv_1.ATTR_VTEX_IO_WORKSPACE_TYPE,
+};
 exports.LINKED = !!process.env.VTEX_APP_LINK;
 exports.REGION = process.env.VTEX_REGION;
 exports.PUBLIC_ENDPOINT = process.env.VTEX_PUBLIC_ENDPOINT || 'myvtex.com';
@@ -65,3 +78,7 @@ exports.PRODUCTION = process.env.VTEX_PRODUCTION === 'true';
 exports.INSPECT_DEBUGGER_PORT = 5858;
 exports.cancellableMethods = new Set(['GET', 'OPTIONS', 'HEAD']);
 exports.LOG_CLIENT_INIT_TIMEOUT_MS = 5000;
+exports.METRIC_CLIENT_INIT_TIMEOUT_MS = 5000;
+exports.OTEL_EXPORTER_OTLP_ENDPOINT = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+exports.DK_APP_ID = process.env.NODE_VTEX_API_DK_APP_ID || 'apps-team';
+exports.DIAGNOSTICS_TELEMETRY_ENABLED = process.env.VTEX_DIAGNOSTICS_TELEMETRY_ENABLED === 'true';

package/lib/metrics/DiagnosticsMetrics.d.ts

@@ -0,0 +1,189 @@
+import { Attributes } from '@opentelemetry/api';
+/**
+ * DiagnosticsMetrics provides a high-level API for recording metrics using
+ * the @vtex/diagnostics-nodejs library. It completely abstracts instrument
+ * management, bucket configuration, and lifecycle.
+ *
+ * Uses a single histogram for all latency measurements with attributes to differentiate.
+ * This follows OpenTelemetry best practices and reduces metric cardinality.
+ *
+ * ## Base Attributes (Request Context)
+ *
+ * DiagnosticsMetrics supports automatic merging of request-scoped "base attributes"
+ * with custom attributes provided in each metric call. This is useful for automatically
+ * including request context (account, status_code, route_id, etc.) in all metrics
+ * recorded during a request lifecycle.
+ *
+ * Use `runWithBaseAttributes()` to set base attributes for a scope. All metric calls
+ * within that scope will automatically include these base attributes, merged with
+ * any custom attributes provided.
+ *
+ * **Important:** Base attributes take precedence over custom attributes. If a custom
+ * attribute has the same key as a base attribute, the custom attribute is silently
+ * dropped and the base attribute value is used.
+ *
+ * @example
+ * ```typescript
+ * const diagnosticsMetrics = new DiagnosticsMetrics()
+ * diagnosticsMetrics.initMetricClient()
+ *
+ * // Record latency with operation type in attributes
+ * const start = process.hrtime()
+ * // ... do work ...
+ * diagnosticsMetrics.recordLatency(process.hrtime(start), { operation: 'api-call', status: '2xx' })
+ *
+ * // Or from milliseconds
+ * diagnosticsMetrics.recordLatency(42.5, { operation: 'db-query', status: 'success' })
+ *
+ * // Increment a counter
+ * diagnosticsMetrics.incrementCounter('http_requests_total', 1, { method: 'GET', status: '2xx' })
+ *
+ * // Set a gauge value
+ * diagnosticsMetrics.setGauge('cache_items_current', 1024, { cache: 'pages' })
+ *
+ * // Using base attributes for request context
+ * await diagnosticsMetrics.runWithBaseAttributes(
+ *   { 'vtex.account.name': 'mystore', status_code: 200 },
+ *   async () => {
+ *     // All metrics recorded here will include the base attributes
+ *     diagnosticsMetrics.recordLatency(100, { operation: 'custom-op' })
+ *     // Result: { 'vtex.account.name': 'mystore', status_code: 200, operation: 'custom-op' }
+ *   }
+ * )
+ * ```
+ */
+export declare class DiagnosticsMetrics {
+    private metricsClient;
+    private clientInitPromise;
+    private latencyHistogram;
+    private counters;
+    private gauges;
+    constructor();
+    /**
+     * Initialize the metrics client with timeout handling.
+     * Called automatically in constructor.
+     */
+    private initMetricClient;
+    /**
+     * Create the single shared histogram for all latency measurements.
+     * Called after metric client is initialized.
+     */
+    private createLatencyHistogram;
+    /**
+     * Execute a function with base attributes set in the OpenTelemetry context.
+     * All metric calls within the function will automatically include these base attributes,
+     * merged with any custom attributes provided in each call.
+     *
+     * Base attributes take precedence over custom attributes when there are key conflicts.
+     * Conflicting custom attributes are silently dropped.
+     *
+     * @param baseAttributes Base attributes to include in all metrics within the scope
+     * @param fn Function to execute with the base attributes context
+     * @returns The return value of the function
+     *
+     * @example
+     * ```typescript
+     * // In a request middleware
+     * await diagnosticsMetrics.runWithBaseAttributes(
+     *   {
+     *     'vtex.account.name': ctx.vtex.account,
+     *     status_code: ctx.status,
+     *     route_id: ctx.vtex.route.id,
+     *   },
+     *   async () => {
+     *     await next()
+     *   }
+     * )
+     *
+     * // In app code (custom attributes are merged with base)
+     * diagnosticsMetrics.recordLatency(elapsed, { operation: 'my-operation', status: 'success' })
+     * // Result includes both base attributes AND custom attributes
+     * ```
+     */
+    runWithBaseAttributes<T>(baseAttributes: Attributes, fn: () => T): T;
+    /**
+     * Get the base attributes from the current OpenTelemetry context.
+     * Returns undefined if no base attributes are set.
+     */
+    private getBaseAttributes;
+    /**
+     * Merge base attributes from context with provided custom attributes.
+     * Base attributes take precedence over custom attributes when there are key conflicts.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES before merging.
+     * Custom attributes with keys that conflict with base attributes are silently dropped.
+     * Base attributes are not limited.
+     *
+     * @param customAttributes Custom attributes provided by the caller
+     * @returns Merged attributes (base + non-conflicting limited custom) or undefined if both are empty
+     */
+    private mergeAttributes;
+    /**
+     * Record a latency measurement using the single shared histogram.
+     * Accepts either an hrtime tuple from process.hrtime() or milliseconds as a number.
+     * Use attributes to differentiate between different operations.
+     *
+     * Base attributes from the current context (set via `runWithBaseAttributes`) are
+     * automatically merged with the provided custom attributes. Base attributes take
+     * precedence - if a custom attribute key conflicts with a base attribute key,
+     * the custom attribute is silently dropped.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     *
+     * @param value Either [seconds, nanoseconds] from process.hrtime() or milliseconds
+     * @param attributes Custom attributes including 'operation' to identify the operation type (max 5 custom attributes)
+     *
+     * @example
+     * ```typescript
+     * const start = process.hrtime()
+     * // ... do work ...
+     * diagnosticsMetrics.recordLatency(process.hrtime(start), { operation: 'api-call', status: '2xx' })
+     *
+     * // Or with milliseconds
+     * diagnosticsMetrics.recordLatency(42.5, { operation: 'db-query', status: 'success' })
+     * ```
+     */
+    recordLatency(value: [number, number] | number, attributes?: Attributes): void;
+    /**
+     * Increment a counter by a specific value.
+     * Multiple counters are stored by name since counters represent different types of events.
+     *
+     * Base attributes from the current context (set via `runWithBaseAttributes`) are
+     * automatically merged with the provided custom attributes. Base attributes take
+     * precedence - if a custom attribute key conflicts with a base attribute key,
+     * the custom attribute is silently dropped.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     *
+     * @param name Counter name (e.g., 'http_requests_total', 'cache_hits_total')
+     * @param value Amount to increment by (typically 1)
+     * @param attributes Optional custom attributes for the counter (max 5 custom attributes, e.g., { method: 'GET', status: '2xx' })
+     *
+     * @example
+     * ```typescript
+     * diagnosticsMetrics.incrementCounter('http_requests_total', 1, { method: 'GET', status: '2xx' })
+     * ```
+     */
+    incrementCounter(name: string, value: number, attributes?: Attributes): void;
+    /**
+     * Set a gauge to a specific value (current state).
+     * Multiple gauges are stored by name since gauges represent different types of measurements.
+     *
+     * Base attributes from the current context (set via `runWithBaseAttributes`) are
+     * automatically merged with the provided custom attributes. Base attributes take
+     * precedence - if a custom attribute key conflicts with a base attribute key,
+     * the custom attribute is silently dropped.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     *
+     * @param name Gauge name (e.g., 'cache_items_current', 'memory_usage_bytes')
+     * @param value Current value
+     * @param attributes Optional custom attributes for the gauge (max 5 custom attributes, e.g., { cache: 'pages' })
+     *
+     * @example
+     * ```typescript
+     * diagnosticsMetrics.setGauge('cache_items_current', 1024, { cache: 'pages' })
+     * ```
+     */
+    setGauge(name: string, value: number, attributes?: Attributes): void;
+}

package/lib/metrics/DiagnosticsMetrics.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagnosticsMetrics = void 0;
+const api_1 = require("@opentelemetry/api");
+const constants_1 = require("../constants");
+const client_1 = require("../service/metrics/client");
+/**
+ * Maximum number of custom attributes allowed per metric call to control cardinality.
+ * This limit applies only to custom attributes provided by callers (VTEX IO Apps).
+ * Base attributes (set via runWithBaseAttributes) are not counted toward this limit.
+ *
+ * Total attributes sent = base attributes + custom attributes (up to MAX_CUSTOM_ATTRIBUTES)
+ */
+const MAX_CUSTOM_ATTRIBUTES = 7;
+/**
+ * Context key for storing base attributes in OpenTelemetry context.
+ * These attributes are automatically merged with custom attributes in all metric methods.
+ */
+const BASE_ATTRIBUTES_KEY = (0, api_1.createContextKey)('vtex.metrics.baseAttributes');
+/**
+ * Converts an hrtime tuple [seconds, nanoseconds] to milliseconds.
+ */
+function hrtimeToMillis(hrtime) {
+    return (hrtime[0] * 1e3) + (hrtime[1] / 1e6);
+}
+/**
+ * Limits the number of custom attributes to prevent high cardinality.
+ * Takes the first MAX_CUSTOM_ATTRIBUTES entries if the limit is exceeded.
+ *
+ * Note: This limit applies only to custom attributes. Base attributes are not limited.
+ *
+ * @param customAttributes Optional custom attributes object
+ * @returns Limited custom attributes object or undefined
+ */
+function limitCustomAttributes(customAttributes) {
+    if (!customAttributes) {
+        return undefined;
+    }
+    const entries = Object.entries(customAttributes);
+    if (entries.length <= MAX_CUSTOM_ATTRIBUTES) {
+        return customAttributes;
+    }
+    if (constants_1.LINKED) {
+        console.warn(`Custom attribute limit exceeded: ${entries.length} custom attributes provided, using only the first ${MAX_CUSTOM_ATTRIBUTES}. ` +
+            `Consider reducing the number of custom attributes to avoid high cardinality. `);
+    }
+    return Object.fromEntries(entries.slice(0, MAX_CUSTOM_ATTRIBUTES));
+}
+/**
+ * DiagnosticsMetrics provides a high-level API for recording metrics using
+ * the @vtex/diagnostics-nodejs library. It completely abstracts instrument
+ * management, bucket configuration, and lifecycle.
+ *
+ * Uses a single histogram for all latency measurements with attributes to differentiate.
+ * This follows OpenTelemetry best practices and reduces metric cardinality.
+ *
+ * ## Base Attributes (Request Context)
+ *
+ * DiagnosticsMetrics supports automatic merging of request-scoped "base attributes"
+ * with custom attributes provided in each metric call. This is useful for automatically
+ * including request context (account, status_code, route_id, etc.) in all metrics
+ * recorded during a request lifecycle.
+ *
+ * Use `runWithBaseAttributes()` to set base attributes for a scope. All metric calls
+ * within that scope will automatically include these base attributes, merged with
+ * any custom attributes provided.
+ *
+ * **Important:** Base attributes take precedence over custom attributes. If a custom
+ * attribute has the same key as a base attribute, the custom attribute is silently
+ * dropped and the base attribute value is used.
+ *
+ * @example
+ * ```typescript
+ * const diagnosticsMetrics = new DiagnosticsMetrics()
+ * diagnosticsMetrics.initMetricClient()
+ *
+ * // Record latency with operation type in attributes
+ * const start = process.hrtime()
+ * // ... do work ...
+ * diagnosticsMetrics.recordLatency(process.hrtime(start), { operation: 'api-call', status: '2xx' })
+ *
+ * // Or from milliseconds
+ * diagnosticsMetrics.recordLatency(42.5, { operation: 'db-query', status: 'success' })
+ *
+ * // Increment a counter
+ * diagnosticsMetrics.incrementCounter('http_requests_total', 1, { method: 'GET', status: '2xx' })
+ *
+ * // Set a gauge value
+ * diagnosticsMetrics.setGauge('cache_items_current', 1024, { cache: 'pages' })
+ *
+ * // Using base attributes for request context
+ * await diagnosticsMetrics.runWithBaseAttributes(
+ *   { 'vtex.account.name': 'mystore', status_code: 200 },
+ *   async () => {
+ *     // All metrics recorded here will include the base attributes
+ *     diagnosticsMetrics.recordLatency(100, { operation: 'custom-op' })
+ *     // Result: { 'vtex.account.name': 'mystore', status_code: 200, operation: 'custom-op' }
+ *   }
+ * )
+ * ```
+ */
+class DiagnosticsMetrics {
+    constructor() {
+        this.counters = new Map();
+        this.gauges = new Map();
+        this.initMetricClient();
+    }
+    /**
+     * Initialize the metrics client with timeout handling.
+     * Called automatically in constructor.
+     */
+    initMetricClient() {
+        if (this.clientInitPromise) {
+            return this.clientInitPromise;
+        }
+        this.clientInitPromise = (async () => {
+            try {
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error('Metric client initialization timeout')), constants_1.METRIC_CLIENT_INIT_TIMEOUT_MS);
+                });
+                this.metricsClient = await Promise.race([
+                    (0, client_1.getMetricClient)(),
+                    timeoutPromise,
+                ]);
+                // Create the single latency histogram after client is ready
+                this.createLatencyHistogram();
+                return this.metricsClient;
+            }
+            catch (error) {
+                console.error('Failed to initialize metric client:', error);
+                return undefined;
+            }
+        })();
+        return this.clientInitPromise;
+    }
+    /**
+     * Create the single shared histogram for all latency measurements.
+     * Called after metric client is initialized.
+     */
+    createLatencyHistogram() {
+        if (!this.metricsClient) {
+            return;
+        }
+        this.latencyHistogram = this.metricsClient.createHistogram('io_app_operation_duration_milliseconds', {
+            description: 'Duration of VTEX IO app operations in milliseconds',
+            unit: 'ms',
+        });
+    }
+    /**
+     * Execute a function with base attributes set in the OpenTelemetry context.
+     * All metric calls within the function will automatically include these base attributes,
+     * merged with any custom attributes provided in each call.
+     *
+     * Base attributes take precedence over custom attributes when there are key conflicts.
+     * Conflicting custom attributes are silently dropped.
+     *
+     * @param baseAttributes Base attributes to include in all metrics within the scope
+     * @param fn Function to execute with the base attributes context
+     * @returns The return value of the function
+     *
+     * @example
+     * ```typescript
+     * // In a request middleware
+     * await diagnosticsMetrics.runWithBaseAttributes(
+     *   {
+     *     'vtex.account.name': ctx.vtex.account,
+     *     status_code: ctx.status,
+     *     route_id: ctx.vtex.route.id,
+     *   },
+     *   async () => {
+     *     await next()
+     *   }
+     * )
+     *
+     * // In app code (custom attributes are merged with base)
+     * diagnosticsMetrics.recordLatency(elapsed, { operation: 'my-operation', status: 'success' })
+     * // Result includes both base attributes AND custom attributes
+     * ```
+     */
+    runWithBaseAttributes(baseAttributes, fn) {
+        const currentContext = api_1.context.active();
+        const newContext = currentContext.setValue(BASE_ATTRIBUTES_KEY, baseAttributes);
+        return api_1.context.with(newContext, fn);
+    }
+    /**
+     * Get the base attributes from the current OpenTelemetry context.
+     * Returns undefined if no base attributes are set.
+     */
+    getBaseAttributes() {
+        return api_1.context.active().getValue(BASE_ATTRIBUTES_KEY);
+    }
+    /**
+     * Merge base attributes from context with provided custom attributes.
+     * Base attributes take precedence over custom attributes when there are key conflicts.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES before merging.
+     * Custom attributes with keys that conflict with base attributes are silently dropped.
+     * Base attributes are not limited.
+     *
+     * @param customAttributes Custom attributes provided by the caller
+     * @returns Merged attributes (base + non-conflicting limited custom) or undefined if both are empty
+     */
+    mergeAttributes(customAttributes) {
+        const baseAttributes = this.getBaseAttributes();
+        // Limit custom attributes before merging
+        const limitedCustomAttributes = limitCustomAttributes(customAttributes);
+        if (!baseAttributes && !limitedCustomAttributes) {
+            return undefined;
+        }
+        if (!baseAttributes) {
+            return limitedCustomAttributes;
+        }
+        if (!limitedCustomAttributes) {
+            return baseAttributes;
+        }
+        // Filter out custom attributes that conflict with base attributes (base takes precedence)
+        const baseKeys = new Set(Object.keys(baseAttributes));
+        const nonConflictingCustomAttributes = {};
+        for (const [key, value] of Object.entries(limitedCustomAttributes)) {
+            if (!baseKeys.has(key)) {
+                nonConflictingCustomAttributes[key] = value;
+            }
+            // Silently drop conflicting custom attributes - base attributes take precedence
+        }
+        // Merge: base attributes + non-conflicting custom attributes
+        return { ...baseAttributes, ...nonConflictingCustomAttributes };
+    }
+    /**
+     * Record a latency measurement using the single shared histogram.
+     * Accepts either an hrtime tuple from process.hrtime() or milliseconds as a number.
+     * Use attributes to differentiate between different operations.
+     *
+     * Base attributes from the current context (set via `runWithBaseAttributes`) are
+     * automatically merged with the provided custom attributes. Base attributes take
+     * precedence - if a custom attribute key conflicts with a base attribute key,
+     * the custom attribute is silently dropped.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     *
+     * @param value Either [seconds, nanoseconds] from process.hrtime() or milliseconds
+     * @param attributes Custom attributes including 'operation' to identify the operation type (max 5 custom attributes)
+     *
+     * @example
+     * ```typescript
+     * const start = process.hrtime()
+     * // ... do work ...
+     * diagnosticsMetrics.recordLatency(process.hrtime(start), { operation: 'api-call', status: '2xx' })
+     *
+     * // Or with milliseconds
+     * diagnosticsMetrics.recordLatency(42.5, { operation: 'db-query', status: 'success' })
+     * ```
+     */
+    recordLatency(value, attributes) {
+        if (!this.latencyHistogram) {
+            console.warn('DiagnosticsMetrics not initialized. Call initialize() first.');
+            return;
+        }
+        // Convert hrtime to milliseconds if needed
+        const milliseconds = Array.isArray(value) ? hrtimeToMillis(value) : value;
+        // Merge base attributes from context with custom attributes (custom attrs are limited internally)
+        const mergedAttributes = this.mergeAttributes(attributes);
+        // Record to the single shared histogram with merged attributes
+        this.latencyHistogram.record(milliseconds, mergedAttributes);
+    }
+    /**
+     * Increment a counter by a specific value.
+     * Multiple counters are stored by name since counters represent different types of events.
+     *
+     * Base attributes from the current context (set via `runWithBaseAttributes`) are
+     * automatically merged with the provided custom attributes. Base attributes take
+     * precedence - if a custom attribute key conflicts with a base attribute key,
+     * the custom attribute is silently dropped.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     *
+     * @param name Counter name (e.g., 'http_requests_total', 'cache_hits_total')
+     * @param value Amount to increment by (typically 1)
+     * @param attributes Optional custom attributes for the counter (max 5 custom attributes, e.g., { method: 'GET', status: '2xx' })
+     *
+     * @example
+     * ```typescript
+     * diagnosticsMetrics.incrementCounter('http_requests_total', 1, { method: 'GET', status: '2xx' })
+     * ```
+     */
+    incrementCounter(name, value, attributes) {
+        if (!this.metricsClient) {
+            console.warn('DiagnosticsMetrics not initialized. Call initialize() first.');
+            return;
+        }
+        // Get or create counter instrument
+        if (!this.counters.has(name)) {
+            const counter = this.metricsClient.createCounter(name, {
+                description: `Counter for ${name}`,
+                unit: '1',
+            });
+            this.counters.set(name, counter);
+        }
+        // Merge base attributes from context with custom attributes (custom attrs are limited internally)
+        const mergedAttributes = this.mergeAttributes(attributes);
+        // Increment the counter
+        this.counters.get(name).add(value, mergedAttributes);
+    }
+    /**
+     * Set a gauge to a specific value (current state).
+     * Multiple gauges are stored by name since gauges represent different types of measurements.
+     *
+     * Base attributes from the current context (set via `runWithBaseAttributes`) are
+     * automatically merged with the provided custom attributes. Base attributes take
+     * precedence - if a custom attribute key conflicts with a base attribute key,
+     * the custom attribute is silently dropped.
+     *
+     * Custom attributes are limited to MAX_CUSTOM_ATTRIBUTES (5). Base attributes are not limited.
+     *
+     * @param name Gauge name (e.g., 'cache_items_current', 'memory_usage_bytes')
+     * @param value Current value
+     * @param attributes Optional custom attributes for the gauge (max 5 custom attributes, e.g., { cache: 'pages' })
+     *
+     * @example
+     * ```typescript
+     * diagnosticsMetrics.setGauge('cache_items_current', 1024, { cache: 'pages' })
+     * ```
+     */
+    setGauge(name, value, attributes) {
+        if (!this.metricsClient) {
+            console.warn('DiagnosticsMetrics not initialized. Call initialize() first.');
+            return;
+        }
+        // Get or create gauge instrument
+        if (!this.gauges.has(name)) {
+            const gauge = this.metricsClient.createGauge(name, {
+                description: `Gauge for ${name}`,
+                unit: '1',
+            });
+            this.gauges.set(name, gauge);
+        }
+        // Merge base attributes from context with custom attributes (custom attrs are limited internally)
+        const mergedAttributes = this.mergeAttributes(attributes);
+        // Set the gauge value
+        this.gauges.get(name).set(value, mergedAttributes);
+    }
+}
+exports.DiagnosticsMetrics = DiagnosticsMetrics;

package/lib/service/logger/client.js

@@ -23,11 +23,6 @@ async function initializeClient(account, workspace, appName) {
         const telemetryClient = await (0, telemetry_1.getTelemetryClient)();
         const logsConfig = diagnostics_nodejs_1.Exporters.CreateLogsExporterConfig({
             endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
-            path: process.env.OTEL_EXPORTER_OTLP_PATH || '/v1/logs',
-            protocol: 'http',
-            interval: 5,
-            timeoutSeconds: 5,
-            headers: { 'Content-Type': 'application/json' },
         });
         const logsExporter = diagnostics_nodejs_1.Exporters.CreateExporter(logsConfig, 'otlp');
         await logsExporter.initialize();

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;