@vtex/api 6.52.0 → 6.53.0-beta.1

package/CHANGELOG.md

@@ -5,7 +5,17 @@ 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.1]
+### 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. Metrics are wired into the request pipeline itself, not just exposed as a
+  library API: HTTP handler latency/counters, request closed/aborted/total counters, outbound
+  HTTP client metrics, HTTP agent socket gauges, and the `@metric` GraphQL directive all emit
+  through `DiagnosticsMetrics` at the same points `master` does. Disabled by default; opt in
+  per app with `VTEX_DIAGNOSTICS_TELEMETRY_ENABLED=true`.
 
 ## [6.52.0]
 ### Added

package/lib/HttpClient/middlewares/metrics.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.metricsMiddleware = void 0;
+const constants_1 = require("../../constants");
 const RequestCancelledError_1 = require("../../errors/RequestCancelledError");
 const requestStats_1 = require("../../service/worker/runtime/http/middlewares/requestStats");
 const utils_1 = require("../../utils");
 const retry_1 = require("../../utils/retry");
 const status_1 = require("../../utils/status");
+const DEFAULT_ACCOUNT = 'unknown';
 const metricsMiddleware = ({ metrics, serverTiming, name }) => {
     const serverTimingStart = process.hrtime();
     const serverTimingLabel = (0, utils_1.shrinkTimings)((0, utils_1.formatTimingName)({
@@ -14,6 +16,7 @@ const metricsMiddleware = ({ metrics, serverTiming, name }) => {
         target: name || 'unknown',
     }));
     return async (ctx, next) => {
+        var _a, _b;
         const start = process.hrtime();
         let status = 'unknown';
         let errorCode;
@@ -57,29 +60,73 @@ const metricsMiddleware = ({ metrics, serverTiming, name }) => {
                 const label = `http-client-${ctx.config.metric}`;
                 const extensions = {};
                 Object.assign(extensions, { [status]: 1 });
+                // Determine cache state for diagnostics metrics
+                let cacheState = 'none';
                 if (ctx.cacheHit) {
                     Object.assign(extensions, ctx.cacheHit, { [`${status}-hit`]: 1 });
+                    cacheState = 'hit';
                 }
                 else if (!ctx.inflightHit && !ctx.memoizedHit) {
                     // Lets us know how many calls passed through to origin
                     Object.assign(extensions, { [`${status}-miss`]: 1 });
+                    cacheState = 'miss';
                 }
                 if (ctx.inflightHit) {
                     Object.assign(extensions, { [`${status}-inflight`]: 1 });
+                    cacheState = 'inflight';
                 }
                 if (ctx.memoizedHit) {
                     Object.assign(extensions, { [`${status}-memoized`]: 1 });
+                    cacheState = 'memoized';
                 }
-                if (ctx.config.retryCount) {
-                    const retryCount = ctx.config.retryCount;
-                    if (retryCount > 0) {
-                        extensions[`retry-${status}-${retryCount}`] = 1;
-                    }
+                const retryCount = ctx.config.retryCount || 0;
+                if (retryCount > 0) {
+                    extensions[`retry-${status}-${retryCount}`] = 1;
                 }
                 const end = status === 'success' && !ctx.cacheHit && !ctx.inflightHit && !ctx.memoizedHit
                     ? process.hrtime(start)
                     : undefined;
+                // Legacy metrics (backward compatibility)
                 metrics.batch(label, end, extensions);
+                // New diagnostics metrics with stable names and attributes
+                if (global.diagnosticsMetrics) {
+                    const elapsed = process.hrtime(start);
+                    const rawStatusCode = ((_a = ctx.response) === null || _a === void 0 ? void 0 : _a.status) || errorStatus;
+                    // Extract account from request headers, fallback to default
+                    const account = ((_b = ctx.config.headers) === null || _b === void 0 ? void 0 : _b[constants_1.ACCOUNT_HEADER]) || DEFAULT_ACCOUNT;
+                    const baseAttributes = {
+                        [constants_1.AttributeKeys.VTEX_ACCOUNT_NAME]: account,
+                        component: 'http-client',
+                        client_metric: ctx.config.metric,
+                        status_code: rawStatusCode,
+                        status,
+                    };
+                    // Record latency histogram with all context
+                    global.diagnosticsMetrics.recordLatency(elapsed, {
+                        ...baseAttributes,
+                        cache_state: cacheState,
+                    });
+                    // Increment counters for different event types (replaces extensions behavior)
+                    // Main request counter with status as attribute
+                    global.diagnosticsMetrics.incrementCounter('http_client_requests_total', 1, baseAttributes);
+                    // Cache counter with cache_state as attribute (replaces extensions like 'success-hit', 'error-miss')
+                    if (cacheState !== 'none') {
+                        global.diagnosticsMetrics.incrementCounter('http_client_cache_total', 1, {
+                            ...baseAttributes,
+                            cache_state: cacheState,
+                        });
+                    }
+                    // Retry counter (replaces 'retry-{status}-{count}' extensions)
+                    if (retryCount > 0) {
+                        global.diagnosticsMetrics.incrementCounter('http_client_requests_retried_total', 1, {
+                            ...baseAttributes,
+                            retry_count: retryCount,
+                        });
+                    }
+                }
+                else {
+                    console.warn('DiagnosticsMetrics not available. HTTP client metrics not reported.');
+                }
                 if (ctx.config.verbose) {
                     console.log(`VERBOSE: ${name}.${ctx.config.label}`, {
                         ...extensions,

package/lib/HttpClient/middlewares/request/HttpAgentSingleton.d.ts

@@ -6,6 +6,11 @@ export declare class HttpAgentSingleton {
         pendingRequests: number;
         sockets: number;
     };
+    /**
+     * Update HTTP agent statistics as diagnostics metrics (gauges).
+     * This method should be called periodically to export current HTTP agent state.
+     */
+    static updateHttpAgentMetrics(): void;
     private static httpAgent;
     private static count;
 }

package/lib/HttpClient/middlewares/request/HttpAgentSingleton.js

@@ -19,6 +19,21 @@ class HttpAgentSingleton {
             sockets,
         };
     }
+    /**
+     * Update HTTP agent statistics as diagnostics metrics (gauges).
+     * This method should be called periodically to export current HTTP agent state.
+     */
+    static updateHttpAgentMetrics() {
+        if (!global.diagnosticsMetrics) {
+            console.warn('DiagnosticsMetrics not available. HTTP agent metrics not reported.');
+            return;
+        }
+        const stats = HttpAgentSingleton.httpAgentStats();
+        // Report HTTP agent stats as gauges (current state)
+        global.diagnosticsMetrics.setGauge('http_agent_sockets_current', stats.sockets, {});
+        global.diagnosticsMetrics.setGauge('http_agent_free_sockets_current', stats.freeSockets, {});
+        global.diagnosticsMetrics.setGauge('http_agent_pending_requests_current', stats.pendingRequests, {});
+    }
     static count(obj) {
         try {
             return Object.values(obj).reduce((acc, val) => acc += val.length, 0);

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;
+}