redis_queued_locks 1.4.0 → 1.6.0

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -86,6 +86,41 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #     - `:extendable_work_through`;
     #     - `:wait_for_lock`;
     #     - `:dead_locking`;
+    # @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]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -94,7 +129,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.4.0
+    # @version 1.6.0
     def acquire_lock(
       redis,
       lock_name,
@@ -118,6 +153,12 @@ module RedisQueuedLocks::Acquier::AcquireLock
       logger:,
       log_lock_try:,
       conflict_strategy:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
       &block
     )
       # Step 0: Prevent argument type incompatabilities
@@ -165,6 +206,17 @@ module RedisQueuedLocks::Acquier::AcquireLock
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
       acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
 
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sampling_percent,
+        log_sampler
+      )
+      instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
+        instr_sampling_enabled,
+        instr_sampling_percent,
+        instr_sampler
+      )
+
       # Step X: intermediate result observer
       acq_process = {
         lock_info: {},
@@ -183,7 +235,9 @@ module RedisQueuedLocks::Acquier::AcquireLock
           lock_key,
           lock_key_queue,
           queue_ttl,
-          acquier_id
+          acquier_id,
+          log_sampled,
+          instr_sampled
         )
       end
 
@@ -194,7 +248,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
           "queue_ttl => #{queue_ttl} " \
           "acq_id => '#{acquier_id}'"
         end
-      end
+      end if log_sampled
 
       # Step 2: try to lock with timeout
       with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
@@ -209,7 +263,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               "queue_ttl => #{queue_ttl} " \
               "acq_id => '{#{acquier_id}'"
             end
-          end
+          end if log_sampled
 
           # Step 2.X: check the actual score: is it in queue ttl limit or not?
           if RedisQueuedLocks::Resource.dead_score_reached?(acquier_position, queue_ttl)
@@ -223,7 +277,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                 "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}'"
               end
-            end
+            end if log_sampled
           end
 
           try_to_lock(
@@ -238,7 +292,9 @@ module RedisQueuedLocks::Acquier::AcquireLock
             queue_ttl,
             fail_fast,
             conflict_strategy,
-            meta
+            meta,
+            log_sampled,
+            instr_sampled
           ) => { ok:, result: }
 
           acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
@@ -261,7 +317,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   "acq_id => '#{acquier_id}' " \
                   "acq_time => #{acq_time} (ms)"
                 end
-              end
+              end if log_sampled
 
               run_non_critical do
                 instrumenter.notify('redis_queued_locks.extendable_reentrant_lock_obtained', {
@@ -272,7 +328,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   acq_time: acq_time,
                   instrument:
                 })
-              end
+              end if instr_sampled
             elsif acq_process[:result][:process] == :conflict_work_through
               # instrumetnation: (reentrant lock without ttl extension)
               run_non_critical do
@@ -283,7 +339,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   "acq_id => '#{acquier_id}' " \
                   "acq_time => #{acq_time} (ms)"
                 end
-              end
+              end if log_sampled
 
               run_non_critical do
                 instrumenter.notify('redis_queued_locks.reentrant_lock_obtained', {
@@ -294,7 +350,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   acq_time: acq_time,
                   instrument:
                 })
-              end
+              end if instr_sampled
             else
               # instrumentation: (classic lock obtain)
               # NOTE: classic is: acq_process[:result][:process] == :lock_obtaining
@@ -306,7 +362,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   "acq_id => '#{acquier_id}' " \
                   "acq_time => #{acq_time} (ms)"
                 end
-              end
+              end if log_sampled
 
               # Step X (instrumentation): lock obtained
               run_non_critical do
@@ -318,7 +374,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   acq_time: acq_time,
                   instrument:
                 })
-              end
+              end if instr_sampled
             end
 
             # Step 2.1.a: successfully acquired => build the result
@@ -426,6 +482,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
               ttl_shift,
               ttl,
               queue_ttl,
+              log_sampled,
+              instr_sampled,
               should_expire, # NOTE: should expire the lock after the block execution
               should_decrease, # NOTE: should decrease the lock ttl in reentrant locks?
               &block
@@ -451,7 +509,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   acq_time: acq_process[:acq_time],
                   instrument:
                 })
-              end
+              end if instr_sampled
             else
               # Step X (instrumentation): lock_hold_and_release
               run_non_critical do
@@ -464,7 +522,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   acq_time: acq_process[:acq_time],
                   instrument:
                 })
-              end
+              end if instr_sampled
             end
           end
         else

data/lib/redis_queued_locks/acquier/clear_dead_requests.rb

@@ -10,11 +10,31 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
     # @param logger [::Logger,#debug]
     # @param instrumenter [#notify]
     # @param instrument [NilClass,Any]
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @param instr_sampling_enabled [Boolean]
+    # @param instr_sampling_percent [Integer]
+    # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
     # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
     #
     # @api private
     # @since 1.0.0
-    def clear_dead_requests(redis_client, scan_size, dead_ttl, logger, instrumenter, instrument)
+    # @version 1.6.0
+    def clear_dead_requests(
+      redis_client,
+      scan_size,
+      dead_ttl,
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
+    )
       dead_score = RedisQueuedLocks::Resource.acquier_dead_score(dead_ttl / 1_000.0)
 
       result = Set.new.tap do |processed_queues|

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -17,11 +17,33 @@ module RedisQueuedLocks::Acquier::ExtendLockTTL
     # @param lock_name [String]
     # @param milliseconds [Integer]
     # @param logger [::Logger,#debug]
+    # @param instrumenter [#notify]
+    # @param instrument [NilClass,Any]
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @param instr_sampling_enabled [Boolean]
+    # @param instr_sampling_percent [Integer]
+    # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
     # @return [Hash<Symbol,Boolean|Symbol>]
     #
     # @api private
     # @since 1.0.0
-    def extend_lock_ttl(redis_client, lock_name, milliseconds, logger)
+    # @version 1.6.0
+    def extend_lock_ttl(
+      redis_client,
+      lock_name,
+      milliseconds,
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
+    )
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 
       # NOTE: EVAL signature -> <lua script>, (number of keys), *(keys), *(arguments)

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -20,29 +20,82 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @param isntrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @option instrument [NilClass,Any]
+    # @param instrument [NilClass,Any]
     #    - Custom instrumentation data wich will be passed to the instrumenter's payload
     #      with :instrument key;
+    # @param 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>;
+    # @param 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;
+    # @param 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);
+    # @param 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>;
+    # @param 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;
+    # @param 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);
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
     #   Format: { ok: true, result: Hash<Symbol,Numeric> }
     #
     # @api private
     # @since 1.0.0
-    # @version 1.4.0
-    def release_all_locks(redis, batch_size, logger, instrumenter, instrument)
+    # @version 1.6.0
+    def release_all_locks(
+      redis,
+      batch_size,
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
+    )
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
       fully_release_all_locks(redis, batch_size) => { ok:, result: }
       time_at = Time.now.to_f
       rel_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
       rel_time = ((rel_end_time - rel_start_time) / 1_000).ceil(2)
 
+      instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
+        instr_sampling_enabled,
+        instr_sampling_percent,
+        instr_sampler
+      )
+
       run_non_critical do
         instrumenter.notify('redis_queued_locks.explicit_all_locks_release', {
           at: time_at,
           rel_time: rel_time,
           rel_key_cnt: result[:rel_key_cnt]
         })
-      end
+      end if instr_sampled
 
       RedisQueuedLocks::Data[
         ok: true,

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -23,13 +23,60 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
+    # @param 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>;
+    # @param 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;
+    # @param 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);
+    # @param 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>;
+    # @param 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;
+    # @param 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);
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean<Hash<Symbol,Numeric|String|Symbol>>]
     #   Format: { ok: true/false, result: Hash<Symbol,Numeric|String|Symbol> }
     #
     # @api private
     # @since 1.0.0
-    # @version 1.4.0
-    def release_lock(redis, lock_name, instrumenter, logger)
+    # @version 1.6.0
+    # rubocop:disable Metrics/MethodLength
+    def release_lock(
+      redis,
+      lock_name,
+      instrumenter,
+      logger,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
+    )
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
 
@@ -39,6 +86,12 @@ module RedisQueuedLocks::Acquier::ReleaseLock
       rel_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
       rel_time = ((rel_end_time - rel_start_time) / 1_000).ceil(2)
 
+      instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
+        instr_sampling_enabled,
+        instr_sampling_percent,
+        instr_sampler
+      )
+
       run_non_critical do
         instrumenter.notify('redis_queued_locks.explicit_lock_release', {
           lock_key: lock_key,
@@ -46,7 +99,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
           rel_time: rel_time,
           at: time_at
         })
-      end
+      end if instr_sampled
 
       RedisQueuedLocks::Data[
         ok: true,
@@ -59,6 +112,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
         }
       ]
     end
+    # rubocop:enable Metrics/MethodLength
 
     private