@vtex/api 7.3.0 → 7.3.1-beta.0

package/lib/metrics/DiagnosticsMetrics.d.ts

@@ -7,6 +7,21 @@ import { Attributes } from '@opentelemetry/api';
  * 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()
@@ -25,6 +40,16 @@ import { Attributes } from '@opentelemetry/api';
  *
  * // 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 {
@@ -44,13 +69,69 @@ export declare class DiagnosticsMetrics {
      * 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 Attributes including 'operation' to identify the operation type (max of MAX_ATTRIBUTES attributes)
+     * @param attributes Custom attributes including 'operation' to identify the operation type (max 5 custom attributes)
      *
      * @example
      * ```typescript
@@ -67,9 +148,16 @@ export declare class DiagnosticsMetrics {
      * 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 attributes for the counter (max of MAX_ATTRIBUTES attributes, e.g., { method: 'GET', status: '2xx' })
+     * @param attributes Optional custom attributes for the counter (max 5 custom attributes, e.g., { method: 'GET', status: '2xx' })
      *
      * @example
      * ```typescript
@@ -81,9 +169,16 @@ export declare class DiagnosticsMetrics {
      * 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 attributes for the gauge (max of MAX_ATTRIBUTES attributes, e.g., { cache: 'pages' })
+     * @param attributes Optional custom attributes for the gauge (max 5 custom attributes, e.g., { cache: 'pages' })
      *
      * @example
      * ```typescript

package/lib/metrics/DiagnosticsMetrics.js

@@ -1,13 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiagnosticsMetrics = void 0;
+const api_1 = require("@opentelemetry/api");
 const client_1 = require("../service/metrics/client");
 const constants_1 = require("../constants");
 /**
- * Maximum number of attributes allowed per metric to control cardinality.
- * This limit applies to external usage (VTEX IO Apps) to prevent unbounded metric dimensions.
+ * 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 = 5;
+/**
+ * Context key for storing base attributes in OpenTelemetry context.
+ * These attributes are automatically merged with custom attributes in all metric methods.
  */
-const MAX_ATTRIBUTES = 7;
+const BASE_ATTRIBUTES_KEY = (0, api_1.createContextKey)('vtex.metrics.baseAttributes');
 /**
  * Converts an hrtime tuple [seconds, nanoseconds] to milliseconds.
  */
@@ -15,25 +24,27 @@ function hrtimeToMillis(hrtime) {
     return (hrtime[0] * 1e3) + (hrtime[1] / 1e6);
 }
 /**
- * Limits the number of attributes to prevent high cardinality.
- * Takes the first MAX_ATTRIBUTES entries if the limit is exceeded.
+ * Limits the number of custom attributes to prevent high cardinality.
+ * Takes the first MAX_CUSTOM_ATTRIBUTES entries if the limit is exceeded.
  *
- * @param attributes Optional attributes object
- * @returns Limited attributes object or undefined
+ * 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 limitAttributes(attributes) {
-    if (!attributes) {
+function limitCustomAttributes(customAttributes) {
+    if (!customAttributes) {
         return undefined;
     }
-    const entries = Object.entries(attributes);
-    if (entries.length <= MAX_ATTRIBUTES) {
-        return attributes;
+    const entries = Object.entries(customAttributes);
+    if (entries.length <= MAX_CUSTOM_ATTRIBUTES) {
+        return customAttributes;
     }
     if (constants_1.LINKED) {
-        console.warn(`Attribute limit exceeded: ${entries.length} attributes provided, using only the first ${MAX_ATTRIBUTES}. ` +
-            `Consider reducing the number of attributes to avoid high cardinality.`);
+        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_ATTRIBUTES));
+    return Object.fromEntries(entries.slice(0, MAX_CUSTOM_ATTRIBUTES));
 }
 /**
  * DiagnosticsMetrics provides a high-level API for recording metrics using
@@ -43,6 +54,21 @@ function limitAttributes(attributes) {
  * 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()
@@ -61,6 +87,16 @@ function limitAttributes(attributes) {
  *
  * // 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 {
@@ -110,13 +146,99 @@ class DiagnosticsMetrics {
             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 Attributes including 'operation' to identify the operation type (max of MAX_ATTRIBUTES attributes)
+     * @param attributes Custom attributes including 'operation' to identify the operation type (max 5 custom attributes)
      *
      * @example
      * ```typescript
@@ -135,18 +257,25 @@ class DiagnosticsMetrics {
         }
         // Convert hrtime to milliseconds if needed
         const milliseconds = Array.isArray(value) ? hrtimeToMillis(value) : value;
-        // Limit attributes to prevent high cardinality
-        const limitedAttributes = limitAttributes(attributes);
-        // Record to the single shared histogram with attributes
-        this.latencyHistogram.record(milliseconds, limitedAttributes);
+        // 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 attributes for the counter (max of MAX_ATTRIBUTES attributes, e.g., { method: 'GET', status: '2xx' })
+     * @param attributes Optional custom attributes for the counter (max 5 custom attributes, e.g., { method: 'GET', status: '2xx' })
      *
      * @example
      * ```typescript
@@ -166,18 +295,25 @@ class DiagnosticsMetrics {
             });
             this.counters.set(name, counter);
         }
-        // Limit attributes to prevent high cardinality
-        const limitedAttributes = limitAttributes(attributes);
+        // 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, limitedAttributes);
+        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 attributes for the gauge (max of MAX_ATTRIBUTES attributes, e.g., { cache: 'pages' })
+     * @param attributes Optional custom attributes for the gauge (max 5 custom attributes, e.g., { cache: 'pages' })
      *
      * @example
      * ```typescript
@@ -197,10 +333,10 @@ class DiagnosticsMetrics {
             });
             this.gauges.set(name, gauge);
         }
-        // Limit attributes to prevent high cardinality
-        const limitedAttributes = limitAttributes(attributes);
+        // 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, limitedAttributes);
+        this.gauges.get(name).set(value, mergedAttributes);
     }
 }
 exports.DiagnosticsMetrics = DiagnosticsMetrics;

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

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

package/package.json

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