vectra-client 0.1.2 → 0.2.0

data/lib/vectra/instrumentation.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Instrumentation and observability hooks
+  #
+  # Provides hooks for monitoring tools like New Relic, Datadog, and custom loggers.
+  # Records metrics for all vector operations including duration, result counts, and errors.
+  #
+  # @example Enable instrumentation
+  #   Vectra.configure do |config|
+  #     config.instrumentation = true
+  #   end
+  #
+  # @example Custom instrumentation handler
+  #   Vectra.on_operation do |event|
+  #     puts "#{event.operation} took #{event.duration}ms"
+  #   end
+  #
+  module Instrumentation
+    # Event object passed to instrumentation handlers
+    #
+    # @attr_reader [Symbol] operation The operation type (:upsert, :query, :fetch, etc.)
+    # @attr_reader [Symbol] provider The provider name (:pinecone, :pgvector, etc.)
+    # @attr_reader [String] index The index/table name
+    # @attr_reader [Float] duration Duration in milliseconds
+    # @attr_reader [Hash] metadata Additional operation metadata
+    # @attr_reader [Exception, nil] error Exception if operation failed
+    class Event
+      attr_reader :operation, :provider, :index, :duration, :metadata, :error
+
+      def initialize(operation:, provider:, index:, duration:, metadata: {}, error: nil)
+        @operation = operation
+        @provider = provider
+        @index = index
+        @duration = duration
+        @metadata = metadata
+        @error = error
+      end
+
+      # Check if operation succeeded
+      #
+      # @return [Boolean]
+      def success?
+        error.nil?
+      end
+
+      # Check if operation failed
+      #
+      # @return [Boolean]
+      def failure?
+        !success?
+      end
+    end
+
+    class << self
+      # Register an instrumentation handler
+      #
+      # The block will be called for every vector operation with an Event object.
+      #
+      # @yield [event] The instrumentation event
+      # @yieldparam event [Event] Event details
+      #
+      # @example
+      #   Vectra::Instrumentation.on_operation do |event|
+      #     StatsD.timing("vectra.#{event.operation}", event.duration)
+      #     StatsD.increment("vectra.#{event.operation}.#{event.success? ? 'success' : 'error'}")
+      #   end
+      #
+      def on_operation(&block)
+        handlers << block
+      end
+
+      # Instrument a vector operation
+      #
+      # @param operation [Symbol] Operation name
+      # @param provider [Symbol] Provider name
+      # @param index [String] Index name
+      # @param metadata [Hash] Additional metadata
+      # @yield The operation to instrument
+      # @return [Object] The result of the block
+      #
+      # @api private
+      def instrument(operation:, provider:, index:, metadata: {})
+        return yield unless enabled?
+
+        start_time = Time.now
+        error = nil
+        result = nil
+
+        begin
+          result = yield
+        rescue StandardError => e
+          error = e
+          raise
+        ensure
+          duration = ((Time.now - start_time) * 1000).round(2)
+
+          event = Event.new(
+            operation: operation,
+            provider: provider,
+            index: index,
+            duration: duration,
+            metadata: metadata,
+            error: error
+          )
+
+          notify_handlers(event)
+        end
+
+        result
+      end
+
+      # Check if instrumentation is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        Vectra.configuration.instrumentation
+      end
+
+      # Clear all handlers (useful for testing)
+      #
+      # @api private
+      def clear_handlers!
+        @handlers = []
+      end
+
+      private
+
+      def handlers
+        @handlers ||= []
+      end
+
+      def notify_handlers(event)
+        handlers.each do |handler|
+          handler.call(event)
+        rescue StandardError => e
+          # Don't let instrumentation errors crash the app
+          warn "Vectra instrumentation handler error: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/vectra/providers/pgvector/connection.rb

@@ -5,6 +5,8 @@ module Vectra
     class Pgvector < Base
       # Connection management for pgvector provider
       module Connection
+        include Vectra::Retry
+
         private
 
         # Get or create database connection
@@ -49,7 +51,9 @@ module Vectra
         # Execute SQL with parameters
         def execute(sql, params = [])
           log_debug("Executing SQL", { sql: sql, params: params })
-          connection.exec_params(sql, params)
+          with_retry do
+            connection.exec_params(sql, params)
+          end
         rescue PG::Error => e
           handle_pg_error(e)
         end

data/lib/vectra/retry.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "connection_pool"
+
+module Vectra
+  # Retry helper for transient errors
+  #
+  # Provides exponential backoff retry logic for database operations.
+  #
+  # @example
+  #   include Vectra::Retry
+  #
+  #   with_retry(max_attempts: 3) do
+  #     connection.exec_params(sql, params)
+  #   end
+  #
+  module Retry
+    # Errors that should be retried
+    RETRYABLE_PG_ERRORS = [
+      "PG::ConnectionBad",
+      "PG::UnableToSend",
+      "PG::AdminShutdown",
+      "PG::CrashShutdown",
+      "PG::CannotConnectNow",
+      "PG::TooManyConnections",
+      "PG::SerializationFailure",
+      "PG::DeadlockDetected"
+    ].freeze
+
+    # Execute block with retry logic
+    #
+    # @param max_attempts [Integer] Maximum number of attempts (default: from config)
+    # @param base_delay [Float] Initial delay in seconds (default: from config)
+    # @param max_delay [Float] Maximum delay in seconds (default: 30)
+    # @param backoff_factor [Float] Multiplier for each retry (default: 2)
+    # @param jitter [Boolean] Add randomness to delay (default: true)
+    # @yield The block to execute with retry logic
+    # @return [Object] The result of the block
+    #
+    # @example
+    #   result = with_retry(max_attempts: 5) do
+    #     perform_database_operation
+    #   end
+    #
+    def with_retry(max_attempts: nil, base_delay: nil, max_delay: 30, backoff_factor: 2, jitter: true, &block)
+      max_attempts ||= config.max_retries
+      base_delay ||= config.retry_delay
+
+      attempt = 0
+      last_error = nil
+
+      loop do
+        attempt += 1
+
+        begin
+          return block.call
+        rescue StandardError => e
+          last_error = e
+
+          # Don't retry if not retryable or out of attempts
+          should_retry = retryable_error?(e) && attempt < max_attempts
+
+          unless should_retry
+            log_error("Operation failed after #{attempt} attempts", e)
+            raise
+          end
+
+          # Calculate delay with exponential backoff
+          delay = calculate_delay(
+            attempt: attempt,
+            base_delay: base_delay,
+            max_delay: max_delay,
+            backoff_factor: backoff_factor,
+            jitter: jitter
+          )
+
+          log_retry(attempt, max_attempts, delay, e)
+          sleep(delay)
+        end
+      end
+    end
+
+    private
+
+    # Check if error should be retried
+    #
+    # @param error [Exception] The error to check
+    # @return [Boolean]
+    def retryable_error?(error)
+      error_class = error.class.name
+
+      # Check if it's a retryable PG error
+      return true if RETRYABLE_PG_ERRORS.include?(error_class)
+
+      # Check if it's a connection pool timeout
+      return true if error.instance_of?(::ConnectionPool::TimeoutError)
+
+      # Check message for specific patterns
+      error_message = error.message.downcase
+      error_message.include?("timeout") ||
+        error_message.include?("connection") ||
+        error_message.include?("temporary")
+    end
+
+    # Calculate exponential backoff delay
+    #
+    # @param attempt [Integer] Current attempt number
+    # @param base_delay [Float] Base delay in seconds
+    # @param max_delay [Float] Maximum delay in seconds
+    # @param backoff_factor [Float] Multiplier for each retry
+    # @param jitter [Boolean] Add randomness
+    # @return [Float] Delay in seconds
+    def calculate_delay(attempt:, base_delay:, max_delay:, backoff_factor:, jitter:)
+      # Exponential backoff: base_delay * (backoff_factor ^ (attempt - 1))
+      delay = base_delay * (backoff_factor**(attempt - 1))
+
+      # Cap at max_delay
+      delay = [delay, max_delay].min
+
+      # Add jitter (±25% randomness)
+      if jitter
+        jitter_amount = delay * 0.25
+        delay += rand(-jitter_amount..jitter_amount)
+      end
+
+      delay.clamp(base_delay, max_delay)
+    end
+
+    # Log retry attempt
+    #
+    # @param attempt [Integer] Current attempt
+    # @param max_attempts [Integer] Maximum attempts
+    # @param delay [Float] Delay before next attempt
+    # @param error [Exception] The error that triggered retry
+    def log_retry(attempt, max_attempts, delay, error)
+      return unless config.logger
+
+      config.logger.warn(
+        "[Vectra] Retry attempt #{attempt}/#{max_attempts} after error: " \
+        "#{error.class} - #{error.message}. Waiting #{delay.round(2)}s..."
+      )
+    end
+
+    # Log final error
+    #
+    # @param message [String] Error message
+    # @param error [Exception] The error
+    def log_error(message, error)
+      return unless config.logger
+
+      config.logger.error(
+        "[Vectra] #{message}: #{error.class} - #{error.message}"
+      )
+    end
+  end
+end

data/lib/vectra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectra
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/vectra.rb

@@ -5,6 +5,9 @@ require_relative "vectra/errors"
 require_relative "vectra/configuration"
 require_relative "vectra/vector"
 require_relative "vectra/query_result"
+require_relative "vectra/instrumentation"
+require_relative "vectra/retry"
+require_relative "vectra/active_record"
 require_relative "vectra/providers/base"
 require_relative "vectra/providers/pinecone"
 require_relative "vectra/providers/qdrant"
@@ -53,6 +56,14 @@ require_relative "vectra/client"
 #
 module Vectra
   class << self
+    # Register an instrumentation handler
+    #
+    # @yield [event] The instrumentation event
+    # @see Instrumentation.on_operation
+    def on_operation(&)
+      Instrumentation.on_operation(&)
+    end
+
     # Create a new client with the given options
     #
     # @param options [Hash] client options

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Mijo Kristo
@@ -37,6 +37,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -179,14 +207,29 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
+- IMPLEMENTATION_GUIDE.md
 - LICENSE
+- NEW_FEATURES_v0.2.0.md
 - README.md
+- RELEASE_CHECKLIST_v0.2.0.md
 - Rakefile
 - SECURITY.md
+- USAGE_EXAMPLES.md
+- benchmarks/batch_operations_benchmark.rb
+- benchmarks/connection_pooling_benchmark.rb
+- examples/active_record_demo.rb
+- examples/instrumentation_demo.rb
+- lib/generators/vectra/install_generator.rb
+- lib/generators/vectra/templates/enable_pgvector_extension.rb
+- lib/generators/vectra/templates/vectra.rb
 - lib/vectra.rb
+- lib/vectra/active_record.rb
 - lib/vectra/client.rb
 - lib/vectra/configuration.rb
 - lib/vectra/errors.rb
+- lib/vectra/instrumentation.rb
+- lib/vectra/instrumentation/datadog.rb
+- lib/vectra/instrumentation/new_relic.rb
 - lib/vectra/providers/base.rb
 - lib/vectra/providers/pgvector.rb
 - lib/vectra/providers/pgvector/connection.rb
@@ -196,6 +239,7 @@ files:
 - lib/vectra/providers/qdrant.rb
 - lib/vectra/providers/weaviate.rb
 - lib/vectra/query_result.rb
+- lib/vectra/retry.rb
 - lib/vectra/vector.rb
 - lib/vectra/version.rb
 homepage: https://github.com/stokry/vectra