valkey-glide 2.0.0rc2__cp312-cp312-macosx_11_0_arm64.whl → 2.2.0rc2__cp312-cp312-macosx_11_0_arm64.whl

glide/logger.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
+import traceback
 from enum import Enum
 from typing import Optional
 
-from .glide import Level as internalLevel
-from .glide import py_init, py_log
+from glide.glide import Level as internalLevel
+from glide.glide import py_init, py_log
 
 
 class Level(Enum):
@@ -20,13 +21,12 @@ class Level(Enum):
 
 class Logger:
     """
-    A singleton class that allows logging which is consistent with logs from the internal rust core.
+    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 Logger.init, which configures the logger only if it wasn't previously configured.
     2. By calling Logger.set_logger_config, which replaces the existing configuration, and means that new logs will not be
     saved with the logs that were sent before the call.
-    If set_logger_config wasn't called, the first log attempt will initialize a new logger with default configuration decided
-    by the Rust core.
+    If none of these functions are called, the first log attempt will initialize a new logger with default configuration.
     """
 
     _instance = None
@@ -38,48 +38,60 @@ class Logger:
 
     @classmethod
     def init(cls, level: Optional[Level] = None, file_name: Optional[str] = None):
-        """_summary_
+        """
         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,
+        replace an existing logger. Otherwise, use `set_logger_config` for overriding the existing logger configs.
+        The logger will filter all logs with a level lower than the given level.
+        If given a file_name argument, will write the logs to files postfixed with file_name. If file_name isn't provided,
         the logs will be written to the console.
+
         Args:
             level (Optional[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 decided by the Rust core.
-            file_name (Optional[str]):  If provided the target of the logs will be the file mentioned.
-            Otherwise, logs will be printed to the console.
-            To turn off logging completely, set the level to Level.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.
+            file_name (Optional[str]): If provided the target of the logs will be the file mentioned.
+                Otherwise, logs will be printed to the console.
         """
         if cls._instance is None:
             cls._instance = cls(level, file_name)
 
     @classmethod
-    def log(cls, log_level: Level, log_identifier: str, message: str):
-        """Logs the provided message if the provided log level is lower then the logger level.
+    def log(
+        cls,
+        log_level: Level,
+        log_identifier: str,
+        message: str,
+        err: Optional[Exception] = None,
+    ):
+        """
+        Logs the provided message if the provided log level is lower then the logger level.
 
         Args:
-            log_level (Level): The log level of the provided message
+            log_level (Level): The log level of the provided message.
             log_identifier (str): The log identifier should give the log a context.
             message (str): The message to log.
+            err (Optional[Exception]): The exception or error to log.
         """
         if not cls._instance:
             cls._instance = cls(None)
         if not log_level.value.is_lower(Logger.logger_level):
             return
+        if err:
+            message = f"{message}: {traceback.format_exception(err)}"
         py_log(log_level.value, log_identifier, message)
 
     @classmethod
     def set_logger_config(
         cls, level: Optional[Level] = None, file_name: Optional[str] = None
     ):
-        """Creates a new logger instance and configure it with the provided log level and file name.
+        """
+        Creates a new logger instance and configure it with the provided log level and file name.
 
         Args:
             level (Optional[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 decided by the Rust core.
-            file_name (Optional[str]):  If provided the target of the logs will be the file mentioned.
-            Otherwise, logs will be printed to the console.
-            To turn off logging completely, set the level to OFF.
+                If log level isn't provided, the logger will be configured with default configuration.
+                To turn off logging completely, set the level to OFF.
+            file_name (Optional[str]): If provided the target of the logs will be the file mentioned.
+                Otherwise, logs will be printed to the console.
         """
         Logger._instance = Logger(level, file_name)

glide/opentelemetry.py

@@ -0,0 +1,185 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+"""
+⚠️ 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)
+    - **sample_percentage**: (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.
+  - **flush_interval_ms**: (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
+- `flush_interval_ms` must be a positive integer.
+- `sample_percentage` 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()`.
+"""
+
+import random
+from typing import Optional
+
+from glide.glide import (
+    OpenTelemetryConfig,
+    OpenTelemetryTracesConfig,
+    init_opentelemetry,
+)
+from glide_shared.exceptions import ConfigurationError
+
+from .logger import Level, Logger
+
+
+class OpenTelemetry:
+    """
+    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:
+        ```python
+        from glide import OpenTelemetry, OpenTelemetryConfig, OpenTelemetryTracesConfig, OpenTelemetryMetricsConfig
+
+        OpenTelemetry.init(OpenTelemetryConfig(
+            traces=OpenTelemetryTracesConfig(
+                endpoint="http://localhost:4318/v1/traces",
+                sample_percentage=10  # Optional, defaults to 1. Can also be changed at runtime via set_sample_percentage().
+            ),
+            metrics=OpenTelemetryMetricsConfig(
+                endpoint="http://localhost:4318/v1/metrics"
+            ),
+            flush_interval_ms=1000  # Optional, defaults to 5000
+        ))
+        ```
+
+    Note:
+        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.
+    """
+
+    _instance: Optional["OpenTelemetry"] = None
+    _config: Optional[OpenTelemetryConfig] = None
+
+    @classmethod
+    def init(cls, config: OpenTelemetryConfig) -> None:
+        """
+        Initialize the OpenTelemetry instance.
+
+        Args:
+            config: The OpenTelemetry configuration
+
+        Note:
+            OpenTelemetry can only be initialized once per process.
+            Subsequent calls will be ignored and a warning will be logged.
+        """
+        if not cls._instance:
+            cls._config = config
+            # Initialize the underlying OpenTelemetry implementation
+            init_opentelemetry(config)
+            cls._instance = OpenTelemetry()
+            Logger.log(
+                Level.INFO,
+                "GlideOpenTelemetry",
+                "OpenTelemetry initialized successfully",
+            )
+            return
+
+        Logger.log(
+            Level.WARN,
+            "GlideOpenTelemetry",
+            "OpenTelemetry already initialized - ignoring new configuration",
+        )
+
+    @classmethod
+    def is_initialized(cls) -> bool:
+        """
+        Check if the OpenTelemetry instance is initialized.
+
+        Returns:
+            bool: True if the OpenTelemetry instance is initialized, False otherwise
+        """
+        return cls._instance is not None
+
+    @classmethod
+    def get_sample_percentage(cls) -> Optional[int]:
+        """
+        Get the sample percentage for traces.
+
+        Returns:
+            Optional[int]: The sample percentage for traces only if OpenTelemetry is initialized
+                and the traces config is set, otherwise None.
+        """
+        if cls._config:
+            traces_config = cls._config.get_traces()
+            if traces_config:
+                return traces_config.get_sample_percentage()
+        return None
+
+    @classmethod
+    def should_sample(cls) -> bool:
+        """
+        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:
+            bool: True if the request should be sampled, False otherwise
+        """
+        percentage = cls.get_sample_percentage()
+        return (
+            cls.is_initialized()
+            and percentage is not None
+            and random.random() * 100 < percentage
+        )
+
+    @classmethod
+    def set_sample_percentage(cls, percentage: int) -> None:
+        """
+        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.
+
+        Args:
+            percentage: The sample percentage 0-100
+
+        Raises:
+            ConfigurationError: 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.
+        """
+        if not cls._config or not cls._config.get_traces():
+            raise ConfigurationError("OpenTelemetry config traces not initialized")
+
+        if percentage < 0 or percentage > 100:
+            raise ConfigurationError("Sample percentage must be between 0 and 100")
+
+        # Create a new traces config with the updated sample_percentage
+        # This is necessary because the PyO3 binding doesn't properly handle direct assignment to Option<u32>
+        traces_config = cls._config.get_traces()
+        if traces_config:
+            endpoint = traces_config.get_endpoint()
+            new_traces_config = OpenTelemetryTracesConfig(
+                endpoint=endpoint, sample_percentage=percentage
+            )
+
+            # Replace the traces config
+            cls._config.set_traces(new_traces_config)

glide_shared/__init__.py

@@ -0,0 +1,330 @@
+# Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+from .commands.batch import Batch, ClusterBatch, ClusterTransaction, TBatch, Transaction
+from .commands.batch_options import (
+    BatchOptions,
+    BatchRetryStrategy,
+    ClusterBatchOptions,
+)
+from .commands.bitmap import (
+    BitEncoding,
+    BitFieldGet,
+    BitFieldIncrBy,
+    BitFieldOffset,
+    BitFieldOverflow,
+    BitFieldSet,
+    BitFieldSubCommands,
+    BitmapIndexType,
+    BitOffset,
+    BitOffsetMultiplier,
+    BitOverflowControl,
+    BitwiseOperation,
+    OffsetOptions,
+    SignedEncoding,
+    UnsignedEncoding,
+)
+from .commands.command_args import Limit, ListDirection, ObjectType, OrderBy
+from .commands.core_options import (
+    ConditionalChange,
+    ExpireOptions,
+    ExpiryGetEx,
+    ExpirySet,
+    ExpiryType,
+    ExpiryTypeGetEx,
+    FlushMode,
+    FunctionRestorePolicy,
+    HashFieldConditionalChange,
+    InfoSection,
+    InsertPosition,
+    OnlyIfEqual,
+    PubSubMsg,
+    UpdateOptions,
+)
+from .commands.server_modules import json_batch
+from .commands.server_modules.ft_options.ft_aggregate_options import (
+    FtAggregateApply,
+    FtAggregateClause,
+    FtAggregateFilter,
+    FtAggregateGroupBy,
+    FtAggregateLimit,
+    FtAggregateOptions,
+    FtAggregateReducer,
+    FtAggregateSortBy,
+    FtAggregateSortProperty,
+)
+from .commands.server_modules.ft_options.ft_create_options import (
+    DataType,
+    DistanceMetricType,
+    Field,
+    FieldType,
+    FtCreateOptions,
+    NumericField,
+    TagField,
+    TextField,
+    VectorAlgorithm,
+    VectorField,
+    VectorFieldAttributes,
+    VectorFieldAttributesFlat,
+    VectorFieldAttributesHnsw,
+    VectorType,
+)
+from .commands.server_modules.ft_options.ft_profile_options import (
+    FtProfileOptions,
+    QueryType,
+)
+from .commands.server_modules.ft_options.ft_search_options import (
+    FtSearchLimit,
+    FtSearchOptions,
+    ReturnField,
+)
+from .commands.server_modules.json_options import (
+    JsonArrIndexOptions,
+    JsonArrPopOptions,
+    JsonGetOptions,
+)
+from .commands.sorted_set import (
+    AggregationType,
+    GeoSearchByBox,
+    GeoSearchByRadius,
+    GeoSearchCount,
+    GeospatialData,
+    GeoUnit,
+    InfBound,
+    LexBoundary,
+    RangeByIndex,
+    RangeByLex,
+    RangeByScore,
+    ScoreBoundary,
+    ScoreFilter,
+)
+from .commands.stream import (
+    ExclusiveIdBound,
+    IdBound,
+    MaxId,
+    MinId,
+    StreamAddOptions,
+    StreamClaimOptions,
+    StreamGroupOptions,
+    StreamPendingOptions,
+    StreamRangeBound,
+    StreamReadGroupOptions,
+    StreamReadOptions,
+    StreamTrimOptions,
+    TrimByMaxLen,
+    TrimByMinId,
+)
+from .config import (
+    AdvancedGlideClientConfiguration,
+    AdvancedGlideClusterClientConfiguration,
+    BackoffStrategy,
+    GlideClientConfiguration,
+    GlideClusterClientConfiguration,
+    IamAuthConfig,
+    NodeAddress,
+    PeriodicChecksManualInterval,
+    PeriodicChecksStatus,
+    ProtocolVersion,
+    ReadFrom,
+    ServerCredentials,
+    ServiceType,
+    TlsAdvancedConfiguration,
+)
+from .constants import (
+    OK,
+    TOK,
+    FtAggregateResponse,
+    FtInfoResponse,
+    FtProfileResponse,
+    FtSearchResponse,
+    TClusterResponse,
+    TEncodable,
+    TFunctionListResponse,
+    TFunctionStatsFullResponse,
+    TFunctionStatsSingleNodeResponse,
+    TJsonResponse,
+    TJsonUniversalResponse,
+    TResult,
+    TSingleNodeRoute,
+    TXInfoStreamFullResponse,
+    TXInfoStreamResponse,
+)
+from .exceptions import (
+    ClosingError,
+    ConfigurationError,
+    ConnectionError,
+    ExecAbortError,
+    GlideError,
+    LoggerError,
+    RequestError,
+    TimeoutError,
+)
+from .routes import (
+    AllNodes,
+    AllPrimaries,
+    ByAddressRoute,
+    RandomNode,
+    Route,
+    SlotIdRoute,
+    SlotKeyRoute,
+    SlotType,
+)
+
+__all__ = [
+    # Client
+    "Batch",
+    "ClusterBatch",
+    "ClusterTransaction",
+    "Transaction",
+    "TBatch",
+    # Batch Options
+    "BatchOptions",
+    "BatchRetryStrategy",
+    "ClusterBatchOptions",
+    # Config
+    "AdvancedGlideClientConfiguration",
+    "AdvancedGlideClusterClientConfiguration",
+    "GlideClientConfiguration",
+    "GlideClusterClientConfiguration",
+    "BackoffStrategy",
+    "ReadFrom",
+    "ServerCredentials",
+    "ServiceType",
+    "IamAuthConfig",
+    "NodeAddress",
+    "ProtocolVersion",
+    "PeriodicChecksManualInterval",
+    "PeriodicChecksStatus",
+    "TlsAdvancedConfiguration",
+    # Response
+    "OK",
+    "TClusterResponse",
+    "TEncodable",
+    "TFunctionListResponse",
+    "TFunctionStatsFullResponse",
+    "TFunctionStatsSingleNodeResponse",
+    "TJsonResponse",
+    "TJsonUniversalResponse",
+    "TOK",
+    "TResult",
+    "TXInfoStreamFullResponse",
+    "TXInfoStreamResponse",
+    "FtAggregateResponse",
+    "FtInfoResponse",
+    "FtProfileResponse",
+    "FtSearchResponse",
+    # Commands
+    "BitEncoding",
+    "BitFieldGet",
+    "BitFieldIncrBy",
+    "BitFieldOffset",
+    "BitFieldOverflow",
+    "BitFieldSet",
+    "BitFieldSubCommands",
+    "BitmapIndexType",
+    "BitOffset",
+    "BitOffsetMultiplier",
+    "BitOverflowControl",
+    "BitwiseOperation",
+    "OffsetOptions",
+    "SignedEncoding",
+    "UnsignedEncoding",
+    "ScoreBoundary",
+    "ConditionalChange",
+    "HashFieldConditionalChange",
+    "OnlyIfEqual",
+    "ExpireOptions",
+    "ExpiryGetEx",
+    "ExpirySet",
+    "ExpiryType",
+    "ExpiryTypeGetEx",
+    "FlushMode",
+    "FunctionRestorePolicy",
+    "GeoSearchByBox",
+    "GeoSearchByRadius",
+    "GeoSearchCount",
+    "GeoUnit",
+    "GeospatialData",
+    "AggregationType",
+    "InfBound",
+    "InfoSection",
+    "InsertPosition",
+    "LexBoundary",
+    "Limit",
+    "ListDirection",
+    "RangeByIndex",
+    "RangeByLex",
+    "RangeByScore",
+    "ScoreFilter",
+    "ObjectType",
+    "OrderBy",
+    "ExclusiveIdBound",
+    "IdBound",
+    "MaxId",
+    "MinId",
+    "StreamAddOptions",
+    "StreamClaimOptions",
+    "StreamGroupOptions",
+    "StreamPendingOptions",
+    "StreamReadGroupOptions",
+    "StreamRangeBound",
+    "StreamReadOptions",
+    "StreamTrimOptions",
+    "TrimByMaxLen",
+    "TrimByMinId",
+    "UpdateOptions",
+    # PubSub
+    "PubSubMsg",
+    # Json
+    "json_batch",
+    "JsonGetOptions",
+    "JsonArrIndexOptions",
+    "JsonArrPopOptions",
+    # Routes
+    "Route",
+    "SlotType",
+    "AllNodes",
+    "AllPrimaries",
+    "ByAddressRoute",
+    "RandomNode",
+    "SlotKeyRoute",
+    "SlotIdRoute",
+    "TSingleNodeRoute",
+    # Exceptions
+    "ClosingError",
+    "ConfigurationError",
+    "ConnectionError",
+    "ExecAbortError",
+    "GlideError",
+    "RequestError",
+    "TimeoutError",
+    "LoggerError",
+    # Ft
+    "DataType",
+    "DistanceMetricType",
+    "Field",
+    "FieldType",
+    "FtCreateOptions",
+    "NumericField",
+    "TagField",
+    "TextField",
+    "VectorAlgorithm",
+    "VectorField",
+    "VectorFieldAttributes",
+    "VectorFieldAttributesFlat",
+    "VectorFieldAttributesHnsw",
+    "VectorType",
+    "FtSearchLimit",
+    "ReturnField",
+    "FtSearchOptions",
+    "FtAggregateApply",
+    "FtAggregateFilter",
+    "FtAggregateClause",
+    "FtAggregateLimit",
+    "FtAggregateOptions",
+    "FtAggregateGroupBy",
+    "FtAggregateReducer",
+    "FtAggregateSortBy",
+    "FtAggregateSortProperty",
+    "FtProfileOptions",
+    "QueryType",
+]