@vtex/api 6.52.0 → 6.53.0-beta.1

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

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

package/lib/service/index.js

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

package/lib/service/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;