@vtex/api 6.52.0 → 6.53.0-beta.0

package/CHANGELOG.md

@@ -5,7 +5,14 @@ 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

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/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/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/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>;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/api",
-  "version": "6.52.0",
+  "version": "6.53.0-beta.0",
   "description": "VTEX I/O API client",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -47,9 +47,14 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/host-metrics": "0.35.5",
+    "@opentelemetry/instrumentation": "0.57.2",
+    "@opentelemetry/instrumentation-koa": "0.47.1",
     "@types/koa": "^2.11.0",
     "@types/koa-compose": "^3.2.3",
-    "@vtex/diagnostics-nodejs": "0.1.0-beta.10",
+    "@vtex/diagnostics-nodejs": "0.1.8-io",
+    "@vtex/diagnostics-semconv": "5.5.2",
     "@vtex/node-error-report": "^0.0.3",
     "@wry/equality": "^0.1.9",
     "agentkeepalive": "^4.0.2",