redis_queued_locks 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5be49c89b572553d2de7af37b8bbc38439bcefc5b2b33cd4d8e542fb3c9dd3e3
-  data.tar.gz: 8a3a5509e82bd45ff9576677e2c2017c670fdd6a825da8ad0281f0fc1b6e7e69
+  metadata.gz: cd303479ce60c268e630d4ad770657cbe0223cffcb9990d31a9bb3de92d80843
+  data.tar.gz: 2a19bfed90da70fa8c49bf069a2acd110d3840eeb78f1f21767416c28e5bc6b7
 SHA512:
-  metadata.gz: 8f151272fadc4be25fd1344f9b29a5b263bc8ab63d17e8d09c55178232e4e57acac456c5987c0040172643e0a479976f9c12d0ff81549ba223ed742adb0dfcd1
-  data.tar.gz: c862d4040d1dbe421a7a8e2a10c8e24c8e22cd74c65d64746cb74ad96c2d31b3c1ec7a55f22cc0149ea0a65014f4d891d8a13f4336b07d6f56130673203ff384
+  metadata.gz: 0c2d6c956bfc7227cd45c33c8b983ae759e13bf7149121c272821922d66a4be73b57b344e2042f86d0391acbe92de794013e0a67ce6157b402c6a0ca0a3a1740
+  data.tar.gz: e00ec46afd8e5d8ebef469c0a5d86a026562f8060e8abc95c4f3e89aa9351dc8961fe2d9d181aa4e8203056c74fb4aa8c4043f925b93a5b477c44541eec5ad9f

data/CHANGELOG.md

@@ -1,8 +1,22 @@
 ## [Unreleased]
 
+## [1.7.0] - 2024-06-12
+### Added
+- New feature: **Lock Access Strategy**: you can obtain a lock in different ways: `queued` (classic queued FIFO), `random` (get the lock immideatly if lock is free), and soon: `lifo` and `barrier`;
+  - `:queued` is used by default (classic `redis_queued_locks` behavior);
+  - `:random`: obtain a lock without checking the positions in the queue => if lock is free to obtain - it will be obtained;
+### Changed
+- Some logging refactorings, some instrumentation refactorings: the code that uses them is more readable and supportable;
+
+## [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

@@ -4,6 +4,8 @@
 
 Each lock request is put into the request queue (each lock is hosted by it's own queue separately from other queues) and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) (with requeue capabilities) which guarantees the request queue will never be stacked.
 
+In addition to the classic `queued` (FIFO) strategy RQL supports `random` (RANDOM) lock obtaining strategy when any acquirer from the lock queue can obtain the lock regardless the position in the queue.
+
 Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), logging and instrumentation.
 
 ---
@@ -32,6 +34,9 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
   - [locks_info](#locks_info---get-list-of-locks-with-their-info)
   - [queues_info](#queues_info---get-list-of-queues-with-their-info)
   - [clear_dead_requests](#clear_dead_requests)
+- [Lock Access Strategies](#lock-access-strategies)
+  - [queued](#lock-access-strategies)
+  - [random](#lock-access-strategies)
 - [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks)
 - [Logging](#logging)
 - [Instrumentation](#instrumentation)
@@ -69,6 +74,8 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 
 > Each lock request is put into the request queue (each lock is hosted by it's own queue separately from other queues) and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees that the request queue will never be stacked.
 
+> In addition to the classic "queued" (FIFO) strategy RQL supports "random" (RANDOM) lock obtaining strategy when any acquirer from the lock queue can obtain the lock regardless the position in the queue.
+
 **Soon**: detailed explanation.
 
 ---
@@ -150,9 +157,20 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - should be all blocks of code are timed by default;
   config.is_timed_by_default = false
 
+  # (symbol) (default: :queued)
+  # - Defines the way in which the lock should be obitained;
+  # - By default it is configured to obtain a lock in classic `queued` way:
+  #   you should wait your position in queue in order to obtain a lock;
+  # - Can be customized in methods `#lock` and `#lock!` via `:access_strategy` attribute (see method signatures of #lock and #lock! methods);
+  # - Supports different strategies:
+  #   - `:queued` (FIFO): the classic queued behavior (default), your lock will be obitaned if you are first in queue and the required lock is free;
+  #   - `:random` (RANDOM): obtain a lock without checking the positions in the queue (but with checking the limist,
+  #     retries, timeouts and so on). if lock is free to obtain - it will be obtained;
+  config.default_access_strategy = :queued
+
   # (symbol) (default: :wait_for_lock)
   # - Global default conflict strategy mode;
-  # - Can be customized in methods `#lock` and `#lock` via `:conflict_strategy` attribute (see method signatures of #lock and #lock! methods);
+  # - Can be customized in methods `#lock` and `#lock!` via `:conflict_strategy` attribute (see method signatures of #lock and #lock! methods);
   # - Conflict strategy is a logical behavior for cases when the process that obtained the lock want to acquire this lock again;
   # - Realizes "reentrant locks" abstraction (same process conflict / same process deadlock);
   # - By default uses `:wait_for_lock` strategy (classic way);
@@ -202,15 +220,15 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - should implement `debug(progname = nil, &block)` (minimal requirement) or be an instance of Ruby's `::Logger` class/subclass;
   # - supports `SemanticLogger::Logger` (see "semantic_logger" gem)
   # - at this moment the only debug logs are realised in following cases:
-  #   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
-  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
-  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
-  #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "acs_strat");
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
@@ -218,19 +236,19 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - adds additional debug logs;
   # - enables additional logs for each internal try-retry lock acquiring (a lot of logs can be generated depending on your retry configurations);
   # - it adds following logs in addition to the existing:
-  #   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "spc_status");
-  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "spc_status", "last_ext_ttl", "last_ext_ts");
-  #   - "[redis_queued_locks.try_lock.reentrant_lock__work_through]" (logs "lock_key", "queue_ttl", "acq_id", "spc_status", last_spc_ts);
-  #   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id)";
-  #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue");
-  #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id");
-  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "<current_lock_data>");
-  #   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
-  #   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", "last_ext_ttl", "last_ext_ts");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__work_through]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", last_spc_ts);
+  #   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id, "acs_strat")";
+  #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue");
+  #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
   config.log_lock_try = false
 
   # (default: false)
@@ -253,6 +271,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
 ```
 
@@ -306,14 +345,19 @@ def lock(
   raise_errors: false,
   fail_fast: false,
   conflict_strategy: config[:default_conflict_strategy],
+  access_strategy: config[:default_access_strategy],
   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,16 +390,28 @@ 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;
 - `fail_fast` - (optional) `[Boolean]`
-    - Should the required lock to be checked before the try and exit immidietly if lock is
-      already obtained;
-    - Should the logic exit immidietly after the first try if the lock was obtained
-      by another process while the lock request queue was initially empty;
-    - `false` by default;
-- `conflict_strategy` - (optional) - `[Symbol]``
+  - Should the required lock to be checked before the try and exit immidietly if lock is
+    already obtained;
+  - Should the logic exit immidietly after the first try if the lock was obtained
+    by another process while the lock request queue was initially empty;
+  - `false` by default;
+- `access_strategy` - (optional) - `[Symbol]`
+  - Defines the way in which the lock should be obitained (in queued way, in random way and so on);
+  - By default it is configured to obtain a lock in classic `:queued` way: you should wait your position in queue in order to obtain a lock;
+  - Supports following strategies:
+    - `:queued` (FIFO): (default) the classic queued behavior, your lock will be obitaned if you are first in queue and the required lock is free;
+    - `:random` (RANDOM): obtain a lock without checking the positions in the queue (but with checking the limist, retries, timeouts and so on).
+      if lock is free to obtain - it will be obtained;
+  - pre-configured in `config[:default_access_strategy]`;
+  - See [Lock Access Strategies](#lock-access-strategies) documentation section for details;
+- `conflict_strategy` - (optional) - `[Symbol]`
   - The conflict strategy mode for cases when the process that obtained the lock
     want to acquire this lock again;
   - By default uses `:wait_for_lock` strategy;
@@ -365,7 +421,7 @@ def lock(
     - `:extendable_work_through` - continue working under the lock **with** lock's TTL extension;
     - `:wait_for_lock` - (default) - work in classic way (with timeouts, retry delays, retry limits, etc - in classic way :));
     - `:dead_locking` - fail with deadlock exception;
-  - See [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) readme section for details;
+  - See [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) documentation section for details;
 - `identity` - (optional) `[String]`
   - An unique string that is unique per `RedisQueuedLock::Client` instance. Resolves the
     collisions between the same process_id/thread_id/fiber_id/ractor_id identifiers on different
@@ -377,9 +433,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 +458,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 +629,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
@@ -581,7 +652,51 @@ rql.lock("my_lock", queue_ttl: 5, timeout: 10_000, retry_count: nil)
  "rql:acq:123/456/567/685/374dd74329", # some other waiting process
  "rql:acq:123/456/567/683/374dd74322", # <== we are here (moved to the end of the queue)
 ]
+```
+
+- obtain a lock in `:random` way (with `:random` strategy): in `:random` strategy
+  any acquirer from the lcok queue can obtain the lock regardless of the position in the lock queue;
 
+```ruby
+# Current Process (process#1)
+rql.lock('my_lock', ttl: 2_000, access_strategy: :random)
+# => holds the lock
+
+# Another Process (process#2)
+rql.lock('my_lock', retry_delay: 7000, ttl: 4000, access_strategy: :random)
+# => the lock is not free, stay in a queue and retry...
+
+# Another Process (process#3)
+rql.lock('my_lock', retry_delay: 3000, ttl: 3000, access_strategy: :random)
+# => the lock is not free, stay in a queue and retry...
+
+# lock queue:
+[
+ "rql:acq:123/456/567/677/374dd74322", # process#1 (holds the lock)
+ "rql:acq:123/456/567/679/374dd74321", # process#2 (waiting for the lock, in retry)
+ "rql:acq:123/456/567/683/374dd74322", # process#3 (waiting for the lock, in retry)
+]
+
+# ... some period of time
+# -> process#1 => released the lock;
+# -> process#2 => delayed retry, waiting;
+# -> process#3 => preparing for retry (the delay is over);
+# lock queue:
+[
+ "rql:acq:123/456/567/679/374dd74321", # process#2 (waiting for the lock, DELAYED)
+ "rql:acq:123/456/567/683/374dd74322", # process#3 (trying to obtain the lock, RETRYING now)
+]
+
+# ... some period of time
+# -> process#2 => didn't have time to obtain the lock, delayed retry;
+# -> process#3 => holds the lock;
+# lock queue:
+[
+ "rql:acq:123/456/567/679/374dd74321", # process#2 (waiting for the lock, DELAYED)
+ "rql:acq:123/456/567/683/374dd74322", # process#3 (holds the lock)
+]
+
+# `process#3` is the last in queue, but has acquired the lock because his lock request "randomly" came first;
 ```
 
 ---
@@ -613,10 +728,15 @@ def lock!(
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
   instrument: nil,
+  instrumenter: config[:instrumenter],
+  access_strategy: config[:default_access_strategy],
   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 +917,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 +985,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 +1026,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 +1044,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 +1290,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;
 
@@ -1157,6 +1319,22 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 
 ---
 
+## Lock Access Strategies
+
+- **this documentation section is in progress**;
+- (little details for a context of the current implementation and feautres):
+  - defines the way in which the lock should be obitained;
+  - by default it is configured to obtain a lock in classic `queued` way: you should wait your position in queue in order to obtain a lock;
+  - can be customized in methods `#lock` and `#lock!` via `:access_strategy` attribute (see method signatures of #lock and #lock! methods);
+  - supports different strategies:
+    - `:queued` (FIFO): the classic queued behavior (default), your lock will be obitaned if you are first in queue and the required lock is free;
+    - `:random` (RANDOM): obtain a lock without checking the positions in the queue (but with checking the limist, retries, timeouts and so on). if lock is free to obtain - it will be obtained;
+  - for current implementation detalis check:
+    - [Configuration](#configuration) documentation: see `config.default_access_strategy` config docs;
+    - [#lock](#lock---obtain-a-lock) method documentation: see `access_strategy` attribute docs;
+
+---
+
 ## Dead locks and Reentrant locks
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
@@ -1182,34 +1360,34 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 - default logs (raised from `#lock`/`#lock!`):
 
 ```ruby
-"[redis_queued_locks.start_lock_obtaining]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.dead_score_reached__reset_acquier_position]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.start_lock_obtaining]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.dead_score_reached__reset_acquier_position]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
 "[redis_queued_locks.lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
-"[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
-"[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
-"[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.decrease_lock]" # (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id");
+"[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "acq_time");
+"[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "acq_time");
+"[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.decrease_lock]" # (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "acs_strat");
 ```
 
 - additional logs (raised from `#lock`/`#lock!` with `confg[:log_lock_try] == true`):
 
 ```ruby
-"[redis_queued_locks.try_lock.start]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.try_lock.rconn_fetched]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.try_lock.same_process_conflict_detected]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.try_lock.same_process_conflict_analyzed]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status");
-"[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status", "last_ext_ttl", "last_ext_ts");
-"[redis_queued_locks.try_lock.reentrant_lock__work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status", last_spc_ts);
-"[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status", "last_spc_ts");
-"[redis_queued_locks.try_lock.acq_added_to_queue]" # (logs "lock_key", "queue_ttl", "acq_id)";
-"[redis_queued_locks.try_lock.remove_expired_acqs]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.try_lock.get_first_from_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue");
-"[redis_queued_locks.try_lock.exit__queue_ttl_reached]" # (logs "lock_key", "queue_ttl", "acq_id");
-"[redis_queued_locks.try_lock.exit__no_first]" # (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "<current_lock_data>");
-"[redis_queued_locks.try_lock.exit__lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
-"[redis_queued_locks.try_lock.obtain__free_to_acquire]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.try_lock.start]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.rconn_fetched]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.same_process_conflict_detected]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.same_process_conflict_analyzed]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status");
+"[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", "last_ext_ttl", "last_ext_ts");
+"[redis_queued_locks.try_lock.reentrant_lock__work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", last_spc_ts);
+"[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", "last_spc_ts");
+"[redis_queued_locks.try_lock.acq_added_to_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.remove_expired_acqs]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.get_first_from_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue");
+"[redis_queued_locks.try_lock.exit__queue_ttl_reached]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.exit__no_first]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue", "<current_lock_data>");
+"[redis_queued_locks.try_lock.exit__lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
+"[redis_queued_locks.try_lock.obtain__free_to_acquire]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
 ```
 
 ---
@@ -1335,8 +1513,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);
   - `#lock_series` - acquire a series of locks:

data/lib/redis_queued_locks/acquier/acquire_lock/dequeue_from_lock_queue/log_visitor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.7.0
+module RedisQueuedLocks::Acquier::AcquireLock::DequeueFromLockQueue::LogVisitor
+  extend self
+
+  # @param logger [::Logger,#debug]
+  # @param log_sampled [Boolean]
+  # @param lock_key [String]
+  # @param queue_ttl [Integer]
+  # @param acquier_id [String]
+  # @param access_strategy [Symbol]
+  # @return [void]
+  #
+  # @api private
+  # @since 1.7.0
+  def dequeue_from_lock_queue(
+    logger,
+    log_sampled,
+    lock_key,
+    queue_ttl,
+    acquier_id,
+    access_strategy
+  )
+    return unless log_sampled
+
+    logger.debug do
+      "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue] " \
+      "lock_key => '#{lock_key}' " \
+      "queue_ttl => #{queue_ttl} " \
+      "acq_id => '#{acquier_id}' " \
+      "acs_strat => '#{access_strategy}"
+    end rescue nil
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.7.0
+module RedisQueuedLocks::Acquier::AcquireLock::DequeueFromLockQueue
+  require_relative 'dequeue_from_lock_queue/log_visitor'
+
+  # @param redis [RedisClient]
+  # @param logger [::Logger,#debug]
+  # @param lock_key [String]
+  # @param lock_key_queue [String]
+  # @param queue_ttl [Integer]
+  # @param acquier_id [String]
+  # @param access_strategy [Symbol]
+  # @param log_sampled [Boolean]
+  # @param instr_sampled [Boolean]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+  #
+  # @api private
+  # @since 1.7.0
+  def dequeue_from_lock_queue(
+    redis,
+    logger,
+    lock_key,
+    lock_key_queue,
+    queue_ttl,
+    acquier_id,
+    access_strategy,
+    log_sampled,
+    instr_sampled
+  )
+    result = redis.call('ZREM', lock_key_queue, acquier_id)
+    LogVisitor.dequeue_from_lock_queue(
+      logger, log_sampled,
+      lock_key, queue_ttl, acquier_id, access_strategy
+    )
+    RedisQueuedLocks::Data[ok: true, result: result]
+  end
+end