speedkey 0.1.0

package/build-ts/Logger.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+export type LevelOptions = "error" | "warn" | "info" | "debug" | "trace" | "off";
+/**
+ * A singleton class that allows logging which is consistent with logs from the internal GLIDE core.
+ * The logger can be set up in 2 ways -
+ *   1. By calling {@link init}, which configures the logger only if it wasn't previously configured.
+ *   2. By calling {@link setLoggerConfig}, which replaces the existing configuration, and means that new logs
+ *     will not be saved with the logs that were sent before the call. The previous logs will remain unchanged.
+ * If none of these functions are called, the first log attempt will initialize a new logger with default configuration.
+ */
+export declare class Logger {
+    private static _instance;
+    private static logger_level;
+    private constructor();
+    /**
+     * Logs the provided message if the provided log level is lower then the logger level.
+     *
+     * @param logLevel - The log level of the provided message.
+     * @param logIdentifier - The log identifier should give the log a context.
+     * @param message - The message to log.
+     * @param err - The exception or error to log.
+     */
+    static log(logLevel: LevelOptions, logIdentifier: string, message: string, err?: Error): void;
+    /**
+     * Initialize a logger if it wasn't initialized before - this method is meant to be used when there is no intention to
+     * replace an existing logger.
+     * The logger will filter all logs with a level lower than the given level.
+     * If given a fileName argument, will write the logs to files postfixed with fileName. If fileName isn't provided,
+     * the logs will be written to the console.
+     *
+     * @param level - Set the logger level to one of [ERROR, WARN, INFO, DEBUG, TRACE, OFF].
+     *   If log level isn't provided, the logger will be configured with default configuration.
+     *   To turn off logging completely, set the level to level "off".
+     * @param fileName - If provided the target of the logs will be the file mentioned.
+     *   Otherwise, logs will be printed to the console.
+     */
+    static init(level?: LevelOptions, fileName?: string): void;
+    /**
+     * Creates a new logger instance and configure it with the provided log level and file name.
+     *
+     * @param level - Set the logger level to one of [ERROR, WARN, INFO, DEBUG, TRACE, OFF].
+     * @param fileName - The target of the logs will be the file mentioned.
+     */
+    static setLoggerConfig(level: LevelOptions, fileName?: string): void;
+}

package/build-ts/Logger.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const _1 = require(".");
+const LEVEL = new Map([
+    ["error", 0 /* Level.Error */],
+    ["warn", 1 /* Level.Warn */],
+    ["info", 2 /* Level.Info */],
+    ["debug", 3 /* Level.Debug */],
+    ["trace", 4 /* Level.Trace */],
+    ["off", 5 /* Level.Off */],
+    [undefined, undefined],
+]);
+/**
+ * A singleton class that allows logging which is consistent with logs from the internal GLIDE core.
+ * The logger can be set up in 2 ways -
+ *   1. By calling {@link init}, which configures the logger only if it wasn't previously configured.
+ *   2. By calling {@link setLoggerConfig}, which replaces the existing configuration, and means that new logs
+ *     will not be saved with the logs that were sent before the call. The previous logs will remain unchanged.
+ * If none of these functions are called, the first log attempt will initialize a new logger with default configuration.
+ */
+class Logger {
+    static _instance;
+    static logger_level = 0;
+    constructor(level, fileName) {
+        Logger.logger_level = (0, _1.InitInternalLogger)(LEVEL.get(level), fileName);
+    }
+    /**
+     * Logs the provided message if the provided log level is lower then the logger level.
+     *
+     * @param logLevel - The log level of the provided message.
+     * @param logIdentifier - The log identifier should give the log a context.
+     * @param message - The message to log.
+     * @param err - The exception or error to log.
+     */
+    static log(logLevel, logIdentifier, message, err) {
+        if (!Logger._instance) {
+            new Logger();
+        }
+        if (err) {
+            message += `: ${err.stack}`;
+        }
+        const level = LEVEL.get(logLevel) || 0;
+        if (!(level <= Logger.logger_level))
+            return;
+        (0, _1.log)(level, logIdentifier, message);
+    }
+    /**
+     * Initialize a logger if it wasn't initialized before - this method is meant to be used when there is no intention to
+     * replace an existing logger.
+     * The logger will filter all logs with a level lower than the given level.
+     * If given a fileName argument, will write the logs to files postfixed with fileName. If fileName isn't provided,
+     * the logs will be written to the console.
+     *
+     * @param level - Set the logger level to one of [ERROR, WARN, INFO, DEBUG, TRACE, OFF].
+     *   If log level isn't provided, the logger will be configured with default configuration.
+     *   To turn off logging completely, set the level to level "off".
+     * @param fileName - If provided the target of the logs will be the file mentioned.
+     *   Otherwise, logs will be printed to the console.
+     */
+    static init(level, fileName) {
+        if (!this._instance) {
+            this._instance = new this(level, fileName);
+        }
+    }
+    /**
+     * Creates a new logger instance and configure it with the provided log level and file name.
+     *
+     * @param level - Set the logger level to one of [ERROR, WARN, INFO, DEBUG, TRACE, OFF].
+     * @param fileName - The target of the logs will be the file mentioned.
+     */
+    static setLoggerConfig(level, fileName) {
+        this._instance = new this(level, fileName);
+    }
+}
+exports.Logger = Logger;

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;