redis_queued_locks 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5be49c89b572553d2de7af37b8bbc38439bcefc5b2b33cd4d8e542fb3c9dd3e3
-  data.tar.gz: 8a3a5509e82bd45ff9576677e2c2017c670fdd6a825da8ad0281f0fc1b6e7e69
+  metadata.gz: dd9e0ee49d4c08d6ba572a825da792468926b2f676e872a2337b1ce2eff60836
+  data.tar.gz: ae635ac450f966539581c4b5a53098b92ba29562bb0641049571ca0ceb1461e7
 SHA512:
-  metadata.gz: 8f151272fadc4be25fd1344f9b29a5b263bc8ab63d17e8d09c55178232e4e57acac456c5987c0040172643e0a479976f9c12d0ff81549ba223ed742adb0dfcd1
-  data.tar.gz: c862d4040d1dbe421a7a8e2a10c8e24c8e22cd74c65d64746cb74ad96c2d31b3c1ec7a55f22cc0149ea0a65014f4d891d8a13f4336b07d6f56130673203ff384
+  metadata.gz: b678b3fbccd5273d17d07120c144b0eb1c6be32db73ff1aa2f9fb19f485d30499645f3c4592fad0cb4cdeab1ebcd37f437b62740e01a46dce999eaaa2814f146
+  data.tar.gz: b8cb79c79767cd1d3b831992454c84c8399f6bf7ac313b8a2d0a7527711f555cb2196a172ae435103df2fc4c3e483b0a5b35775fba4baee7b7bad6234103cb0a

data/CHANGELOG.md

@@ -1,8 +1,14 @@
 ## [Unreleased]
 
+## [1.6.0] - 2024-05-25
+### Added
+- New Feature: **Instrumentation Sampling** - configurable instrumentation sampling based on `weight` algorithm (where the weight is a percentage of RQL cases that should be logged);
+- Missing instrumenter customization in public `RedisQueuedLocks::Client` methods;
+- Documentation updates;
+
 ## [1.5.0] - 2024-05-23
 ### Added
-- New Feature: **Log sampling** - configurable log sampling based on `weight` algorithm (where the weight is a percentage);
+- New Feature: **Log sampling** - configurable log sampling based on `weight` algorithm (where the weight is a percentage of RQL cases that should be logged);
 
 ## [1.4.0] - 2024-05-13
 ### Added

data/README.md

@@ -253,6 +253,27 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - you can provide your own log sampler with bettter algorithm that should realize
   #   `sampling_happened?(percent) => boolean` interface (see `RedisQueuedLocks::Logging::Sampler` for example);
   config.log_sampler = RedisQueuedLocks::Logging::Sampler
+
+  # (default: false)
+  # - 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>;
+  config.instr_sampling_enabled = false
+
+  # (default: 15)
+  # - 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;
+  config.instr_sampling_percent = 15
+
+  # (default: 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);
+  config.instr_sampler = RedisQueuedLocks::Instrument::Sampler
 end
 ```
 
@@ -309,11 +330,15 @@ def lock(
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
   meta: nil,
   instrument: nil,
+  instrumenter: config[:instrumenter],
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
   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
 )
 ```
@@ -346,6 +371,9 @@ def lock(
   - See RedisQueuedLocks::Instrument::ActiveSupport for example;
   - See [Instrumentation](#instrumentation) section of docs;
   - pre-configured in `config[:isntrumenter]` with void notifier (`RedisQueuedLocks::Instrumenter::VoidNotifier`);
+- `instrument` - (optional) `[NilClass,Any]`
+  - Custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
+  - `nil` by default (means "no custom instrumentation data");
 - `raise_errors` - (optional) `[Boolean]`
   - Raise errors on library-related limits (such as timeout or retry count limit) and on lock conflicts (such as same-process dead locks);
   - `false` by default;
@@ -377,9 +405,6 @@ def lock(
   - A custom metadata wich will be passed to the lock data in addition to the existing data;
   - Custom metadata can not contain reserved lock data keys (such as `lock_key`, `acq_id`, `ts`, `ini_ttl`, `rem_ttl`);
   - `nil` by default (means "no metadata");
-- `instrument` - (optional) `[NilClass,Any]`
-  - Custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
-  - `nil` by default (means "no custom instrumentation data");
 - `logger` - (optional) `[::Logger,#debug]`
   - Logger object used for loggin internal mutation oeprations and opertioan results / process progress;
   - pre-configured in `config[:logger]` with void logger `RedisQueuedLocks::Logging::VoidLogger`;
@@ -405,6 +430,24 @@ def lock(
   - you can provide your own log sampler with bettter algorithm that should realize
     `sampling_happened?(percent) => boolean` interface (see `RedisQueuedLocks::Logging::Sampler` for example);
   - pre-configured in `config[:log_sampler]`;
+- `instr_sampling_enabled` - (optional) `[Boolean]`
+  - enables **instrumentaion sampling**: only the configured percent of RQL cases will be instrumented;
+  - disabled by default;
+  - works in tandem with `instr_sampling_percent` and `instr_sampler` options;
+  - pre-configured in `config[:instr_sampling_enabled]`;
+- `instr_sampling_percent` - (optional) `[Integer]`
+  - the percent of cases that should be instrumented;
+  - take an effect when `instr_sampling_enalbed` is true;
+  - works in tandem with `instr_sampling_enabled` and `instr_sampler` options;
+  - pre-configured in `config[:instr_sampling_percent]`;
+- `instr_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]`
+  - percent-based log sampler that decides should be RQL case instrumented or not;
+  - works in tandem with `instr_sampling_enabled` and `instr_sampling_percent` options;
+  - 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);
+  - pre-configured in `config[:instr_sampler]`;
 - `block` - (optional) `[Block]`
   - A block of code that should be executed after the successfully acquired lock.
   - If block is **passed** the obtained lock will be released after the block execution or it's ttl (what will happen first);
@@ -558,7 +601,7 @@ rql.lock("my_lock", queue_ttl: 5, timeout: 10_000, retry_count: nil)
 
 # lock queue: =>
 [
- "rql:acq:123/456/567/676/374dd74324", 
+ "rql:acq:123/456/567/676/374dd74324",
  "rql:acq:123/456/567/677/374dd74322", # <- long living lock
  "rql:acq:123/456/567/679/374dd74321",
  "rql:acq:123/456/567/683/374dd74322", # <== we are here
@@ -613,10 +656,14 @@ def lock!(
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
   instrument: nil,
+  instrumenter: config[:instrumenter],
   conflict_strategy: config[:default_conflict_strategy],
   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
 )
 ```
@@ -797,6 +844,15 @@ rql.queued?("your_lock_name") # => true/false
   - `:log_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]`
     - **log sampling**: percent-based log sampler that decides should be RQL case logged or not;
     - pre-configured in `config[:log_sampler]`;
+  - `:instr_sampling_enabled` - (optional) `[Boolean]`
+    - enables **instrumentaion sampling**;
+    - pre-configured in `config[:instr_sampling_enabled]`;
+  - `instr_sampling_percent` - (optional) `[Integer]`
+    - the percent of cases that should be instrumented;
+    - pre-configured in `config[:instr_sampling_percent]`;
+  - `instr_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]`
+    - percent-based log sampler that decides should be RQL case instrumented or not;
+    - pre-configured in `config[:instr_sampler]`;
 - if you try to unlock non-existent lock you will receive `ok: true` result with operation timings
   and `:nothing_to_release` result factor inside;
 
@@ -856,6 +912,15 @@ rql.unlock("your_lock_name")
   - `:log_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]`
     - **log sampling**: percent-based log sampler that decides should be RQL case logged or not;
     - pre-configured in `config[:log_sampler]`;
+  - `:instr_sampling_enabled` - (optional) `[Boolean]`
+    - enables **instrumentaion sampling**;
+    - pre-configured in `config[:instr_sampling_enabled]`;
+  - `instr_sampling_percent` - (optional) `[Integer]`
+    - the percent of cases that should be instrumented;
+    - pre-configured in `config[:instr_sampling_percent]`;
+  - `instr_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]`
+    - percent-based log sampler that decides should be RQL case instrumented or not;
+    - pre-configured in `config[:instr_sampler]`;
 - returns:
   - `[Hash<Symbol,Numeric>]` - Format: `{ ok: true, result: Hash<Symbol,Numeric> }`;
   - result data:
@@ -888,6 +953,12 @@ rql.clear_locks
     - the lock name which ttl should be extended;
   - `milliseconds` - (required) `[Integer]`
     - how many milliseconds should be added to the lock's TTL;
+  - `:instrumenter` - (optional) `[#notify]`
+    - custom instrumenter object;
+    - pre-configured in `config[:instrumetner]`;
+  - `:instrument` - (optional) `[NilClass,Any]`;
+    - custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
+    - `nil` by default (no additional data);
   - `:logger` - (optional) `[::Logger,#debug]`
     - custom logger object;
     - pre-configured in `config[:logger]`;
@@ -900,6 +971,15 @@ rql.clear_locks
   - `:log_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]`
     - **log sampling**: percent-based log sampler that decides should be RQL case logged or not;
     - pre-configured in `config[:log_sampler]`;
+  - `:instr_sampling_enabled` - (optional) `[Boolean]`
+    - enables **instrumentaion sampling**;
+    - pre-configured in `config[:instr_sampling_enabled]`;
+  - `instr_sampling_percent` - (optional) `[Integer]`
+    - the percent of cases that should be instrumented;
+    - pre-configured in `config[:instr_sampling_percent]`;
+  - `instr_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]`
+    - percent-based log sampler that decides should be RQL case instrumented or not;
+    - pre-configured in `config[:instr_sampler]`;
 - returns `{ ok: true, result: :ttl_extended }` when ttl is extended;
 - returns `{ ok: false, result: :async_expire_or_no_lock }` when a lock not found or a lock is already expired during
   some steps of invocation (see **Important** section below);
@@ -1137,6 +1217,15 @@ Accepts:
 - `:log_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]`
   - **log sampling**: percent-based log sampler that decides should be RQL case logged or not;
   - pre-configured in `config[:log_sampler]`;
+- `:instr_sampling_enabled` - (optional) `[Boolean]`
+  - enables **instrumentaion sampling**;
+  - pre-configured in `config[:instr_sampling_enabled]`;
+- `instr_sampling_percent` - (optional) `[Integer]`
+  - the percent of cases that should be instrumented;
+  - pre-configured in `config[:instr_sampling_percent]`;
+- `instr_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]`
+  - percent-based log sampler that decides should be RQL case instrumented or not;
+  - pre-configured in `config[:instr_sampler]`;
 
 Returns: `{ ok: true, processed_queues: Set<String> }` returns the list of processed lock queues;
 
@@ -1335,7 +1424,6 @@ Detalized event semantics and payload structure:
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - **Major**:
-  - precent-based instrumentation sampling (instrument the concrete % of cases via "sampling" strategy);
   - support for Random Access strategy (non-queued behavior);
   - lock request prioritization;
   - **strict redlock algorithm support** (support for many `RedisClient` instances);

data/lib/redis_queued_locks/acquier/acquire_lock/try_to_lock.rb

@@ -29,11 +29,12 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @param conflict_strategy [Symbol]
   # @param meta [NilClass,Hash<String|Symbol,Any>]
   # @param log_sampled [Boolean]
+  # @param instr_sampled [Boolean]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol|Hash<Symbol,Any> }
   #
   # @api private
   # @since 1.0.0
-  # @version 1.5.0
+  # @version 1.6.0
   # rubocop:disable Metrics/MethodLength
   def try_to_lock(
     redis,
@@ -48,7 +49,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     fail_fast,
     conflict_strategy,
     meta,
-    log_sampled
+    log_sampled,
+    instr_sampled
   )
     # Step X: intermediate invocation results
     inter_result = nil
@@ -485,11 +487,12 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @param queue_ttl [Integer]
   # @param acquier_id [String]
   # @param log_sampled [Boolean]
+  # @param instr_sampled [Boolean]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 1.0.0
-  # @version 1.5.0
+  # @version 1.6.0
   def dequeue_from_lock_queue(
     redis,
     logger,
@@ -497,7 +500,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     lock_key_queue,
     queue_ttl,
     acquier_id,
-    log_sampled
+    log_sampled,
+    instr_sampled
   )
     result = redis.call('ZREM', lock_key_queue, acquier_id)
 

data/lib/redis_queued_locks/acquier/acquire_lock/yield_expire.rb

@@ -24,7 +24,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
   # @param ttl [Integer,NilClass] Lock's time to live (in ms). Nil means "without timeout".
   # @param queue_ttl [Integer] Lock request lifetime.
   # @param block [Block] Custom logic that should be invoked unter the obtained lock.
-  # @param log_sampled [Boolean] Should the logic be logged or not (is log sample happened?).
+  # @param log_sampled [Boolean] Should the logic be logged or not.
+  # @param instr_sampled [Boolean] Should the logic be instrumented or not.
   # @param should_expire [Boolean] Should the lock be expired after the block invocation.
   # @param should_decrease [Boolean]
   #   - Should decrease the lock TTL after the lock invocation;
@@ -33,7 +34,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
   #
   # @api private
   # @since 1.3.0
-  # @version 1.5.0
+  # @version 1.6.0
   # rubocop:disable Metrics/MethodLength
   def yield_expire(
     redis,
@@ -45,6 +46,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
     ttl,
     queue_ttl,
     log_sampled,
+    instr_sampled,
     should_expire,
     should_decrease,
     &block
@@ -73,11 +75,13 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
           "acq_id => '#{acquier_id}'"
         end
       end if log_sampled
+
       redis.call('EXPIRE', lock_key, '0')
     elsif should_decrease
       finish_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
       spent_time = (finish_time - initial_time)
       decreased_ttl = ttl - spent_time - RedisQueuedLocks::Resource::REDIS_TIMESHIFT_ERROR
+
       if decreased_ttl > 0
         run_non_critical do
           logger.debug do
@@ -88,6 +92,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
             "acq_id => '#{acquier_id}' " \
           end
         end if log_sampled
+
         # NOTE:# NOTE: EVAL signature -> <lua script>, (number of keys), *(keys), *(arguments)
         redis.call('EVAL', DECREASE_LOCK_PTTL, 1, lock_key, decreased_ttl)
         # TODO: upload scripts to the redis

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -87,19 +87,40 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #     - `:wait_for_lock`;
     #     - `:dead_locking`;
     # @option log_sampling_enabled [Boolean]
-    #   - The percent of cases that should be logged;
-    #   - Sampling algorithm is super simple and works via SecureRandom.rand method
-    #     on the base of "weight" algorithm;
-    #   - You can provide your own sampler via config[:log_sampler] config and :sampler option
-    #     (see `RedisQueuedLocks::Logging::Sampler` for examples);
-    #   - The spread of guaranteed percent is approximately +13% (rand method spread);
-    #   - Take an effect when <log_sampling_enabled> parameter has <true> value
-    #     (when log sampling is enabled);
+    #   - 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 <log_sampling_enabled> parameter has <true> value
-    #     (when log sampling is enabled);
+    #   - 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]
@@ -108,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,
@@ -135,6 +156,9 @@ module RedisQueuedLocks::Acquier::AcquireLock
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
       &block
     )
       # Step 0: Prevent argument type incompatabilities
@@ -187,6 +211,11 @@ module RedisQueuedLocks::Acquier::AcquireLock
         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 = {
@@ -207,7 +236,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
           lock_key_queue,
           queue_ttl,
           acquier_id,
-          log_sampled
+          log_sampled,
+          instr_sampled
         )
       end
 
@@ -263,7 +293,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
             fail_fast,
             conflict_strategy,
             meta,
-            log_sampled
+            log_sampled,
+            instr_sampled
           ) => { ok:, result: }
 
           acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
@@ -297,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
@@ -319,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
@@ -343,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
@@ -452,6 +483,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               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
@@ -477,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
@@ -490,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

@@ -13,10 +13,14 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
     # @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
+    # @version 1.6.0
     def clear_dead_requests(
       redis_client,
       scan_size,
@@ -26,7 +30,10 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
       instrument,
       log_sampling_enabled,
       log_sampling_percent,
-      log_sampler
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
       dead_score = RedisQueuedLocks::Resource.acquier_dead_score(dead_ttl / 1_000.0)
 

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -17,22 +17,32 @@ 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
-    # @version 1.5.0
+    # @version 1.6.0
     def extend_lock_ttl(
       redis_client,
       lock_name,
       milliseconds,
       logger,
+      instrumenter,
+      instrument,
       log_sampling_enabled,
       log_sampling_percent,
-      log_sampler
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -24,19 +24,46 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #    - 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 cases will be logged;
-    #   - Works in tandem with <log_samplng_percent> option;
+    #   - 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 <log_sampling_enabled> parameter has <true> value
-    #     (when log sampling is enabled);
+    #   - 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.5.0
+    # @version 1.6.0
     def release_all_locks(
       redis,
       batch_size,
@@ -45,7 +72,10 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
       instrument,
       log_sampling_enabled,
       log_sampling_percent,
-      log_sampler
+      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: }
@@ -53,13 +83,19 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
       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

@@ -24,25 +24,47 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @param log_sampling_enabled [Boolean]
-    #   - The percent of cases that should be logged;
-    #   - Sampling algorithm is super simple and works via SecureRandom.rand method
-    #     on the base of "weight" algorithm;
-    #   - You can provide your own sampler via config[:log_sampler] config and :sampler option
-    #     (see `RedisQueuedLocks::Logging::Sampler` for examples);
-    #   - The spread of guaranteed percent is approximately +13% (rand method spread);
-    #   - Take an effect when <log_sampling_enabled> parameter has <true> value
-    #     (when log sampling is enabled);
+    #   - 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 <log_sampling_enabled> parameter has <true> value
-    #     (when log sampling is enabled);
+    #   - 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.5.0
+    # @version 1.6.0
+    # rubocop:disable Metrics/MethodLength
     def release_lock(
       redis,
       lock_name,
@@ -50,7 +72,10 @@ module RedisQueuedLocks::Acquier::ReleaseLock
       logger,
       log_sampling_enabled,
       log_sampling_percent,
-      log_sampler
+      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)
@@ -61,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,
@@ -68,7 +99,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
           rel_time: rel_time,
           at: time_at
         })
-      end
+      end if instr_sampled
 
       RedisQueuedLocks::Data[
         ok: true,
@@ -81,6 +112,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
         }
       ]
     end
+    # rubocop:enable Metrics/MethodLength
 
     private
 

data/lib/redis_queued_locks/client.rb

@@ -26,6 +26,9 @@ class RedisQueuedLocks::Client
     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 }
@@ -43,6 +46,9 @@ class RedisQueuedLocks::Client
     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 ||
@@ -98,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]
@@ -133,6 +137,12 @@ 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;
@@ -153,6 +163,24 @@ class RedisQueuedLocks::Client
   #   - 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]
@@ -161,7 +189,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.5.0
+  # @version 1.6.0
   # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
@@ -179,10 +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(
@@ -200,7 +232,7 @@ class RedisQueuedLocks::Client
       retry_delay:,
       retry_jitter:,
       raise_errors:,
-      instrumenter: config[:instrumenter],
+      instrumenter:,
       identity:,
       fail_fast:,
       conflict_strategy:,
@@ -211,6 +243,9 @@ class RedisQueuedLocks::Client
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
       &block
     )
   end
@@ -220,7 +255,8 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.5.0
+  # @version 1.6.0
+  # rubocop:disable Metrics/MethodLength
   def lock!(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -233,6 +269,7 @@ 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],
@@ -240,6 +277,9 @@ class RedisQueuedLocks::Client
     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(
@@ -258,13 +298,18 @@ 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]
@@ -273,6 +318,9 @@ class RedisQueuedLocks::Client
   # @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,
@@ -287,7 +335,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.5.0
+  # @version 1.6.0
   def unlock(
     lock_name,
     logger: config[:logger],
@@ -295,16 +343,22 @@ class RedisQueuedLocks::Client
     instrument: nil,
     log_sampling_enabled: config[:log_sampling_enabled],
     log_sampling_percent: config[:log_sampling_percent],
-    log_sampler: config[:log_sampler]
+    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
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
   end
 
@@ -358,43 +412,47 @@ 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]
-  #   - The percent of cases that should be logged;
-  #   - Sampling algorithm is super simple and works via SecureRandom.rand method
-  #     on the base of "weight" algorithm;
-  #   - You can provide your own sampler via config[:log_sampler] config and :sampler option
-  #     (see `RedisQueuedLocks::Logging::Sampler` for examples);
-  #   - The spread of guaranteed percent is approximately +13% (rand method spread);
-  #   - Take an effect when <log_sampling_enabled> parameter has <true> value
-  #     (when log sampling is enabled);
   # @option log_sampling_percent [Integer]
-  #   - The percent of cases that should be logged;
-  #   - Take an effect when <log_sampling_enabled> parameter has <true> value
-  #     (when log sampling is enabled);
   # @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
-  # @version 1.5.0
+  # @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]
+    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,
+      instrumenter,
+      instrument,
       log_sampling_enabled,
       log_sampling_percent,
-      log_sampler
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
   end
 
@@ -405,17 +463,20 @@ 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.5.0
+  # @version 1.6.0
   def clear_locks(
     batch_size: config[:lock_release_batch_size],
     logger: config[:logger],
@@ -423,7 +484,10 @@ class RedisQueuedLocks::Client
     instrument: nil,
     log_sampling_enabled: config[:log_sampling_enabled],
     log_sampling_percent: config[:log_sampling_percent],
-    log_sampler: config[:log_sampler]
+    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,
@@ -433,7 +497,10 @@ class RedisQueuedLocks::Client
       instrument,
       log_sampling_enabled,
       log_sampling_percent,
-      log_sampler
+      log_sampler,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler
     )
   end
 
@@ -524,12 +591,15 @@ class RedisQueuedLocks::Client
   # @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.5.0
+  # @version 1.6.0
   def clear_dead_requests(
     dead_ttl: config[:dead_request_ttl],
     scan_size: config[:lock_release_batch_size],
@@ -538,7 +608,10 @@ class RedisQueuedLocks::Client
     instrument: nil,
     log_sampling_enabled: config[:log_sampling_enabled],
     log_sampling_percent: config[:log_sampling_percent],
-    log_sampler: config[:log_sampler]
+    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,
@@ -549,7 +622,10 @@ class RedisQueuedLocks::Client
       instrument,
       log_sampling_enabled,
       log_sampling_percent,
-      log_sampler
+      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

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
-# @api private
+# @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.
@@ -12,10 +18,11 @@ module RedisQueuedLocks::Logging::Sampler
     # @return [Boolean]
     #   - <true> for <sampling_percent>% of invocations (and <false> for the rest invocations)
     #
-    # @api private
+    # @api public
     # @since 1.5.0
+    # @version 1.6.0
     def sampling_happened?(sampling_percent)
-      sampling_percent >= SecureRandom.rand(0..100)
+      sampling_percent >= SecureRandom.rand(SAMPLING_PERCENT_RANGE)
     end
   end
 end

data/lib/redis_queued_locks/logging.rb

@@ -2,6 +2,7 @@
 
 # @api public
 # @since 1.0.0
+# @version 1.5.0
 module RedisQueuedLocks::Logging
   require_relative 'logging/void_logger'
   require_relative 'logging/sampler'

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 1.5.0
-  VERSION = '1.5.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.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-23 00:00:00.000000000 Z
+date: 2024-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -79,6 +79,7 @@ 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
@@ -109,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.