redis_queued_locks 1.8.0 → 1.10.0

data/README.md

@@ -35,12 +35,30 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
   - [queues_info](#queues_info---get-list-of-queues-with-their-info)
   - [clear_dead_requests](#clear_dead_requests)
   - [current_acquirer_id](#current_acquirer_id)
+  - [current_host_id](#current_host_id)
+  - [possible_host_ids](#possible_host_ids)
+- [Swarm Mode and Zombie Locks](#swarm-mode-and-zombie-locks)
+  - [work and usage preview (temporary example-based docs)](#work-and-usage-preview-temporary-example-based-docs)
+  - [How to Swarm](#how-to-swarm)
+    - [configuration](#)
+    - [swarm_status](#swarm_status)
+    - [swarm_info](#swarm_info)
+    - [swarmize!](#swarmize!)
+    - [deswarmize!](#deswarmize!)
+    - [probe_hosts](#probe_hosts)
+    - [flush_zobmies](#flush_zombies)
+  - [zombies_info](#zombies_info)
+  - [zombie_locks](#zombie_locks)
+  - [zombie_hosts](#zombie_hosts)
+  - [zombie_acquiers](#zombie_acquiers)
 - [Lock Access Strategies](#lock-access-strategies)
   - [queued](#lock-access-strategies)
   - [random](#lock-access-strategies)
-- [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks)
+- [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks)
 - [Logging](#logging)
+  - [Logging Configuration](#logging-configuration)
 - [Instrumentation](#instrumentation)
+  - [Instrumentation Configuration](#instrumentation-configuration)
   - [Instrumentation Events](#instrumentation-events)
 - [Roadmap](#roadmap)
 - [Contributing](#contributing)
@@ -244,35 +262,35 @@ 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", "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");
+  #   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat");
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
   # (default: false)
   # - 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", "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");
+  # - it adds following debug logs in addition to the existing:
+  #   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "spc_status");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_id", "acs_strat", "spc_status", last_spc_ts);
+  #   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat")";
+  #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "first_acq_id_in_queue");
+  #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_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", "hst_id", "acs_strat");
   config.log_lock_try = false
 
   # (default: false)
@@ -341,6 +359,8 @@ end
 - [queues_info](#queues_info---get-list-of-queues-with-their-info)
 - [clear_dead_requests](#clear_dead_requests)
 - [current_acquirer_id](#current_acquirer_id)
+- [current_host_id](#current_host_id)
+- [possible_host_ids](#possible_host_ids)
 
 ---
 
@@ -381,9 +401,11 @@ def lock(
   log_sampling_enabled: config[:log_sampling_enabled],
   log_sampling_percent: config[:log_sampling_percent],
   log_sampler: config[:log_sampler],
+  log_sample_this: false,
   instr_sampling_enabled: config[:instr_sampling_enabled],
   instr_sampling_percent: config[:instr_sampling_percent],
   instr_sampler: config[:instr_sampler],
+  instr_sample_this: false,
   &block
 )
 ```
@@ -447,7 +469,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) documentation section for details;
+  - See [Deadlocks and Reentrant locks](#deadlocks-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
@@ -503,6 +525,10 @@ 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]`;
+- `log_sample_this` - (optional) `[Boolean]`
+  - marks the method that everything should be logged despite the enabled log sampling;
+  - makes sense when log sampling is enabled;
+  - `false` by default;
 - `instr_sampling_enabled` - (optional) `[Boolean]`
   - enables **instrumentaion sampling**: only the configured percent of RQL cases will be instrumented;
   - disabled by default;
@@ -521,6 +547,10 @@ def lock(
   - 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]`;
+- `instr_sample_this` - (optional) `[Boolean]`
+  - marks the method that everything should be instrumneted despite the enabled instrumentation sampling;
+  - makes sense when instrumentation sampling is enabled;
+  - `false` by default;
 - `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 +588,7 @@ Return value:
     - `:extendable_conflict_work_through` - reentrant lock acquiring process with lock's TTL extension. Suitable for `conflict_strategy: :extendable_work_through`;
     - `:conflict_work_through` - reentrant lock acquiring process without lock's TTL extension. Suitable for `conflict_strategy: :work_through`;
     - `:dead_locking` - current process tries to acquire a lock that is already acquired by them. Suitalbe for `conflict_startegy: :dead_locking`;
-    - For more details see [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) readme section;
+    - For more details see [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks) readme section;
   - For successful lock obtaining:
     ```ruby
     {
@@ -566,6 +596,7 @@ Return value:
       result: {
         lock_key: String, # acquierd lock key ("rql:lock:your_lock_name")
         acq_id: String, # acquier identifier ("process_id/thread_id/fiber_id/ractor_id/identity")
+        hst_id: String, # host identifier ("process_id/thread_id/ractor_id/identity")
         ts: Float, # time (epoch) when lock was obtained (float, Time#to_f)
         ttl: Integer, # lock's time to live in milliseconds (integer)
         process: Symbol # which logical process has acquired the lock (:lock_obtaining, :extendable_conflict_work_through, :conflict_work_through, :conflict_dead_lock)
@@ -580,6 +611,7 @@ Return value:
       result: {
         lock_key: "rql:lock:my_lock",
         acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
+        acq_id: "rql:acq:26672/2280/2320/70ea5dbf10ea1056",
         ts: 1711909612.653696,
         ttl: 10000,
         process: :lock_obtaining # for custom conflict strategies may be: :conflict_dead_lock, :conflict_work_through, :extendable_conflict_work_through
@@ -655,6 +687,7 @@ rql.lock_info("my_lock")
 {
   "lock_key" => "rql:lock:my_lock",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+  "hst_id" => "rql:acq:123/456/678/374dd74324",
   "ts" => 123456789,
   "ini_ttl" => 123456,
   "rem_ttl" => 123440,
@@ -755,7 +788,7 @@ rql.lock('my_lock', retry_delay: 3000, ttl: 3000, access_strategy: :random)
   - (`RedisQueuedLocks::LockAlreadyObtainedError`) when `fail_fast` is `true` and lock is already obtained;
   - (`RedisQueuedLocks::LockAcquiermentTimeoutError`) `timeout` limit reached before lock is obtained;
   - (`RedisQueuedLocks::LockAcquiermentRetryLimitError`) `retry_count` limit reached before lock is obtained;
-  - (`RedisQueuedLocks::ConflictLockObtainError`) when `conflict_strategy: :dead_locking` is used and the "same-process-dead-lock" is happened (see [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) for details);
+  - (`RedisQueuedLocks::ConflictLockObtainError`) when `conflict_strategy: :dead_locking` is used and the "same-process-dead-lock" is happened (see [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks) for details);
 
 ```ruby
 def lock!(
@@ -780,9 +813,11 @@ def lock!(
   log_sampling_enabled: config[:log_sampling_enabled],
   log_sampling_percent: config[:log_sampling_percent],
   log_sampler: config[:log_sampler],
+  log_sample_this: false,
   instr_sampling_enabled: config[:instr_sampling_enabled],
   instr_sampling_percent: config[:instr_sampling_percent],
   instr_sampler: config[:instr_sampler],
+  instr_sample_this: false,
   &block
 )
 ```
@@ -800,6 +835,7 @@ See `#lock` method [documentation](#lock---obtain-a-lock).
 - lock data (`Hash<String,String|Integer>`):
   - `"lock_key"` - `string` - lock key in redis;
   - `"acq_id"` - `string` - acquier identifier (process_id/thread_id/fiber_id/ractor_id/identity);
+  - `"hst_id"` - `string` - host identifier (process_id/thread_id/ractor_id/identity);
   - `"ts"` - `numeric`/`epoch` - the time when lock was obtained;
   - `"init_ttl"` - `integer` - (milliseconds) initial lock key ttl;
   - `"rem_ttl"` - `integer` - (milliseconds) remaining lock key ttl;
@@ -822,6 +858,7 @@ rql.lock_info("your_lock_name")
 {
   "lock_key" => "rql:lock:your_lock_name",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+  "hst_id" => "rql:acq:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 4_999
@@ -837,6 +874,7 @@ rql.lock_info("your_lock_name")
 {
   "lock_key" => "rql:lock:your_lock_name",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+  "hst_id" => "rql:acq:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 4_999,
@@ -858,6 +896,7 @@ rql.lock_info("your_lock_name")
 {
   "lock_key" => "rql:lock:your_lock_name",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+  "hst_id" => "rql:acq:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 9_444,
@@ -943,6 +982,7 @@ rql.queued?("your_lock_name") # => true/false
 
 - release the concrete lock with lock request queue;
 - queue will be relased first;
+- has an alias: `#release_lock`;
 - accepts:
   - `lock_name` - (required) `[String]` - the lock name that should be released.
   - `:logger` - (optional) `[::Logger,#debug]`
@@ -963,6 +1003,10 @@ 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]`;
+  - `log_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be logged despite the enabled log sampling;
+    - makes sense when log sampling is enabled;
+    - `false` by default;
   - `:instr_sampling_enabled` - (optional) `[Boolean]`
     - enables **instrumentaion sampling**;
     - pre-configured in `config[:instr_sampling_enabled]`;
@@ -972,6 +1016,10 @@ rql.queued?("your_lock_name") # => true/false
   - `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]`;
+  - `instr_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be instrumneted despite the enabled instrumentation sampling;
+    - makes sense when instrumentation sampling is enabled;
+    - `false` by default;
 - if you try to unlock non-existent lock you will receive `ok: true` result with operation timings
   and `:nothing_to_release` result factor inside;
 
@@ -1010,6 +1058,7 @@ rql.unlock("your_lock_name")
 
 - release all obtained locks and related lock request queues;
 - queues will be released first;
+- has an alias: `#release_locks`;
 - accepts:
   - `:batch_size` - (optional) `[Integer]`
     - the size of batch of locks and lock queus that should be cleared under the one pipelined redis command at once;
@@ -1031,6 +1080,10 @@ 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]`;
+  - `log_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be logged despite the enabled log sampling;
+    - makes sense when log sampling is enabled;
+    - `false` by default;
   - `:instr_sampling_enabled` - (optional) `[Boolean]`
     - enables **instrumentaion sampling**;
     - pre-configured in `config[:instr_sampling_enabled]`;
@@ -1040,6 +1093,10 @@ rql.unlock("your_lock_name")
   - `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]`;
+  - `instr_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be instrumneted despite the enabled instrumentation sampling;
+    - makes sense when instrumentation sampling is enabled;
+    - `false` by default;
 - returns:
   - `[Hash<Symbol,Numeric>]` - Format: `{ ok: true, result: Hash<Symbol,Numeric> }`;
   - result data:
@@ -1090,6 +1147,10 @@ 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]`;
+  - `log_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be logged despite the enabled log sampling;
+    - makes sense when log sampling is enabled;
+    - `false` by default;
   - `:instr_sampling_enabled` - (optional) `[Boolean]`
     - enables **instrumentaion sampling**;
     - pre-configured in `config[:instr_sampling_enabled]`;
@@ -1099,6 +1160,10 @@ rql.clear_locks
   - `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]`;
+  - `instr_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be instrumneted despite the enabled instrumentation sampling;
+    - makes sense when instrumentation sampling is enabled;
+    - `false` by default;
 - 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);
@@ -1253,6 +1318,7 @@ rql.locks_info # or rql.locks_info(scan_size: 123)
    :status=>:alive,
    :info=>{
     "acq_id"=>"rql:acq:41478/4320/4340/4360/848818f09d8c3420",
+    "hst_id"=>"rql:hst:41478/4320/4360/848818f09d8c3420"
     "ts"=>1711607112.670343,
     "ini_ttl"=>15000,
     "rem_ttl"=>13998}},
@@ -1336,6 +1402,10 @@ 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]`;
+- `log_sample_this` - (optional) `[Boolean]`
+  - marks the method that everything should be logged despite the enabled log sampling;
+  - makes sense when log sampling is enabled;
+  - `false` by default;
 - `:instr_sampling_enabled` - (optional) `[Boolean]`
   - enables **instrumentaion sampling**;
   - pre-configured in `config[:instr_sampling_enabled]`;
@@ -1345,6 +1415,10 @@ Accepts:
 - `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]`;
+- `instr_sample_this` - (optional) `[Boolean]`
+  - marks the method that everything should be instrumneted despite the enabled instrumentation sampling;
+  - makes sense when instrumentation sampling is enabled;
+  - `false` by default;
 
 Returns: `{ ok: true, processed_queues: Set<String> }` returns the list of processed lock queues;
 
@@ -1367,6 +1441,8 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 
 #### #current_acquirer_id
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - get the current acquirer identifier in RQL notation that you can use for debugging purposes during the lock analyzation;
 - acquirer identifier format:
   ```ruby
@@ -1400,6 +1476,278 @@ rql.current_acquirer_id
 
 ---
 
+#### #current_host_id
+
+<sup>\[[back to top](#usage)\]</sup>
+
+- get a current host identifier in RQL notation that you can use for debugging purposes during the lock analyzis;
+- the host is a ruby worker (a combination of process/thread/ractor/identity) that is alive and can obtain locks;
+- the host is limited to `process`/`thread`/`ractor` (without `fiber`) combination cuz we have no abilities to extract
+  all fiber objects from the current ruby process when at least one ractor object is defined (**ObjectSpace** loses
+  abilities to extract `Fiber` and `Thread` objects after the any ractor is created) (`Thread` objects are analyzed
+  via `Thread.list` API which does not lose their abilites);
+- host identifier format:
+  ```ruby
+    "rql:hst:#{process_id}/#{thread_id}/#{ractor_id}/#{uniq_identity}"
+  ```
+- because of the moment that `#lock`/`#lock!` gives you a possibility to customize `process_id`,
+  `fiber_id`, `thread_id`, `ractor_id` and `unique identity` identifiers the `#current_host_id` method provides this possibility too
+  (except the `fiber_id` correspondingly);
+
+Accepts:
+
+- `process_id:` - (optional) `[Integer,Any]`
+  - `::Process.pid` by default;
+- `thread_id:` - (optional) `[Integer,Any]`;
+  - `::Thread.current.object_id` by default;
+- `ractor_id:` - (optional) `[Integer,Any]`;
+  - `::Ractor.current.object_id` by default;
+- `identity:` - (optional) `[String]`;
+  - this value is calculated once during `RedisQueuedLock::Client` instantiation and stored in `@uniq_identity`;
+  - this value can be accessed from `RedisQueuedLock::Client#uniq_identity`;
+  - [Configuration](#configuration) documentation: see `config[:uniq_identifier]`;
+  - [#lock](#lock---obtain-a-lock) method documentation: see `uniq_identifier`;
+
+```ruby
+rql.current_host_id
+
+# =>
+"rql:acq:38529/4500/4360/66093702f24a3129"
+```
+
+---
+
+#### #possible_host_ids
+
+<sup>\[[back to top](#usage)\]</sup>
+
+- return the list (`Array<String>`) of possible host identifiers that can be reached from the current ractor;
+- the host is a ruby worker (a combination of process/thread/ractor/identity) that is alive and can obtain locks;
+- the host is limited to `process`/`thread`/`ractor` (without `fiber`) combination cuz we have no abilities to extract
+  all fiber objects from the current ruby process when at least one ractor object is defined (**ObjectSpace** loses
+  abilities to extract `Fiber` and `Thread` objects after the any ractor is created) (`Thread` objects are analyzed
+  via `Thread.list` API which does not lose their abilites);
+- host identifier format:
+  ```ruby
+    "rql:hst:#{process_id}/#{thread_id}/#{ractor_id}/#{uniq_identity}"
+  ```
+
+Accepts:
+
+- `identity` - (optional) `[String]`;
+  - this value is calculated once during `RedisQueuedLock::Client` instantiation and stored in `@uniq_identity`;
+  - this value can be accessed from `RedisQueuedLock::Client#uniq_identity`;
+  - [Configuration](#configuration) documentation: see `config[:uniq_identifier]`;
+  - [#lock](#lock---obtain-a-lock) method documentation: see `uniq_identifier`;
+
+```ruby
+rql.possible_host_ids
+
+# =>
+[
+  "rql:hst:18814/2300/2280/5ce0c4582fc59c06", # process id / thread id / ractor id / uniq identity
+  "rql:hst:18814/2320/2280/5ce0c4582fc59c06", # ...
+  "rql:hst:18814/2340/2280/5ce0c4582fc59c06", # ...
+  "rql:hst:18814/2360/2280/5ce0c4582fc59c06", # ...
+  "rql:hst:18814/2380/2280/5ce0c4582fc59c06", # ...
+  "rql:hst:18814/2400/2280/5ce0c4582fc59c06"
+]
+```
+---
+
+## Swarm Mode and Zombie Locks
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+> Eliminate zombie locks with a swarm.
+
+**This documentation section is in progress!** (see the changelog and the usage preview for details at this moment)
+
+[(work and usage preview (temporary example-based docs))](#work-and-usage-preview-temporary-example-based-docs)
+
+- [How to Swarm](#how-to-swarm)
+  - [configuration](#)
+  - [swarm_status](#swarm_status)
+  - [swarm_info](#swarm_info)
+  - [swarmize!](#swarmize!)
+  - [deswarmize!](#deswarmize!)
+  - [probe_hosts](#probe_hosts)
+  - [flush_zobmies](#flush_zombies)
+- [zombies_info](#zombies_info)
+- [zombie_locks](#zombie_locks)
+- [zombie_hosts](#zombie_hosts)
+- [zombie_acquiers](#zombie_acquiers)
+
+<hr>
+
+#### Work and Usage Preview (temporary example-based docs)
+
+<sup>\[[back to top](#swarm-mode-and-zombie-locks)\]</sup>
+
+<details>
+  <summary>configuration</summary>
+
+  ```ruby
+  redis_client = RedisClient.config.new_pool # NOTE: provide your own RedisClient instance
+
+  clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
+    # NOTE: auto-swarm your RQL client after initalization (run swarm elements and their supervisor)
+    config.swarm.auto_swarm = false
+
+    # supervisor configs
+    config.swarm.supervisor.liveness_probing_period = 2 # NOTE: in seconds
+
+    # (probe_hosts) host probing configuration
+    config.swarm.probe_hosts.enabled_for_swarm = true # NOTE: run host-probing from or not
+    config.swarm.probe_hosts.probe_period = 2 # NOTE: (in seconds) the period of time when the probing process is triggered
+    # (probe_hosts) individual redis config
+    config.swarm.probe_hosts.redis_config.sentinel = false # NOTE: individual redis config
+    config.swarm.probe_hosts.redis_config.pooled = false # NOTE: individual redis config
+    config.swarm.probe_hosts.redis_config.config = {} # NOTE: individual redis config
+    config.swarm.probe_hosts.redis_config.pool_config = {} # NOTE: individual redis config
+
+    # (flush_zombies) zombie flushing configuration
+    config.swarm.flush_zombies.enabled_for_swarm = true # NOTE: run zombie flushing or not
+    config.swarm.flush_zombies.zombie_flush_period = 10 # NOTE: (in seconds) period of time when the zombie flusher is triggered
+    config.swarm.flush_zombies.zombie_ttl = 15_000 # NOTE: (in milliseconds) when the lock/host/acquier is considered a zombie
+    config.swarm.flush_zombies.zombie_lock_scan_size = 500 # NOTE: scan sizec during zombie flushing
+    config.swarm.flush_zombies.zombie_queue_scan_size = 500 # NOTE: scan sizec during zombie flushing
+    # (flush_zombies) individual redis config
+    config.swarm.flush_zombies.redis_config.sentinel = false # NOTE: individual redis config
+    config.swarm.flush_zombies.redis_config.pooled = false # NOTE: individual redis config
+    config.swarm.flush_zombies.redis_config.config = {} # NOTE: individual redis config
+    config.swarm.flush_zombies.redis_config.pool_config = {} # NOTE: individual redis config
+  end
+  ```
+</details>
+
+<details>
+  <summary>seed a zombie</summary>
+
+  - obtain some long living lock and kill the host process which will lead the lock becoming a zombie:
+
+  ```ruby
+  daiver => ~/Projects/redis_queued_locks  master [$]
+  ➜ bin/console
+  [1] pry(main)> rql = RedisQueuedLocks::Client.new(RedisClient.new);
+  [2] pry(main)> rql.swarmize!
+  /Users/daiver/Projects/redis_queued_locks/lib/redis_queued_locks/swarm/flush_zombies.rb:107: warning: Ractor is experimental, and the behavior may change in future versions of Ruby! Also there are many implementation issues.
+  => {:ok=>true, :result=>:swarming}
+  [3] pry(main)> rql.lock('kekpek', ttl: 1111111111)
+  => {:ok=>true,
+   :result=>
+    {:lock_key=>"rql:lock:kekpek",
+     :acq_id=>"rql:acq:17580/2260/2380/2280/3f16b93973612580",
+     :hst_id=>"rql:hst:17580/2260/2280/3f16b93973612580",
+     :ts=>1720305351.069259,
+     :ttl=>1111111111,
+     :process=>:lock_obtaining}}
+  [4] pry(main)> exit
+  ```
+</details>
+
+<details>
+  <summary>find zombies</summary>
+
+  - start another process, fetch the swarm info, see that our last process is a zombie now and their hosted lock is a zombie too:
+
+  ```ruby
+  daiver => ~/Projects/redis_queued_locks  master [$] took 27.2s
+  ➜ bin/console
+  [1] pry(main)> rql = RedisQueuedLocks::Client.new(RedisClient.new);
+  [2] pry(main)> rql.swarm_info
+  => {"rql:hst:17580/2260/2280/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 12897/262144 +0300, :last_probe_score=>1720305353.0491982},
+   "rql:hst:17580/2300/2280/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 211107/4194304 +0300, :last_probe_score=>1720305353.0503318},
+   "rql:hst:17580/2320/2280/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 106615/2097152 +0300, :last_probe_score=>1720305353.050838},
+   "rql:hst:17580/2260/2340/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 26239/524288 +0300, :last_probe_score=>1720305353.050047},
+   "rql:hst:17580/2300/2340/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 106359/2097152 +0300, :last_probe_score=>1720305353.050716},
+   "rql:hst:17580/2320/2340/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 213633/4194304 +0300, :last_probe_score=>1720305353.050934},
+   "rql:hst:17580/2360/2280/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 214077/4194304 +0300, :last_probe_score=>1720305353.05104},
+   "rql:hst:17580/2360/2340/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 214505/4194304 +0300, :last_probe_score=>1720305353.051142},
+   "rql:hst:17580/2400/2280/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 53729/1048576 +0300, :last_probe_score=>1720305353.05124},
+   "rql:hst:17580/2400/2340/3f16b93973612580"=>{:zombie=>true, :last_probe_time=>2024-07-07 01:35:53 3365/65536 +0300, :last_probe_score=>1720305353.0513458}}
+  [3] pry(main)> rql.swarm_status
+  => {:auto_swarm=>false,
+   :supervisor=>{:running=>false, :state=>"non_initialized", :observable=>"non_initialized"},
+   :probe_hosts=>{:enabled=>true, :thread=>{:running=>false, :state=>"non_initialized"}, :main_loop=>{:running=>false, :state=>"non_initialized"}},
+   :flush_zombies=>{:enabled=>true, :ractor=>{:running=>false, :state=>"non_initialized"}, :main_loop=>{:running=>false, :state=>"non_initialized"}}}
+  [4] pry(main)> rql.zombies_info
+  => {:zombie_hosts=>
+    #<Set:
+     {"rql:hst:17580/2260/2280/3f16b93973612580",
+      "rql:hst:17580/2300/2280/3f16b93973612580",
+      "rql:hst:17580/2320/2280/3f16b93973612580",
+      "rql:hst:17580/2260/2340/3f16b93973612580",
+      "rql:hst:17580/2300/2340/3f16b93973612580",
+      "rql:hst:17580/2320/2340/3f16b93973612580",
+      "rql:hst:17580/2360/2280/3f16b93973612580",
+      "rql:hst:17580/2360/2340/3f16b93973612580",
+      "rql:hst:17580/2400/2280/3f16b93973612580",
+      "rql:hst:17580/2400/2340/3f16b93973612580"}>,
+   :zombie_acquirers=>#<Set: {"rql:acq:17580/2260/2380/2280/3f16b93973612580"}>,
+   :zombie_locks=>#<Set: {"rql:lock:kekpek"}>}
+  [5] pry(main)> rql.zombie_locks
+  => #<Set: {"rql:lock:kekpek"}>
+  [6] pry(main)> rql.zombie_acquiers
+  => #<Set: {"rql:acq:17580/2260/2380/2280/3f16b93973612580"}>
+  [7] pry(main)> rql.zombie_hosts
+  => #<Set:
+   {"rql:hst:17580/2260/2280/3f16b93973612580",
+    "rql:hst:17580/2300/2280/3f16b93973612580",
+    "rql:hst:17580/2320/2280/3f16b93973612580",
+    "rql:hst:17580/2260/2340/3f16b93973612580",
+    "rql:hst:17580/2300/2340/3f16b93973612580",
+    "rql:hst:17580/2320/2340/3f16b93973612580",
+    "rql:hst:17580/2360/2280/3f16b93973612580",
+    "rql:hst:17580/2360/2340/3f16b93973612580",
+    "rql:hst:17580/2400/2280/3f16b93973612580",
+    "rql:hst:17580/2400/2340/3f16b93973612580"}>
+  ```
+</details>
+
+<details>
+  <summary>kill zombies in a background</summary>
+
+  - swarmize the new current ruby process that should run the flush zombies element that will drop zombie locks, zombie hosts and their lock requests in a background:
+
+  ```ruby
+  [8] pry(main)> rql.swarmize!
+  /Users/daiver/Projects/redis_queued_locks/lib/redis_queued_locks/swarm/flush_zombies.rb:107: warning: Ractor is experimental, and the behavior may change in future versions of Ruby! Also there are many implementation issues.
+  => {:ok=>true, :result=>:swarming}
+  [9] pry(main)> rql.swarm_info
+  => {"rql:hst:17752/2260/2280/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 4012577/4194304 +0300, :last_probe_score=>1720305399.956673},
+   "rql:hst:17752/2300/2280/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 4015233/4194304 +0300, :last_probe_score=>1720305399.9573061},
+   "rql:hst:17752/2320/2280/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 4016755/4194304 +0300, :last_probe_score=>1720305399.957669},
+   "rql:hst:17752/2260/2340/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 1003611/1048576 +0300, :last_probe_score=>1720305399.957118},
+   "rql:hst:17752/2300/2340/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 2008027/2097152 +0300, :last_probe_score=>1720305399.957502},
+   "rql:hst:17752/2320/2340/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 2008715/2097152 +0300, :last_probe_score=>1720305399.95783},
+   "rql:hst:17752/2360/2280/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 4018063/4194304 +0300, :last_probe_score=>1720305399.9579809},
+   "rql:hst:17752/2360/2340/89beef198021f16d"=>{:zombie=>false, :last_probe_time=>2024-07-07 01:36:39 1004673/1048576 +0300, :last_probe_score=>1720305399.9581308}}
+  [10] pry(main)> rql.swarm_status
+  => {:auto_swarm=>false,
+   :supervisor=>{:running=>true, :state=>"sleep", :observable=>"initialized"},
+   :probe_hosts=>{:enabled=>true, :thread=>{:running=>true, :state=>"sleep"}, :main_loop=>{:running=>true, :state=>"sleep"}},
+   :flush_zombies=>{:enabled=>true, :ractor=>{:running=>true, :state=>"running"}, :main_loop=>{:running=>true, :state=>"sleep"}}}
+  [11] pry(main)> rql.zombies_info
+  => {:zombie_hosts=>#<Set: {}>, :zombie_acquirers=>#<Set: {}>, :zombie_locks=>#<Set: {}>}
+  [12] pry(main)> rql.zombie_acquiers
+  => #<Set: {}>
+  [13] pry(main)> rql.zombie_hosts
+  => #<Set: {}>
+  [14] pry(main)>
+  ```
+</details>
+
+<details>
+  <summary>swarm hosts key in Redis</summary>
+
+  ```ruby
+  "rql:swarm:hsts"
+  ```
+</details>
+
+---
+
 ## Lock Access Strategies
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
@@ -1418,7 +1766,7 @@ rql.current_acquirer_id
 
 ---
 
-## Dead locks and Reentrant locks
+## Deadlocks and Reentrant locks
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
@@ -1440,37 +1788,110 @@ rql.current_acquirer_id
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
+- [Logging Configuration](#logging-configuration)
+
+
 - default logs (raised from `#lock`/`#lock!`):
 
 ```ruby
-"[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", "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");
+"[redis_queued_locks.start_lock_obtaining]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.dead_score_reached__reset_acquier_position]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time");
+"[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "acq_time");
+"[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "acq_time");
+"[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.decrease_lock]" # (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_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", "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");
+"[redis_queued_locks.try_lock.start]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.try_lock.rconn_fetched]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.try_lock.same_process_conflict_detected]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.try_lock.same_process_conflict_analyzed]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "spc_status");
+"[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_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", "hst_id", "acs_strat", "spc_status", "last_spc_ts");
+"[redis_queued_locks.try_lock.acq_added_to_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.try_lock.remove_expired_acqs]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.try_lock.get_first_from_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "first_acq_id_in_queue");
+"[redis_queued_locks.try_lock.exit__queue_ttl_reached]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+"[redis_queued_locks.try_lock.exit__no_first]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_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", "hst_id", "acs_strat");
+```
+
+---
+
+### Logging Configuration
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+**NOTICE**: logging can be sampled via:
+- `config.log_samplign_enabled = true` (**false** by default);
+- `config.log_sampler = RedisQueuedLocks::Logging::Sampler` (used by default);
+- see **RedisQueuedLocks::Logging::Sampler** implementation in source code for customization details;
+
+```ruby
+# (default: RedisQueuedLocks::Logging::VoidLogger)
+# - the logger object;
+# - 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", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+#   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+#   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
+#   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+# - by default uses VoidLogger that does nothing;
+config.logger = RedisQueuedLocks::Logging::VoidLogger
+
+# (default: false)
+# - 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 debug logs in addition to the existing:
+#   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "spc_status");
+#   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_id", "acs_strat", "spc_status", last_spc_ts);
+#   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat")";
+#   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "first_acq_id_in_queue");
+#   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+#   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_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", "hst_id", "acs_strat");
+config.log_lock_try = false
+
+# (default: false)
+# - 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> configs;
+config.log_sampling_enabled = false
+
+# (default: 15)
+# - 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;
+config.log_sampling_percent = 15
+
+# (default: 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);
+config.log_sampler = RedisQueuedLocks::Logging::Sampler
 ```
 
 ---
@@ -1480,9 +1901,12 @@ rql.current_acquirer_id
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - [Instrumentation Events](#instrumentation-events)
+- [Instrumentation Configuration](#instrumentation-configuration)
 
 An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).
 
+Instrumentation can be sampled. See [Instrumentation Configuration](#instrumentation-configuration) section for details.
+
 Instrumenter object should provide `notify(event, payload)` method with the following signarue:
 
 - `event` - `string`;
@@ -1498,6 +1922,48 @@ By default `RedisQueuedLocks::Client` is configured with the void notifier (whic
 
 ---
 
+### Instrumentation Configuration
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+**NOTICE**: instrumentation can be sampled via:
+- `config.instr_sampling_enabled = true` (**false** by default);
+- `config.instr_sampler = RedisQueuedLocks::Instrument::Sampler` (used by default);
+- see **RedisQueuedLocks::Instrument::Sampler** implementation in source code for customization details;
+
+```ruby
+# (default: RedisQueuedLocks::Instrument::VoidNotifier)
+# - instrumentation layer;
+# - you can provide your own instrumenter that should realize `#notify(event, payload = {})` interface:
+#   - event: <string> requried;
+#   - payload: <hash> requried;
+# - disabled by default via `VoidNotifier`;
+config.instrumenter = RedisQueuedLocks::Instrument::ActiveSupport
+
+# (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
+```
+
+---
+
 ### Instrumentation Events
 
 <sup>\[[back to top](#instrumentation)\]</sup>
@@ -1520,6 +1986,7 @@ Detalized event semantics and payload structure:
   - payload:
     - `:ttl` - `integer`/`milliseconds` - lock ttl;
     - `:acq_id` - `string` - lock acquier identifier;
+    - `:hst_id` - `string` - lock's host identifier;
     - `:lock_key` - `string` - lock name;
     - `:ts` - `numeric`/`epoch` - the time when the lock was obtaiend;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
@@ -1532,6 +1999,7 @@ Detalized event semantics and payload structure:
     - `:lock_key` - `string` - lock name;
     - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
     - `:acq_id` - `string` - lock acquier identifier;
+    - `:hst_id` - `string` - lock's host identifier;
     - `:ts` - `numeric`/`epoch` - the time when the lock was obtaiend as extendable reentrant lock;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
     - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
@@ -1543,6 +2011,7 @@ Detalized event semantics and payload structure:
     - `:lock_key` - `string` - lock name;
     - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
     - `:acq_id` - `string` - lock acquier identifier;
+    - `:hst_id` - `string` - lock's host identifier;
     - `:ts` - `numeric`/`epoch` - the time when the lock was obtaiend as reentrant lock;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
     - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
@@ -1554,6 +2023,7 @@ Detalized event semantics and payload structure:
     - `:hold_time` - `float`/`milliseconds` - lock hold time;
     - `:ttl` - `integer`/`milliseconds` - lock ttl;
     - `:acq_id` - `string` - lock acquier identifier;
+    - `:hst_id` - `string` - lock's host identifier;
     - `:lock_key` - `string` - lock name;
     - `:ts` - `numeric`/`epoch` - the time when lock was obtained;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
@@ -1567,6 +2037,7 @@ Detalized event semantics and payload structure:
     - `:hold_time` - `float`/`milliseconds` - lock hold time;
     - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
     - `:acq_id` - `string` - lock acquier identifier;
+    - `:hst_id` - `string` - lock's host identifier;
     - `:ts` - `numeric`/`epoch` - the time when the lock was obtaiend as reentrant lock;
     - `:lock_key` - `string` - lock name;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
@@ -1596,6 +2067,12 @@ Detalized event semantics and payload structure:
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - **Major**:
+  - Swarm:
+    - circuit-breaker for long-living failures of your infrastructure inside the swarm elements and supervisor:
+      the supervisor will stop (for some period of time or while the some factor will return `true`)
+      trying to ressurect unexpectedly terminated swarm elements, and will notify about this;
+    - swarm logs (thread/ractor has some limitations so the initial implementation does not include swarm logging);
+    - swarm instrumentation (thread/ractor has some limitations so the initial implementation does not include swarm instrumentation);
   - lock request prioritization;
   - **strict redlock algorithm support** (support for many `RedisClient` instances);
   - `#lock_series` - acquire a series of locks: