@valkey/valkey-glide 1.3.5-rc9 → 2.0.0-rc7

package/build-ts/OpenTelemetry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+import { OpenTelemetryConfig } from ".";
+/**
+ * ⚠️ OpenTelemetry can only be initialized once per process. Calling `OpenTelemetry.init()` more than once will be ignored.
+ * If you need to change configuration, restart the process with new settings.
+ * ### OpenTelemetry
+ *
+ * - **openTelemetryConfig**: Use this object to configure OpenTelemetry exporters and options.
+ *   - **traces**: (optional) Configure trace exporting.
+ *     - **endpoint**: The collector endpoint for traces. Supported protocols:
+ *       - `http://` or `https://` for HTTP/HTTPS
+ *       - `grpc://` for gRPC
+ *       - `file://` for local file export (see below)
+ *     - **samplePercentage**: (optional) The percentage of requests to sample and create a span for, used to measure command duration. Must be between 0 and 100. Defaults to 1 if not specified.
+ *       Note: There is a tradeoff between sampling percentage and performance. Higher sampling percentages will provide more detailed telemetry data but will impact performance.
+ *       It is recommended to keep this number low (1-5%) in production environments unless you have specific needs for higher sampling rates.
+ *   - **metrics**: (optional) Configure metrics exporting.
+ *     - **endpoint**: The collector endpoint for metrics. Same protocol rules as above.
+ *   - **flushIntervalMs**: (optional) Interval in milliseconds for flushing data to the collector. Must be a positive integer. Defaults to 5000ms if not specified.
+ *
+ * #### File Exporter Details
+ * - For `file://` endpoints:
+ *   - The path must start with `file://` (e.g., `file:///tmp/otel` or `file:///tmp/otel/traces.json`).
+ *   - If the path is a directory or lacks a file extension, data is written to `signals.json` in that directory.
+ *   - If the path includes a filename with an extension, that file is used as-is.
+ *   - The parent directory must already exist; otherwise, initialization will fail with an InvalidInput error.
+ *   - If the target file exists, new data is appended (not overwritten).
+ *
+ * #### Validation Rules
+ * - `flushIntervalMs` must be a positive integer.
+ * - `samplePercentage` must be between 0 and 100.
+ * - File exporter paths must start with `file://` and have an existing parent directory.
+ * - Invalid configuration will throw an error synchronously when calling `OpenTelemetry.init()`.
+ */
+export declare class OpenTelemetry {
+    private static _instance;
+    private static openTelemetryConfig;
+    /**
+     * Singleton class for managing OpenTelemetry configuration and operations.
+     * This class provides a centralized way to initialize OpenTelemetry and control
+     * sampling behavior at runtime.
+     *
+     * Example usage:
+     * ```typescript
+     * import { OpenTelemetry, OpenTelemetryConfig, OpenTelemetryTracesConfig, OpenTelemetryMetricsConfig } from "@valkey/valkey-glide";
+     *
+     * let tracesConfig: OpenTelemetryTracesConfig = {
+     *  endpoint: "http://localhost:4318/v1/traces",
+     *  samplePercentage: 10, // Optional, defaults to 1. Can also be changed at runtime via setSamplePercentage().
+     * };
+     * let metricsConfig: OpenTelemetryMetricsConfig = {
+     *  endpoint: "http://localhost:4318/v1/metrics",
+     * };
+
+     * let config : OpenTelemetryConfig = {
+     *  traces: tracesConfig,
+     *  metrics: metricsConfig,
+     *  flushIntervalMs: 1000, // Optional, defaults to 5000
+     * };
+     * OpenTelemetry.init(config);
+     *
+     * ```
+     *
+     * @remarks
+     *   OpenTelemetry can only be initialized once per process. Subsequent calls to
+     *   init() will be ignored. This is by design, as OpenTelemetry is a global
+     *   resource that should be configured once at application startup.
+     *
+     * Initialize the OpenTelemetry instance
+     * @param openTelemetryConfig - The OpenTelemetry configuration
+     */
+    static init(openTelemetryConfig: OpenTelemetryConfig): void;
+    private static internalInit;
+    /**
+     * Check if the OpenTelemetry instance is initialized
+     * @returns True if the OpenTelemetry instance is initialized, false otherwise
+     */
+    static isInitialized(): boolean;
+    /**
+     * Get the sample percentage for traces
+     * @returns The sample percentage for traces only if OpenTelemetry is initialized and the traces config is set, otherwise undefined.
+     */
+    static getSamplePercentage(): number | undefined;
+    /**
+     * Determines if the current request should be sampled for OpenTelemetry tracing.
+     * Uses the configured sample percentage to randomly decide whether to create a span for this request.
+     * @returns true if the request should be sampled, false otherwise
+     */
+    static shouldSample(): boolean;
+    /**
+     * Set the percentage of requests to be sampled and traced. Must be a value between 0 and 100.
+     * This setting only affects traces, not metrics.
+     * @param percentage - The sample percentage 0-100
+     * @throws Error if OpenTelemetry is not initialized or traces config is not set
+     * @remarks
+     * This method can be called at runtime to change the sampling percentage without reinitializing OpenTelemetry.
+     */
+    static setSamplePercentage(percentage: number): void;
+}

package/build-ts/OpenTelemetry.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenTelemetry = void 0;
+const _1 = require(".");
+/**
+ * ⚠️ OpenTelemetry can only be initialized once per process. Calling `OpenTelemetry.init()` more than once will be ignored.
+ * If you need to change configuration, restart the process with new settings.
+ * ### OpenTelemetry
+ *
+ * - **openTelemetryConfig**: Use this object to configure OpenTelemetry exporters and options.
+ *   - **traces**: (optional) Configure trace exporting.
+ *     - **endpoint**: The collector endpoint for traces. Supported protocols:
+ *       - `http://` or `https://` for HTTP/HTTPS
+ *       - `grpc://` for gRPC
+ *       - `file://` for local file export (see below)
+ *     - **samplePercentage**: (optional) The percentage of requests to sample and create a span for, used to measure command duration. Must be between 0 and 100. Defaults to 1 if not specified.
+ *       Note: There is a tradeoff between sampling percentage and performance. Higher sampling percentages will provide more detailed telemetry data but will impact performance.
+ *       It is recommended to keep this number low (1-5%) in production environments unless you have specific needs for higher sampling rates.
+ *   - **metrics**: (optional) Configure metrics exporting.
+ *     - **endpoint**: The collector endpoint for metrics. Same protocol rules as above.
+ *   - **flushIntervalMs**: (optional) Interval in milliseconds for flushing data to the collector. Must be a positive integer. Defaults to 5000ms if not specified.
+ *
+ * #### File Exporter Details
+ * - For `file://` endpoints:
+ *   - The path must start with `file://` (e.g., `file:///tmp/otel` or `file:///tmp/otel/traces.json`).
+ *   - If the path is a directory or lacks a file extension, data is written to `signals.json` in that directory.
+ *   - If the path includes a filename with an extension, that file is used as-is.
+ *   - The parent directory must already exist; otherwise, initialization will fail with an InvalidInput error.
+ *   - If the target file exists, new data is appended (not overwritten).
+ *
+ * #### Validation Rules
+ * - `flushIntervalMs` must be a positive integer.
+ * - `samplePercentage` must be between 0 and 100.
+ * - File exporter paths must start with `file://` and have an existing parent directory.
+ * - Invalid configuration will throw an error synchronously when calling `OpenTelemetry.init()`.
+ */
+class OpenTelemetry {
+    static _instance = null;
+    static openTelemetryConfig = null;
+    /**
+     * Singleton class for managing OpenTelemetry configuration and operations.
+     * This class provides a centralized way to initialize OpenTelemetry and control
+     * sampling behavior at runtime.
+     *
+     * Example usage:
+     * ```typescript
+     * import { OpenTelemetry, OpenTelemetryConfig, OpenTelemetryTracesConfig, OpenTelemetryMetricsConfig } from "@valkey/valkey-glide";
+     *
+     * let tracesConfig: OpenTelemetryTracesConfig = {
+     *  endpoint: "http://localhost:4318/v1/traces",
+     *  samplePercentage: 10, // Optional, defaults to 1. Can also be changed at runtime via setSamplePercentage().
+     * };
+     * let metricsConfig: OpenTelemetryMetricsConfig = {
+     *  endpoint: "http://localhost:4318/v1/metrics",
+     * };
+
+     * let config : OpenTelemetryConfig = {
+     *  traces: tracesConfig,
+     *  metrics: metricsConfig,
+     *  flushIntervalMs: 1000, // Optional, defaults to 5000
+     * };
+     * OpenTelemetry.init(config);
+     *
+     * ```
+     *
+     * @remarks
+     *   OpenTelemetry can only be initialized once per process. Subsequent calls to
+     *   init() will be ignored. This is by design, as OpenTelemetry is a global
+     *   resource that should be configured once at application startup.
+     *
+     * Initialize the OpenTelemetry instance
+     * @param openTelemetryConfig - The OpenTelemetry configuration
+     */
+    static init(openTelemetryConfig) {
+        if (!this._instance) {
+            this.internalInit(openTelemetryConfig);
+            _1.Logger.log("info", "GlideOpenTelemetry", "OpenTelemetry initialized with config: " +
+                JSON.stringify(openTelemetryConfig));
+            return;
+        }
+        _1.Logger.log("warn", "GlideOpenTelemetry", "OpenTelemetry already initialized - ignoring new configuration");
+    }
+    static internalInit(openTelemetryConfig) {
+        this.openTelemetryConfig = openTelemetryConfig;
+        (0, _1.InitOpenTelemetry)(openTelemetryConfig);
+        this._instance = new OpenTelemetry();
+    }
+    /**
+     * Check if the OpenTelemetry instance is initialized
+     * @returns True if the OpenTelemetry instance is initialized, false otherwise
+     */
+    static isInitialized() {
+        return this._instance != null;
+    }
+    /**
+     * Get the sample percentage for traces
+     * @returns The sample percentage for traces only if OpenTelemetry is initialized and the traces config is set, otherwise undefined.
+     */
+    static getSamplePercentage() {
+        return this.openTelemetryConfig?.traces?.samplePercentage;
+    }
+    /**
+     * Determines if the current request should be sampled for OpenTelemetry tracing.
+     * Uses the configured sample percentage to randomly decide whether to create a span for this request.
+     * @returns true if the request should be sampled, false otherwise
+     */
+    static shouldSample() {
+        const percentage = this.getSamplePercentage();
+        return (this.isInitialized() &&
+            percentage !== undefined &&
+            Math.random() * 100 < percentage);
+    }
+    /**
+     * Set the percentage of requests to be sampled and traced. Must be a value between 0 and 100.
+     * This setting only affects traces, not metrics.
+     * @param percentage - The sample percentage 0-100
+     * @throws Error if OpenTelemetry is not initialized or traces config is not set
+     * @remarks
+     * This method can be called at runtime to change the sampling percentage without reinitializing OpenTelemetry.
+     */
+    static setSamplePercentage(percentage) {
+        if (!this.openTelemetryConfig || !this.openTelemetryConfig.traces) {
+            throw new _1.ConfigurationError("OpenTelemetry config traces not initialized");
+        }
+        if (percentage < 0 || percentage > 100) {
+            throw new _1.ConfigurationError("Sample percentage must be between 0 and 100");
+        }
+        this.openTelemetryConfig.traces.samplePercentage = percentage;
+    }
+}
+exports.OpenTelemetry = OpenTelemetry;

package/build-ts/ProtobufMessage.d.ts

@@ -1353,6 +1353,9 @@ export namespace command_request {
 
         /** CommandRequest route */
         route?: (command_request.IRoutes|null);
+
+        /** CommandRequest rootSpanPtr */
+        rootSpanPtr?: (number|Long|null);
     }
 
     /** Represents a CommandRequest. */
@@ -1388,9 +1391,15 @@ export namespace command_request {
         /** CommandRequest route. */
         public route?: (command_request.IRoutes|null);
 
+        /** CommandRequest rootSpanPtr. */
+        public rootSpanPtr?: (number|Long|null);
+
         /** CommandRequest command. */
         public command?: ("singleCommand"|"batch"|"scriptInvocation"|"scriptInvocationPointers"|"clusterScan"|"updateConnectionPassword");
 
+        /** CommandRequest _rootSpanPtr. */
+        public _rootSpanPtr?: "rootSpanPtr";
+
         /**
          * Creates a new CommandRequest instance using the specified properties.
          * @param [properties] Properties to set
@@ -1894,84 +1903,6 @@ export namespace connection_request {
         public static getTypeUrl(typeUrlPrefix?: string): string;
     }
 
-    /** Properties of an OpenTelemetryConfig. */
-    interface IOpenTelemetryConfig {
-
-        /** OpenTelemetryConfig collectorEndPoint */
-        collectorEndPoint?: (string|null);
-
-        /** OpenTelemetryConfig spanFlushInterval */
-        spanFlushInterval?: (number|Long|null);
-    }
-
-    /** Represents an OpenTelemetryConfig. */
-    class OpenTelemetryConfig implements IOpenTelemetryConfig {
-
-        /**
-         * Constructs a new OpenTelemetryConfig.
-         * @param [properties] Properties to set
-         */
-        constructor(properties?: connection_request.IOpenTelemetryConfig);
-
-        /** OpenTelemetryConfig collectorEndPoint. */
-        public collectorEndPoint: string;
-
-        /** OpenTelemetryConfig spanFlushInterval. */
-        public spanFlushInterval?: (number|Long|null);
-
-        /** OpenTelemetryConfig _spanFlushInterval. */
-        public _spanFlushInterval?: "spanFlushInterval";
-
-        /**
-         * Creates a new OpenTelemetryConfig instance using the specified properties.
-         * @param [properties] Properties to set
-         * @returns OpenTelemetryConfig instance
-         */
-        public static create(properties?: connection_request.IOpenTelemetryConfig): connection_request.OpenTelemetryConfig;
-
-        /**
-         * Encodes the specified OpenTelemetryConfig message. Does not implicitly {@link connection_request.OpenTelemetryConfig.verify|verify} messages.
-         * @param message OpenTelemetryConfig message or plain object to encode
-         * @param [writer] Writer to encode to
-         * @returns Writer
-         */
-        public static encode(message: connection_request.IOpenTelemetryConfig, writer?: $protobuf.Writer): $protobuf.Writer;
-
-        /**
-         * Encodes the specified OpenTelemetryConfig message, length delimited. Does not implicitly {@link connection_request.OpenTelemetryConfig.verify|verify} messages.
-         * @param message OpenTelemetryConfig message or plain object to encode
-         * @param [writer] Writer to encode to
-         * @returns Writer
-         */
-        public static encodeDelimited(message: connection_request.IOpenTelemetryConfig, writer?: $protobuf.Writer): $protobuf.Writer;
-
-        /**
-         * Decodes an OpenTelemetryConfig message from the specified reader or buffer.
-         * @param reader Reader or buffer to decode from
-         * @param [length] Message length if known beforehand
-         * @returns OpenTelemetryConfig
-         * @throws {Error} If the payload is not a reader or valid buffer
-         * @throws {$protobuf.util.ProtocolError} If required fields are missing
-         */
-        public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): connection_request.OpenTelemetryConfig;
-
-        /**
-         * Decodes an OpenTelemetryConfig message from the specified reader or buffer, length delimited.
-         * @param reader Reader or buffer to decode from
-         * @returns OpenTelemetryConfig
-         * @throws {Error} If the payload is not a reader or valid buffer
-         * @throws {$protobuf.util.ProtocolError} If required fields are missing
-         */
-        public static decodeDelimited(reader: ($protobuf.Reader|Uint8Array)): connection_request.OpenTelemetryConfig;
-
-        /**
-         * Gets the default type url for OpenTelemetryConfig
-         * @param [typeUrlPrefix] your custom typeUrlPrefix(default "type.googleapis.com")
-         * @returns The default type url
-         */
-        public static getTypeUrl(typeUrlPrefix?: string): string;
-    }
-
     /** Properties of a ConnectionRequest. */
     interface IConnectionRequest {
 
@@ -2023,8 +1954,8 @@ export namespace connection_request {
         /** ConnectionRequest connectionTimeout */
         connectionTimeout?: (number|null);
 
-        /** ConnectionRequest opentelemetryConfig */
-        opentelemetryConfig?: (connection_request.IOpenTelemetryConfig|null);
+        /** ConnectionRequest lazyConnect */
+        lazyConnect?: (boolean|null);
     }
 
     /** Represents a ConnectionRequest. */
@@ -2084,8 +2015,8 @@ export namespace connection_request {
         /** ConnectionRequest connectionTimeout. */
         public connectionTimeout: number;
 
-        /** ConnectionRequest opentelemetryConfig. */
-        public opentelemetryConfig?: (connection_request.IOpenTelemetryConfig|null);
+        /** ConnectionRequest lazyConnect. */
+        public lazyConnect: boolean;
 
         /** ConnectionRequest periodicChecks. */
         public periodicChecks?: ("periodicChecksManualInterval"|"periodicChecksDisabled");
@@ -2337,6 +2268,9 @@ export namespace response {
 
         /** Response isPush */
         isPush?: (boolean|null);
+
+        /** Response rootSpanPtr */
+        rootSpanPtr?: (number|Long|null);
     }
 
     /** Represents a Response. */
@@ -2366,9 +2300,15 @@ export namespace response {
         /** Response isPush. */
         public isPush: boolean;
 
+        /** Response rootSpanPtr. */
+        public rootSpanPtr?: (number|Long|null);
+
         /** Response value. */
         public value?: ("respPointer"|"constantResponse"|"requestError"|"closingError");
 
+        /** Response _rootSpanPtr. */
+        public _rootSpanPtr?: "rootSpanPtr";
+
         /**
          * Creates a new Response instance using the specified properties.
          * @param [properties] Properties to set