redis_queued_locks 1.4.0 → 1.6.0

data/lib/redis_queued_locks/client.rb

@@ -23,6 +23,12 @@ class RedisQueuedLocks::Client
     setting :dead_request_ttl, (1 * 24 * 60 * 60 * 1000) # NOTE: 1 day in milliseconds
     setting :is_timed_by_default, false
     setting :default_conflict_strategy, :wait_for_lock
+    setting :log_sampling_enabled, false
+    setting :log_sampling_percent, 15
+    setting :log_sampler, RedisQueuedLocks::Logging::Sampler
+    setting :instr_sampling_enabled, false
+    setting :instr_sampling_percent, 15
+    setting :instr_sampler, RedisQueuedLocks::Instrument::Sampler
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
@@ -37,6 +43,12 @@ class RedisQueuedLocks::Client
     validate('log_lock_try', :boolean)
     validate('dead_request_ttl') { |val| val.is_a?(::Integer) && val > 0 }
     validate('is_timed_by_default', :boolean)
+    validate('log_sampler') { |val| RedisQueuedLocks::Logging.valid_sampler?(val) }
+    validate('log_sampling_enabled', :boolean)
+    validate('log_sampling_percent') { |val| val.is_a?(::Integer) && val >= 0 && val <= 100 }
+    validate('instr_sampling_enabled', :boolean)
+    validate('instr_sampling_percent') { |val| val.is_a?(::Integer) && val >= 0 && val <= 100 }
+    validate('instr_sampler') { |val| RedisQueuedLocks::Instrument.valid_sampler?(val) }
     validate('default_conflict_strategy') do |val|
       # rubocop:disable Layout/MultilineOperationIndentation
       val == :work_through ||
@@ -92,8 +104,6 @@ class RedisQueuedLocks::Client
   #   A time-interval between the each retry (in milliseconds).
   # @option retry_jitter [Integer]
   #   Time-shift range for retry-delay (in milliseconds).
-  # @option instrumenter [#notify]
-  #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
   # @option raise_errors [Boolean]
   #   Raise errors on library-related limits such as timeout or failed lock obtain.
   # @option identity [String]
@@ -127,9 +137,50 @@ class RedisQueuedLocks::Client
   #   - should be logged the each try of lock acquiring (a lot of logs can
   #     be generated depending on your retry configurations);
   #   - see `config[:log_lock_try]`;
+  # @option instrumenter [#notify]
+  #   - Custom instrumenter that will be invoked via #notify method with `event` and `payload` data;
+  #   - See RedisQueuedLocks::Instrument::ActiveSupport for examples and implementation details;
+  #   - See [Instrumentation](#instrumentation) section of docs;
+  #   - pre-configured in `config[:isntrumenter]` with void notifier
+  #     (`RedisQueuedLocks::Instrumenter::VoidNotifier`);
   # @option instrument [NilClass,Any]
   #   - Custom instrumentation data wich will be passed to the instrumenter's payload
   #     with :instrument key;
+  # @option log_sampling_enabled [Boolean]
+  #   - enables <log sampling>: only the configured percent of RQL cases will be logged;
+  #   - disabled by default;
+  #   - works in tandem with <config.log_sampling_percent and <log.sampler>;
+  # @option log_sampling_percent [Integer]
+  #   - the percent of cases that should be logged;
+  #   - take an effect when <config.log_sampling_enalbed> is true;
+  #   - works in tandem with <config.log_sampling_enabled> and <config.log_sampler> configs;
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+  #   - percent-based log sampler that decides should be RQL case logged or not;
+  #   - works in tandem with <config.log_sampling_enabled> and
+  #     <config.log_sampling_percent> configs;
+  #   - based on the ultra simple percent-based (weight-based) algorithm that uses SecureRandom.rand
+  #     method so the algorithm error is ~(0%..13%);
+  #   - you can provide your own log sampler with bettter algorithm that should realize
+  #     `sampling_happened?(percent) => boolean` interface
+  #     (see `RedisQueuedLocks::Logging::Sampler` for example);
+  # @option instr_sampling_enabled [Boolean]
+  #   - enables <instrumentaion sampling>: only the configured percent
+  #     of RQL cases will be instrumented;
+  #   - disabled by default;
+  #   - works in tandem with <config.instr_sampling_percent and <log.instr_sampler>;
+  # @option instr_sampling_percent [Integer]
+  #   - the percent of cases that should be instrumented;
+  #   - take an effect when <config.instr_sampling_enalbed> is true;
+  #   - works in tandem with <config.instr_sampling_enabled> and <config.instr_sampler> configs;
+  # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
+  #   - percent-based log sampler that decides should be RQL case instrumented or not;
+  #   - works in tandem with <config.instr_sampling_enabled> and
+  #     <config.instr_sampling_percent> configs;
+  #   - based on the ultra simple percent-based (weight-based) algorithm that uses SecureRandom.rand
+  #     method so the algorithm error is ~(0%..13%);
+  #   - you can provide your own log sampler with bettter algorithm that should realize
+  #     `sampling_happened?(percent) => boolean` interface
+  #     (see `RedisQueuedLocks::Instrument::Sampler` for example);
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -138,7 +189,8 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.3.0
+  # @version 1.6.0
+  # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -155,7 +207,14 @@ class RedisQueuedLocks::Client
     meta: nil,
     logger: config[:logger],
     log_lock_try: config[:log_lock_try],
+    instrumenter: config[:instrumenter],
     instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
+    instr_sampling_enabled: config[:instr_sampling_enabled],
+    instr_sampling_percent: config[:instr_sampling_percent],
+    instr_sampler: config[:instr_sampler],
     &block
   )
     RedisQueuedLocks::Acquier::AcquireLock.acquire_lock(
@@ -173,23 +232,31 @@ class RedisQueuedLocks::Client
       retry_delay:,
       retry_jitter:,
       raise_errors:,
-      instrumenter: config[:instrumenter],
+      instrumenter:,
       identity:,
       fail_fast:,
       conflict_strategy:,
       meta:,
-      logger: config[:logger],
-      log_lock_try: config[:log_lock_try],
+      logger:,
+      log_lock_try:,
       instrument:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
       &block
     )
   end
+  # rubocop:enable Metrics/MethodLength
 
   # @note See #lock method signature.
   #
   # @api public
   # @since 1.0.0
-  # @version 1.3.0
+  # @version 1.6.0
+  # rubocop:disable Metrics/MethodLength
   def lock!(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -202,10 +269,17 @@ class RedisQueuedLocks::Client
     fail_fast: false,
     conflict_strategy: config[:default_conflict_strategy],
     identity: uniq_identity,
+    instrumenter: config[:instrumenter],
     meta: nil,
     logger: config[:logger],
     log_lock_try: config[:log_lock_try],
     instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
+    instr_sampling_enabled: config[:instr_sampling_enabled],
+    instr_sampling_percent: config[:instr_sampling_percent],
+    instr_sampler: config[:instr_sampler],
     &block
   )
     lock(
@@ -224,15 +298,29 @@ class RedisQueuedLocks::Client
       log_lock_try:,
       meta:,
       instrument:,
+      instrumenter:,
       conflict_strategy:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
       &block
     )
   end
+  # rubocop:enable Metrics/MethodLength
 
   # @param lock_name [String] The lock name that should be released.
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+  # @option instr_sampling_enabled [Boolean]
+  # @option instr_sampling_percent [Integer]
+  # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
   # @return [RedisQueuedLocks::Data, Hash<Symbol,Any>]
   #   Format: {
   #     ok: true/false,
@@ -247,17 +335,30 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
+  # @version 1.6.0
   def unlock(
     lock_name,
     logger: config[:logger],
     instrumenter: config[:instrumenter],
-    instrument: nil
+    instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
+    instr_sampling_enabled: config[:instr_sampling_enabled],
+    instr_sampling_percent: config[:instr_sampling_percent],
+    instr_sampler: config[:instr_sampler]
   )
     RedisQueuedLocks::Acquier::ReleaseLock.release_lock(
       redis_client,
       lock_name,
-      config[:instrumenter],
-      config[:logger]
+      instrumenter,
+      logger,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
   end
 
@@ -310,18 +411,48 @@ class RedisQueuedLocks::Client
   #
   # @param lock_name [String]
   # @param milliseconds [Integer] How many milliseconds should be added.
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify] See `config[:instrumenter]` docs for details.
+  # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+  # @option instr_sampling_enabled [Boolean]
+  # @option instr_sampling_percent [Integer]
+  # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
   # @return [Hash<Symbol,Boolean|Symbol>]
   #   - { ok: true, result: :ttl_extended }
   #   - { ok: false, result: :async_expire_or_no_lock }
   #
   # @api public
   # @since 1.0.0
-  def extend_lock_ttl(lock_name, milliseconds, logger: config[:logger])
+  # @version 1.6.0
+  def extend_lock_ttl(
+    lock_name,
+    milliseconds,
+    logger: config[:logger],
+    instrumenter: config[:instrumenter],
+    instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
+    instr_sampling_enabled: config[:instr_sampling_enabled],
+    instr_sampling_percent: config[:instr_sampling_percent],
+    instr_sampler: config[:instr_sampler]
+  )
     RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
       redis_client,
       lock_name,
       milliseconds,
-      logger
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
   end
 
@@ -332,25 +463,44 @@ class RedisQueuedLocks::Client
   #
   # @option batch_size [Integer]
   # @option logger [::Logger,#debug]
-  # @option instrumenter [#notify]
+  # @option instrumenter [#notify] See `config[:instrumenter]` docs for details.
   # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+  # @option instr_sampling_enabled [Boolean]
+  # @option instr_sampling_percent [Integer]
+  # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean|Hash<Symbol,Numeric>>]
   #   Example: { ok: true, result { rel_key_cnt: 100, rel_time: 0.01 } }
   #
   # @api public
   # @since 1.0.0
+  # @version 1.6.0
   def clear_locks(
     batch_size: config[:lock_release_batch_size],
     logger: config[:logger],
     instrumenter: config[:instrumenter],
-    instrument: nil
+    instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
+    instr_sampling_enabled: config[:instr_sampling_enabled],
+    instr_sampling_percent: config[:instr_sampling_percent],
+    instr_sampler: config[:instr_sampler]
   )
     RedisQueuedLocks::Acquier::ReleaseAllLocks.release_all_locks(
       redis_client,
       batch_size,
       logger,
       instrumenter,
-      instrument
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
   end
 
@@ -438,18 +588,30 @@ class RedisQueuedLocks::Client
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+  # @option instr_sampling_enabled [Boolean]
+  # @option instr_sampling_percent [Integer]
+  # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
   # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
   #   Format: { ok: true, result: { processed_queus: Set<String> } }
   #
   # @api public
   # @since 1.0.0
-  # @version 1.1.0
+  # @version 1.6.0
   def clear_dead_requests(
     dead_ttl: config[:dead_request_ttl],
     scan_size: config[:lock_release_batch_size],
     logger: config[:logger],
     instrumenter: config[:instrumenter],
-    instrument: nil
+    instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
+    instr_sampling_enabled: config[:instr_sampling_enabled],
+    instr_sampling_percent: config[:instr_sampling_percent],
+    instr_sampler: config[:instr_sampler]
   )
     RedisQueuedLocks::Acquier::ClearDeadRequests.clear_dead_requests(
       redis_client,
@@ -457,7 +619,13 @@ class RedisQueuedLocks::Client
       dead_ttl,
       logger,
       instrumenter,
-      instrument
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
   end
 end

data/lib/redis_queued_locks/instrument/sampler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 1.6.0
+module RedisQueuedLocks::Instrument::Sampler
+  # @return [Range]
+  #
+  # @api private
+  # @since 1.6.0
+  SAMPLING_PERCENT_RANGE = (0..100)
+
+  class << self
+    # Super simple probalistic function based on the `weight` of <true>/<false> values.
+    # Requires the <percent> parameter as the required percent of <true> values sampled.
+    #
+    # @param sampling_percent [Integer]
+    #   - percent of <true> values in range of 0..100;
+    # @return [Boolean]
+    #   - <true> for <sampling_percent>% of invocations (and <false> for the rest invocations)
+    #
+    # @api public
+    # @since 1.6.0
+    def sampling_happened?(sampling_percent)
+      sampling_percent >= SecureRandom.rand(SAMPLING_PERCENT_RANGE)
+    end
+  end
+end

data/lib/redis_queued_locks/instrument.rb

@@ -2,11 +2,58 @@
 
 # @api public
 # @since 1.0.0
+# @version 1.6.0
 module RedisQueuedLocks::Instrument
   require_relative 'instrument/void_notifier'
   require_relative 'instrument/active_support'
+  require_relative 'instrument/sampler'
 
   class << self
+    # @param instr_sampling_enabled [Boolean]
+    # @param instr_sampling_percent [Integer]
+    # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 1.6.0
+    def should_instrument?(instr_sampling_enabled, instr_sampling_percent, instr_sampler)
+      return true unless instr_sampling_enabled
+      instr_sampler.sampling_happened?(instr_sampling_percent)
+    end
+
+    # @param sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 1.6.0
+    def valid_sampler?(sampler)
+      return false unless sampler.respond_to?(:sampling_happened?)
+
+      m_obj = sampler.method(:sampling_happened?)
+      m_sig = m_obj.parameters
+
+      # NOTE:
+      #   Required method signature (sampling_percent)
+      #     => [[:req, :sampling_percent]]
+      #     => [[:opt, :sampling_percent]]
+      #     => [[:req, :sampling_percent], [:block, :block]]
+      #     => [[:opt, :sampling_percent], [:block, :block]]
+      if m_sig.size == 1
+        prm = m_sig[0][0]
+        prm == :req || prm == :opt
+      elsif m_sig.size == 2
+        f_prm = m_sig[0][0]
+        s_prm = m_sign[1][0]
+
+        # rubocop:disable Layout/MultilineOperationIndentation
+        f_prm == :req && s_prm == :block ||
+        f_prm == :opt && s_prm == :block
+        # rubocop:enable Layout/MultilineOperationIndentation
+      else
+        false
+      end
+    end
+
     # @param instrumenter [Class,Module,Object]
     # @return [Boolean]
     #

data/lib/redis_queued_locks/logging/sampler.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 1.5.0
+module RedisQueuedLocks::Logging::Sampler
+  # @return [Range]
+  #
+  # @api private
+  # @since 1.6.0
+  SAMPLING_PERCENT_RANGE = (0..100)
+
+  class << self
+    # Super simple probalistic function based on the `weight` of <true>/<false> values.
+    # Requires the <percent> parameter as the required percent of <true> values sampled.
+    #
+    # @param sampling_percent [Integer]
+    #   - percent of <true> values in range of 0..100;
+    # @return [Boolean]
+    #   - <true> for <sampling_percent>% of invocations (and <false> for the rest invocations)
+    #
+    # @api public
+    # @since 1.5.0
+    # @version 1.6.0
+    def sampling_happened?(sampling_percent)
+      sampling_percent >= SecureRandom.rand(SAMPLING_PERCENT_RANGE)
+    end
+  end
+end

data/lib/redis_queued_locks/logging.rb

@@ -2,10 +2,57 @@
 
 # @api public
 # @since 1.0.0
+# @version 1.5.0
 module RedisQueuedLocks::Logging
   require_relative 'logging/void_logger'
+  require_relative 'logging/sampler'
 
   class << self
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 1.5.0
+    def should_log?(log_sampling_enabled, log_sampling_percent, log_sampler)
+      return true unless log_sampling_enabled
+      log_sampler.sampling_happened?(log_sampling_percent)
+    end
+
+    # @param sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 1.5.0
+    def valid_sampler?(sampler)
+      return false unless sampler.respond_to?(:sampling_happened?)
+
+      m_obj = sampler.method(:sampling_happened?)
+      m_sig = m_obj.parameters
+
+      # NOTE:
+      #   Required method signature (sampling_percent)
+      #     => [[:req, :sampling_percent]]
+      #     => [[:opt, :sampling_percent]]
+      #     => [[:req, :sampling_percent], [:block, :block]]
+      #     => [[:opt, :sampling_percent], [:block, :block]]
+      if m_sig.size == 1
+        prm = m_sig[0][0]
+        prm == :req || prm == :opt
+      elsif m_sig.size == 2
+        f_prm = m_sig[0][0]
+        s_prm = m_sign[1][0]
+
+        # rubocop:disable Layout/MultilineOperationIndentation
+        f_prm == :req && s_prm == :block ||
+        f_prm == :opt && s_prm == :block
+        # rubocop:enable Layout/MultilineOperationIndentation
+      else
+        false
+      end
+    end
+
     # @param logger [::Logger,#debug,::SemanticLogger::Logger]
     # @return [Boolean]
     #

data/lib/redis_queued_locks/utilities.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.0.0
+# @version 1.5.0
 module RedisQueuedLocks::Utilities
   module_function
 

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 1.4.0
-  VERSION = '1.4.0'
+  # @version 1.6.0
+  VERSION = '1.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-13 00:00:00.000000000 Z
+date: 2024-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -79,8 +79,10 @@ files:
 - lib/redis_queued_locks/errors.rb
 - lib/redis_queued_locks/instrument.rb
 - lib/redis_queued_locks/instrument/active_support.rb
+- lib/redis_queued_locks/instrument/sampler.rb
 - lib/redis_queued_locks/instrument/void_notifier.rb
 - lib/redis_queued_locks/logging.rb
+- lib/redis_queued_locks/logging/sampler.rb
 - lib/redis_queued_locks/logging/void_logger.rb
 - lib/redis_queued_locks/resource.rb
 - lib/redis_queued_locks/utilities.rb
@@ -108,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.1
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Queued distributed locks based on Redis.