redis_queued_locks 1.19.0 → 1.21.0

data/README.md

@@ -10,7 +10,7 @@ In addition to the classic `queued` (FIFO) strategy RQL supports `random` (RANDO
 
 Supports `Read`/`Write` locks and `Reentrant` locks.
 
-Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), **zombie locks elimination**, logging and instrumentation (and much more).
+Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), **zombie locks elimination**, **[lock indexing](#lock-index)**, logging and instrumentation (and much more).
 
 ---
 
@@ -47,6 +47,7 @@ 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)
+  - [reindex_locks](#reindex_locks)
   - [current_acquirer_id](#current_acquirer_id)
   - [current_host_id](#current_host_id)
   - [possible_host_ids](#possible_host_ids)
@@ -64,6 +65,9 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
   - [zombie_locks](#zombie_locks)
   - [zombie_hosts](#zombie_hosts)
   - [zombie_acquirers](#zombie_acquirers)
+- [Lock Index](#lock-index)
+  - [Lock Index Performance](#lock-index-performance)
+  - [Lock Index Size](#lock-index-size)
 - [Lock Access Strategies](#lock-access-strategies)
   - [queued](#lock-access-strategies)
   - [random](#lock-access-strategies)
@@ -75,6 +79,7 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
   - [Instrumentation Configuration](#instrumentation-configuration)
   - [Instrumentation Events](#instrumentation-events)
     - ["redis_queued_locks.lock_obtained"](#redis_queued_lockslock_obtained)
+    - ["redis_queued_locks.lock_obtaining_failed"](#redis_queued_lockslock_obtaining_failed)
     - ["redis_queued_locks.extendable_reentrant_lock_obtained"](#redis_queued_locksextendable_reentrant_lock_obtained)
     - ["redis_queued_locks.reentrant_lock_obtained"](#redis_queued_locksreentrant_lock_obtained)
     - ["redis_queued_locks.lock_hold_and_release"](#redis_queued_lockslock_hold_and_release)
@@ -85,6 +90,9 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
     - ["redis_queued_locks.explicit_read_lock_release"](#redis_queued_locksexplicit_read_lock_release)
     - ["redis_queued_locks.explicit_all_locks_release"](#redis_queued_locksexplicit_all_locks_release)
     - ["redis_queued_locks.release_locks_of"](#redis_queued_locksrelease_locks_of)
+    - ["redis_queued_locks.extend_lock_ttl"](#redis_queued_locksextend_lock_ttl)
+    - ["redis_queued_locks.clear_dead_requests"](#redis_queued_locksclear_dead_requests)
+    - ["redis_queued_locks.reindex_locks"](#redis_queued_locksreindex_locks)
 - [Roadmap](#roadmap)
 - [Build and Develop](#build-and-develop)
 - [Contributing](#contributing)
@@ -188,14 +196,19 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
 
   # (seconds) (supports nil)
   # - nil means "no timeout" and you are only limited by "retry_count" config;
+  # - 0 is the same as nil (no timeout);
   config['try_to_lock_timeout'] = 10
 
   # (milliseconds) (default: 5_000)
   # - lock's time to live
+  # - should be a positive Integer
   config['default_lock_ttl'] = 5_000
 
   # (seconds) (default: 15)
   # - lock request timeout. after this timeout your lock request in queue will be requeued with new position (at the end of the queue);
+  # - (the enabled lock index) the lock request queue lives as long as its latest lock request (the queue TTL is refreshed with
+  #   the queue ttl on each lock request): queues of dead acquirers expire by themselves;
+  # - should be a positive Integer
   config['default_queue_ttl'] = 15
 
   # (boolean) (default: false)
@@ -252,24 +265,35 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
 
   # (default: 100)
   # - how many items will be released at a time in #clear_locks and in #clear_dead_requests (uses SCAN);
+  # - (the enabled lock index) how many locks (lock names of the lock index) will be processed at a time
+  #   (the ZSCAN count of the lock index pass);
   # - affects the performance of your Redis and Ruby Application (configure thoughtfully);
+  # - should be a positive Integer
   config['lock_release_batch_size'] = 100
 
   # (default: 300)
   # - how many items will be released at a time in #clear_locks_of and in #clear_current_locks methods (uses SCAN for batch extraction and DEL for batch deletion);
+  # - (the enabled lock index) how many locks (lock names of the lock index) will be processed at a time
+  #   (the ZSCAN count of the lock index pass, DEL for batch deletion);
   # - affects the ruby's memory (cuz this batch will be stored in Set object in first, and then will be splatted to the DEL redis method invocation) (configure thoughtfully);
   # - affects the performance of your Redis (configure thoughtfully);
+  # - should be a positive Integer
   config['clear_locks_of__lock_scan_size'] = 300
 
   # (default: 300)
-  # - how many queues will be SCAN'ned at a time in #clear_locks_of and in #clear_current_locks methods (uses SCAN);
+  # - how many lock queues will be processed in one round trip in #clear_locks_of and in #clear_current_locks methods
+  #   (lock queues are found by the same SCAN pass as locks or derived from the lock names of the same lock index pass);
   # - affects the performance of your Redis (configure thoughtfully);
+  # - should be a positive Integer
   config['clear_locks_of__queue_scan_size'] = 300
 
   # (default: 500)
   # - how many items should be extracted from redis during the #locks, #queues, #keys
   #   #locks_info, and #queues_info operations (uses SCAN);
+  # - (the enabled lock index) how many locks (lock names of the lock index) should be processed at a time
+  #   (the ZSCAN count of the lock index pass);
   # - affects the performance of your Redis and Ruby Application (configure thoughtfully);
+  # - should be a positive Integer
   config['key_extraction_batch_size'] = 500
 
   # (default: 1 day)
@@ -277,6 +301,22 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - used for `#clear_dead_requests` as default vaule of `:dead_ttl` option;
   config['dead_request_ttl'] = (1 * 24 * 60 * 60 * 1000) # one day in milliseconds
 
+  # (boolean) (default: false)
+  # - find locks via the lock index (`rql:index:locks`) instead of the full Redis keyspace `SCAN` in all lock-iterating operations
+  #   (the swarm, #locks, #queues, #keys, #clear_locks, #clear_locks_of, #clear_dead_requests, ...);
+  # - the lock index is maintained by the lock acquirement itself only when it is enabled;
+  # - the client-wide mode (not a per-call option): use the same value on all your processes that share the Redis database;
+  #   after enabling invoke `#reindex_locks` once (see the "Lock Index" documentation section);
+  config['lock_index_enabled'] = false
+
+  # (milliseconds) (default: 60_000)
+  # - the lock index grace period: the lock name stays in the lock index (`rql:index:locks`) for this period
+  #   after the expiration of all its keys (see the "Lock Index" documentation section);
+  # - tolerance of the client clock skew between your hosts and of the network latency: should be greater than
+  #   the maximal clock skew between your hosts plus the network latency;
+  # - used only with the enabled lock index (`config['lock_index_enabled']`);
+  config['lock_index_grace_period'] = 60_000
+
   # (default: RedisQueuedLocks::Instrument::VoidNotifier)
   # - instrumentation layer;
   # - you can provide your own instrumenter that should realize `#notify(event, payload = {})` interface:
@@ -299,15 +339,28 @@ client = 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", "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_acquirer_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");
+  #   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+  #   - "[redis_queued_locks.lock_obtaining_failed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time", "result");
+  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+  #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.start_lock_series_obtaining]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.lock_series_obtained]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+  #   - "[redis_queued_locks.expire_lock_series]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.explicit_lock_release]" (logs "lock_key", "lock_key_queue", "rel_time", "at");
+  #   - "[redis_queued_locks.explicit_read_lock_release]" (logs "lock_key", "acq_id", "lock_res", "rel_time", "at");
+  #   - "[redis_queued_locks.explicit_all_locks_release]" (logs "at", "rel_time", "rel_key_cnt");
+  #   - "[redis_queued_locks.release_locks_of]" (logs "at", "hst_id", "acq_id", "rel_time", "rel_key_cnt", "tch_queue_cnt");
+  #   - "[redis_queued_locks.extend_lock_ttl]" (logs "lock_key", "rw_mode", "all_read_locks", "ext_ttl", "extended_locks_count", "ext_time", "at");
+  #   - "[redis_queued_locks.clear_dead_requests]" (logs "dead_ttl", "prc_queue_cnt", "rel_time", "at");
+  #   - "[redis_queued_locks.reindex_locks]" (logs "idx_key_cnt", "idx_time", "at");
+  #   - "rw_mode" is the requested lock mode ('write'/'read'), the held lock mode for "expire_lock" and "decrease_lock",
+  #     the mode of the series for lock series logs;
   # - by default uses VoidLogger that does nothing;
   config['logger'] = RedisQueuedLocks::Logging::VoidLogger
 
@@ -315,19 +368,25 @@ client = 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 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");
+  #   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "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", "rw_mode", "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", "rw_mode", "spc_status", "last_spc_ts");
+  #   - "[redis_queued_locks.try_lock.single_process_lock_conflict__lock_upgrade]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "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", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "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", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "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", "rw_mode", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.exit__write_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
+  #   - "[redis_queued_locks.try_lock.exit__read_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
+  #   - "[redis_queued_locks.try_lock.exit__read_lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue");
+  #   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "rw_mode" is the requested lock mode ('write'/'read');
   config['log_lock_try'] = false
 
   # (default: false)
@@ -338,7 +397,7 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
 
   # (default: 15)
   # - the percent of cases that should be logged;
-  # - take an effect when <config['log_sampling_enalbed']> is true;
+  # - take an effect when <config['log_sampling_enabled']> is true;
   # - works in tandem with <config['log_sampling_enabled']> and <config['log_sampler']> configs;
   config['log_sampling_percent'] = 15
 
@@ -355,11 +414,11 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - 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 <config['instr_sampler']>;
-  config['nstr_sampling_enabled'] = false
+  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;
+  # - take an effect when <config['instr_sampling_enabled']> is true;
   # - works in tandem with <config['instr_sampling_enabled']> and <config['instr_sampler']> configs;
   config['instr_sampling_percent'] = 15
 
@@ -381,15 +440,18 @@ end
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - [lock](#lock---obtain-a-lock)
-- [lock!](#lock---exeptional-lock-obtaining)
+- [lock!](#lock---exceptional-lock-obtaining)
 - [lock_series](#lock_series---poc-acquire-a-series-of-locks) (PoC)
 - [lock_series!](#lock_series---poc-exceptional-lock_series) (PoC)
 - [lock_info](#lock_info)
 - [queue_info](#queue_info)
 - [locked?](#locked)
 - [queued?](#queued)
-- [unlock](#unlock---release-a-lock)
-- [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
+- [unlock](#unlock---release-a-lock) (aka `release_lock`)
+- [unlock_read](#unlock_read---release-the-read-lock-of-the-current-acquirer) (aka `release_read_lock`)
+- [clear_locks](#clear_locks---release-all-locks-and-lock-queues) (aka `release_locks`)
+- [clear_locks_of](#clear_locks_of) (aka `release_locks_of`)
+- [clear_current_locks](#clear_current_locks) (aka `release_current_locks`)
 - [extend_lock_ttl](#extend_lock_ttl)
 - [locks](#locks---get-list-of-obtained-locks)
 - [queues](#queues---get-list-of-lock-request-queues)
@@ -397,10 +459,15 @@ end
 - [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)
+- [reindex_locks](#reindex_locks)
 - [current_acquirer_id](#current_acquirer_id)
 - [current_host_id](#current_host_id)
 - [possible_host_ids](#possible_host_ids)
 
+The numeric options of the methods (ttls, timeouts, retries, scan and batch sizes, zombie ttl) are validated with the same
+types and ranges as their `config` keys: `Integer` values only (`timeout: 0.5` is rejected), `RedisQueuedLocks::ArgumentError`
+(`RedisQueuedLocks::SwarmArgumentError` for the swarm methods) otherwise.
+
 ---
 
 #### #lock - obtain a lock
@@ -411,6 +478,10 @@ end
 - If block is passed:
   - the obtained lock will be released after the block execution or the lock's ttl (what will happen first);
     - if you want to timeout (fail with timeout) the block execution with lock's TTL use `timed: true` option;
+    - (limitation) the write lock is released after the block without an owner check: if the block (without `timed: true`)
+      runs longer than the lock's ttl, the expired lock can be already obtained by another acquirer and the release
+      deletes that lock (the same for the ttl decrease of `:extendable_work_through` reentrant locks); use `timed: true`
+      or extend the lock (`#extend_lock_ttl`) for long blocks (read locks are released per acquirer and are not affected);
   - the block's result will be returned;
 - If block is not passed:
   - the obtained lock will be released after lock's ttl;
@@ -421,6 +492,7 @@ def lock(
   lock_name,
   ttl: config['default_lock_ttl'],
   queue_ttl: config['default_queue_ttl'],
+  lock_index_grace_period: config['lock_index_grace_period'],
   timeout: config['try_to_lock_timeout'],
   timed: config['is_timed_by_default'],
   retry_count: config['retry_count'],
@@ -454,15 +526,29 @@ def lock(
   - Lock name to be obtained.
 - `ttl` - (optional) - [Integer]
   - Lock's time to live (in milliseconds);
+  - should be a positive `Integer` (write and read locks);
   - pre-configured in `config['default_lock_ttl']`;
 - `queue_ttl` - (optional) `[Integer]`
   - Lifetime of the acuier's lock request. In seconds.
+  - (the enabled lock index) the lock request queue lives as long as its latest lock request (the queue TTL is refreshed
+    on each lock request);
   - pre-configured in `config['default_queue_ttl']`;
+- `lock_index_grace_period` - (optional) `[Integer]`
+  - The lock index grace period (in milliseconds): the lock name stays in the lock index for this period after the expiration
+    of all its keys (tolerance of the client clock skew between your hosts and of the network latency);
+  - used only with the enabled lock index (`config['lock_index_enabled']`, the client-wide mode);
+  - see the [Lock Index](#lock-index) documentation section;
+  - pre-configured in `config['lock_index_grace_period']`;
 - `timeout` - (optional) `[Integer,NilClass]`
   - Time period a client should try to acquire the lock (in seconds). Nil means "without timeout".
+  - `0` is the same as `nil` (without timeout);
   - pre-configured in `config['try_to_lock_timeout']`;
+  - the timeout can not be swallowed by `rescue` of your logger/instrumenter (see `timed` below);
 - `timed` - (optiona) `[Boolean]`
   - Limit the invocation time period of the passed block of code by the lock's TTL.
+  - the block is interrupted by an internal `RedisQueuedLocks::Exception` (an `::Exception`, like `Timeout::ExitException` of Ruby's `Timeout`): `rescue => e`,
+    `rescue StandardError`, `rescue Timeout::Error` and `rescue nil` inside the block can not swallow it (only `rescue Exception`),
+    `ensure` of the block still runs;
   - pre-configured in `config['is_timed_by_default']`;
   - `false` by default;
 - `retry_count` - (optional) `[Integer,NilClass]`
@@ -561,7 +647,7 @@ def lock(
   - pre-configured in `config['log_sampling_enabled']`;
 - `log_sampling_percent` - (optional) `[Integer]`
   - the percent of cases that should be logged;
-  - take an effect when `log_sampling_enalbed` is true;
+  - take an effect when `log_sampling_enabled` is true;
   - works in tandem with `log_sampling_enabled` and `log_sampler` options;
   - pre-configured in `config['log_sampling_percent']`;
 - `log_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]`
@@ -583,7 +669,7 @@ def lock(
   - 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;
+  - take an effect when `instr_sampling_enabled` 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>]`
@@ -621,6 +707,7 @@ Return value:
     result: {
       lock_key: "rql:lock:my_lock",
       acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
+      hst_id: "rql:hst:26672/2280/2320/70ea5dbf10ea1056",
       ts: 1711909612.653696,
       ttl: 10000,
       process: :lock_obtaining
@@ -634,7 +721,8 @@ Return value:
     - `:lock_obtaining` - classic lock obtaining proces. Default behavior (`conflict_strategy: :wait_for_lock`);
     - `: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`;
+    - (`conflict_strategy: :dead_locking` does not obtain the lock already obtained by the current acquirer:
+      it fails with `{ ok: false, result: :conflict_dead_lock }`);
     - For more details see [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks) readme section;
   - For successful lock obtaining:
     ```ruby
@@ -646,7 +734,7 @@ Return value:
         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)
+        process: Symbol # which logical process has acquired the lock (:lock_obtaining, :extendable_conflict_work_through, :conflict_work_through)
       }
     }
     ```
@@ -658,21 +746,21 @@ 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",
+        hst_id: "rql:hst: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
+        process: :lock_obtaining # for reentrant locks (conflict strategies): :conflict_work_through, :extendable_conflict_work_through
       }
     }
     ```
   - For failed lock obtaining:
     ```ruby
-    { ok: false, result: :timeout_reached }
-    { ok: false, result: :retry_count_reached }
+    { ok: false, result: :timeout_reached } # see <timeout> option
+    { ok: false, result: :retry_limit_reached } # see <retry_count> option
     { ok: false, result: :conflict_dead_lock } # see <conflict_strategy> option for details (:dead_locking strategy)
+    { ok: false, result: :conflict_lock_upgrade } # read-to-write lock upgrade (see <read_write_mode> and <conflict_strategy> options)
     { ok: false, result: :fail_fast_no_try } # see <fail_fast> option
     { ok: false, result: :fail_fast_after_try } # see <fail_fast> option
-    { ok: false, result: :unknown }
     ```
 
 Examples:
@@ -733,8 +821,9 @@ rql.lock_info("my_lock")
 # =>
 {
   "lock_key" => "rql:lock:my_lock",
+  "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789,
   "ini_ttl" => 123456,
   "rem_ttl" => 123440,
@@ -842,6 +931,7 @@ def lock!(
   lock_name,
   ttl: config['default_lock_ttl'],
   queue_ttl: config['default_queue_ttl'],
+  lock_index_grace_period: config['lock_index_grace_period'],
   timeout: config['try_to_lock_timeout'],
   timed: config['is_timed_by_default'],
   retry_count: config['retry_count'],
@@ -1017,9 +1107,9 @@ client.lock_series!("x", "y", "z") { ...some_code... }
   - `"acq_id"` - `string` - acquirer 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;
+  - `"ini_ttl"` - `integer` - (milliseconds) initial lock key ttl;
   - `"rem_ttl"` - `integer` - (milliseconds) remaining lock key ttl;
-  - `<custom metadata>`- `string`/`integer` - custom metadata passed to the `lock`/`lock!` methods via `meta:` keyword argument (see [lock]((#lock---obtain-a-lock)) method documentation);
+  - `<custom metadata>`- `string`/`integer` - custom metadata passed to the `lock`/`lock!` methods via `meta:` keyword argument (see [lock](#lock---obtain-a-lock) method documentation);
   - additional keys for **reentrant locks** and **extendable reentrant locks**:
     - for any type of reentrant locks:
       - `"spc_cnt"` - `integer` - how many times the lock was obtained as reentrant lock;
@@ -1039,7 +1129,7 @@ rql.lock_info("your_lock_name")
   "lock_key" => "rql:lock:your_lock_name",
   "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 4_999
@@ -1056,7 +1146,7 @@ rql.lock_info("your_lock_name")
   "lock_key" => "rql:lock:your_lock_name",
   "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 4_999,
@@ -1079,12 +1169,12 @@ rql.lock_info("your_lock_name")
   "lock_key" => "rql:lock:your_lock_name",
   "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 9_444,
   # ==> keys for any type of reentrant lock:
-  "spc_count" => 2, # how many times the lock was obtained as reentrant lock
+  "spc_cnt" => 2, # how many times the lock was obtained as reentrant lock
   # ==> keys for extendable reentarnt locks with `:extendable_work_through` strategy:
   "spc_ext_ttl" => 5_000, # sum of TTL of the each <extendable> reentrant lock (3_000 + 2_000)
   "l_spc_ext_ini_ttl" => 2_000, # TTL of the last <extendable> reentrant lock
@@ -1160,9 +1250,8 @@ rql.lock_info("your_lock_name")
 
 Returns an information about the required lock queue by the lock name. The result
 represnts the ordered lock request queue that is ordered by score (Redis Sets) and shows
-lock acquirers and their position in queue. Async nature with redis communcation can lead
-the situation when the queue becomes empty during the queue data extraction. So sometimes
-you can receive the lock queue info with empty queue value (an empty array).
+lock acquirers and their position in queue. The queue of write lock requests is an empty array
+(`"queue" => []`) when only the queue of read lock requests exists.
 
 - get the lock queue information;
 - queue represents the ordered set of lock key reqests:
@@ -1232,6 +1321,7 @@ rql.queued?("your_lock_name") # => true/false
 
 - release the concrete lock with lock request queue;
 - queue will be relased first;
+- (the enabled lock index) the lock name is dropped from the [Lock Index](#lock-index) in the same transaction;
 - has an alias: `#release_lock`;
 - accepts:
   - `lock_name` - (required) `[String]` - the lock name that should be released.
@@ -1276,7 +1366,7 @@ rql.queued?("your_lock_name") # => true/false
 Return:
 - `[Hash<Symbol,Boolean|Hash<Symbol,Numeric|String|Symbol>>]` (`{ ok: true/false, result: Hasn }`);
 - `:result` format;
-  - `:rel_time` - `Float` - time spent to process redis commands (in seconds);
+  - `:rel_time` - `Float` - time spent to process redis commands (in milliseconds);
   - `:rel_key` - `String` - released lock key (RedisQueudLocks-internal lock key name from Redis);
   - `:rel_queue` - `String` - released lock queue key (RedisQueuedLocks-internal queue key name from Redis);
   - `:queue_res` - `Symbol` - `:released` (or `:nothing_to_release` if the required queue does not exist);
@@ -1291,7 +1381,7 @@ rql.unlock("your_lock_name")
 {
   ok: true,
   result: {
-    rel_time: 0.02, # time spent to lock release (in seconds)
+    rel_time: 0.02, # time spent to lock release (in milliseconds)
     rel_key: "rql:lock:your_lock_name", # released lock key
     rel_queue: "rql:lock_queue:your_lock_name", # released lock key queue
     queue_res: :released, # or :nothing_to_release
@@ -1364,11 +1454,17 @@ rql.unlock_read('report', acquirer_id: reader['acq_id'])
 <sup>\[[back to top](#usage)\]</sup>
 
 - release all obtained locks and related lock request queues;
-- queues will be released first;
+- all lock keys (locks, read locks and lock queues) are found in one `SCAN` pass and deleted during it with one `DEL` per batch;
+- (the enabled [Lock Index](#lock-index)) all locks are found in one `ZSCAN` pass over the lock index (the keyspace is never
+  scanned): all the keys of each batch of locks (locks, read locks and lock queues) are deleted with one `DEL` in one transaction
+  with the removal of their lock names from the lock index; keys without the lock index entry (keys of older RQL versions) are not
+  found (see [#reindex_locks](#reindex_locks));
 - 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;
+    - the size of batch of locks and lock queus that should be cleared under the one `DEL` redis command at once (and the `SCAN` count);
+    - (the enabled lock index) the number of locks (lock names) whose keys should be cleared under the one `DEL` redis command
+      at once (and the `ZSCAN` count);
     - pre-configured in `config['lock_release_batch_size']`;
   - `:logger` - (optional) `[::Logger,#debug]`
     - custom logger object;
@@ -1445,10 +1541,13 @@ rql.clear_locks
   - `:acquirer_id` - (required) `[String]`
     - acquirer indentifier whose locks we want to release and which we want to remove from all locks queues;
   - `:lock_scan_size` - (optional) `[Integer]`
-    - how many items will be released at a time (uses `SCAN `for batch extraction and `DEL` for batch deletion);
+    - how many items will be released at a time (uses one `SCAN` pass for batch extraction and `DEL` for batch deletion);
+    - (the enabled [Lock Index](#lock-index)) how many locks will be processed at a time (one `ZSCAN` pass over the lock index
+      for batch extraction and `DEL` for batch deletion);
     - pre-configuerd value in `config['clear_locks_of__lock_scan_size']`;
   - `:queue_scan_size` - (optional) `[Integer]`
-    - how many queues will be SCAN'ned at a time (uses `SCAN)`;
+    - how many lock queues will be processed in one round trip (lock queues are found by the same `SCAN` pass as locks or
+      derived from the lock names of the same lock index pass);
     - pre-configuerd value in `config['clear_locks_of__queue_scan_size']`;
   - `:logger` - (optional) `[::Logger,#debug]`
     - custom logger object;
@@ -1550,10 +1649,13 @@ rql.clear_current_locks
   ```
 - produces `"redis_queued_locks.release_locks_of"` instrumentation event;
   - `:lock_scan_size` - (optional) `[Integer]`
-    - how many items will be released at a time (uses `SCAN `for batch extraction and `DEL` for batch deletion);
+    - how many items will be released at a time (uses one `SCAN` pass for batch extraction and `DEL` for batch deletion);
+    - (the enabled [Lock Index](#lock-index)) how many locks will be processed at a time (one `ZSCAN` pass over the lock index
+      for batch extraction and `DEL` for batch deletion);
     - pre-configuerd value in `config['clear_locks_of__lock_scan_size']`;
   - `:queue_scan_size` - (optional) `[Integer]`
-    - how many queues will be SCAN'ned at a time (uses `SCAN)`;
+    - how many lock queues will be processed in one round trip (lock queues are found by the same `SCAN` pass as locks or
+      derived from the lock names of the same lock index pass);
     - pre-configuerd value in `config['clear_locks_of__queue_scan_size']`;
   - `:logger` - (optional) `[::Logger,#debug]`
     - custom logger object;
@@ -1622,11 +1724,14 @@ rql.release_locks_of(host_id: rql.current_host_id, acquirer_id: rql.current_acqu
 
 - extends lock ttl by the required number of milliseconds;
 - expects the lock name and the number of milliseconds;
+- (the enabled lock index) the lock index score of the lock is increased by the same number of milliseconds
+  (see [Lock Index](#lock-index));
 - accepts:
   - `lock_name` - (required) `[String]`
     - the lock name which ttl should be extended;
   - `milliseconds` - (required) `[Integer]`
     - how many milliseconds should be added to the lock's TTL;
+    - should be a positive `Integer`;
   - `:read_write_mode` - (optional) `[Symbol]`
     - `:write` (default) - extends the write lock (the behavior described below);
     - `:read` - extends the read lock of the current acquirer only (see [Read/Write Locks](#readwrite-locks)):
@@ -1686,17 +1791,10 @@ rql.release_locks_of(host_id: rql.current_host_id, acquirer_id: rql.current_acqu
     and for the read lock of the current acquirer, the number of extended read locks for `all_read_locks: true`;
 - 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);
-- **Important**:
-  - the method is non-atomic cuz redis does not provide an atomic function for TTL/PTTL extension;
-  - the method consists of two commands:
-    - (1) read current pttl;
-    - (2) set new ttl that is calculated as "current pttl + additional milliseconds";
-  - the method uses Redis'es **CAS** (check-and-set) behavior;
-  - what can happen during these steps:
-    - lock is expired between commands or before the first command;
-    - lock is expired before the second command;
-    - lock is expired AND newly acquired by another process (so you will extend the
-      totally new lock with fresh PTTL);
+- **Important** (`:write` mode):
+  - the write lock TTL is extended atomically by one Lua script (`PTTL` + `PEXPIRE` with "current pttl + additional milliseconds");
+  - the lock owner is not checked: the current write lock is extended, so when your lock is expired and newly obtained
+    by another acquirer, the lock of that acquirer is extended;
   - use it at your own risk and consider the async nature when calling this method;
 
 ```ruby
@@ -1717,8 +1815,11 @@ rql.extend_lock_ttl("my_lock", 5_000) # NOTE: add 5_000 milliseconds
 
 - get list of obtained locks;
 - uses redis `SCAN` under the hood;
+- (the enabled [Lock Index](#lock-index)) uses the lock index under the hood (one `ZSCAN` pass, the keyspace is never scanned):
+  keys without the lock index entry (keys of older RQL versions) are not found (see [#reindex_locks](#reindex_locks));
 - accepts:
-  - `:scan_size` - `Integer` - (`config['key_extraction_batch_size']` by default);
+  - `:scan_size` - `Integer` - (`config['key_extraction_batch_size']` by default) - the `SCAN` count (or the `ZSCAN` count and
+    the batch size of locks with the enabled lock index);
   - `:with_info` - `Boolean` - `false` by default (for details see [#locks_info](#locks_info---get-list-of-locks-with-their-info));
 - returns:
   - `Set<String>` (for `with_info: false`);
@@ -1750,8 +1851,11 @@ rql.locks # or rql.locks(scan_size: 123)
 
 - get list of lock request queues;
 - uses redis `SCAN` under the hood;
+- (the enabled [Lock Index](#lock-index)) uses the lock index under the hood (one `ZSCAN` pass, the keyspace is never scanned):
+  keys without the lock index entry (keys of older RQL versions) are not found (see [#reindex_locks](#reindex_locks));
 - accepts
-  - `:scan_size` - `Integer` - (`config['key_extraction_batch_size']` by default);
+  - `:scan_size` - `Integer` - (`config['key_extraction_batch_size']` by default) - the `SCAN` count (or the `ZSCAN` count and
+    the batch size of locks with the enabled lock index);
   - `:with_info` - `Boolean` - `false` by default (for details see [#queues_info](#queues_info---get-list-of-queues-with-their-info));
 - returns:
   - `Set<String>` (for `with_info: false`);
@@ -1781,10 +1885,15 @@ rql.queues # or rql.queues(scan_size: 123)
 
 <sup>\[[back to top](#usage)\]</sup>
 
-- get list of taken locks and queues;
-- uses redis `SCAN` under the hood;
+- get list of taken locks and queues (all the existing keys of the locks: locks, lock queues, read locks registries,
+  read lock queues, read lock data);
+- uses redis `SCAN` under the hood (all `rql:lock*` keys);
+- (the enabled [Lock Index](#lock-index)) uses the lock index under the hood (one `ZSCAN` pass, the keyspace is never scanned):
+  keys without the lock index entry (keys of older RQL versions) and other `rql:lock*` keys are not listed
+  (see [#reindex_locks](#reindex_locks));
 - accepts:
-  `:scan_size` - `Integer` - (`config['key_extraction_batch_size']` by default);
+  `:scan_size` - `Integer` - (`config['key_extraction_batch_size']` by default) - the `SCAN` count (or the `ZSCAN` count and
+  the batch size of locks with the enabled lock index);
 - returns: `Set<String>`
 
 ```ruby
@@ -1816,7 +1925,8 @@ rql.keys # or rql.keys(scan_size: 123)
 <sup>\[[back to top](#usage)\]</sup>
 
 - get list of locks with their info;
-- uses redis `SCAN` under the hod;
+- uses redis `SCAN` under the hod (one pass) or the [Lock Index](#lock-index) (one `ZSCAN` pass, the keyspace is never scanned:
+  the enabled lock index), lock info is extracted in batches of `scan_size` locks (two round trips per batch);
 - accepts `scan_size:`/`Integer` option (`config['key_extraction_batch_size']` by default);
 - returns `Set<Hash<Symbol,Any>>` (see [#lock_info](#lock_info) and examples below for details).
   - contained data: `{ lock: String, status: Symbol, info: Hash<String,Any> }`;
@@ -1840,6 +1950,8 @@ rql.locks_info # or rql.locks_info(scan_size: 123)
     "hst_id"=>"rql:hst:41478/4320/4360/848818f09d8c3420",
     "ts"=>1711607112.670343,
     "ini_ttl"=>15000,
+    "lock_key"=>"rql:lock:some-lock-123",
+    "rw_mode"=>"write",
     "rem_ttl"=>13998}},
   {:lock=>"rql:lock:some-lock-456",
    :status=>:released,
@@ -1854,7 +1966,8 @@ rql.locks_info # or rql.locks_info(scan_size: 123)
 <sup>\[[back to top](#usage)\]</sup>
 
 - get list of queues with their info;
-- uses redis `SCAN` under the hod;
+- uses redis `SCAN` under the hod (one pass) or the [Lock Index](#lock-index) (one `ZSCAN` pass, the keyspace is never scanned:
+  the enabled lock index), queue info is extracted in batches of `scan_size` queues (one round trip per batch);
 - accepts `scan_size:`/`Integer` option (`config['key_extraction_batch_size']` by default);
 - returns `Set<Hash<Symbol,Any>>` (see [#queue_info](#queue_info) and examples below for details).
   - contained data: `{ queue: String, requests: Array<Hash<String,Any>> }`
@@ -1889,8 +2002,14 @@ before the lock acquire moment occurs and when no any other process does not nee
 For this case your lock reuquest will be cleared only when any process will try
 to acquire this lock again (cuz lock acquirement triggers the removement of expired requests).
 
+NOTE: with the enabled [Lock Index](#lock-index) the lock request queue lives as long as its latest lock request (the queue TTL
+is refreshed with the request `queue_ttl` on each lock request), so the queue of dead requests expires by itself (queues of older
+RQL versions and queues created with the disabled lock index have no TTL: see [#reindex_locks](#reindex_locks)).
+
 In order to help with these dead requests you may periodically call `#clear_dead_requests`
 with corresponding `:dead_ttl` option, that is pre-configured by default via `config['dead_request_ttl']`.
+Lock queues are found via the redis `SCAN` (one pass) or via the [Lock Index](#lock-index) (one `ZSCAN` pass, the keyspace is
+never scanned: the enabled lock index).
 
 `:dead_ttl` option is required because of it is no any **fast** and **resource-free** way to understand which request
 is dead now and is it really dead cuz each request queue can host their requests with
@@ -1902,6 +2021,8 @@ Accepts:
   - has a preconfigured value in `config['dead_request_ttl']` (1 day by default);
 - `:scan_size` - (optional) `[Integer]`
   - the batch of scanned keys for Redis'es SCAN command;
+  - (the enabled lock index) the `ZSCAN` count of the [Lock Index](#lock-index) pass and the number of locks (both lock queues
+    of each lock) processed in one round trip;
   - has a preconfigured valie in `config['lock_release_batch_size']`;
 - `:logger` - (optional) `[::Logger,#debug]`
   - custom logger object;
@@ -1939,7 +2060,8 @@ Accepts:
   - makes sense when instrumentation sampling is enabled;
   - `false` by default;
 
-Returns: `{ ok: true, processed_queues: Set<String> }` returns the list of processed lock queues;
+Returns: `{ ok: true, result: { processed_queues: Set<String> } }` returns the set of processed lock request queues
+(write and read lock request queues);
 
 ```ruby
 rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
@@ -1947,17 +2069,91 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 # =>
 {
   ok: true,
-  processed_queues: [
-    "rql:lock_queue:some-lock-123",
-    "rql:lock_queue:some-lock-456",
-    "rql:lock_queue:your-other-lock",
-    ...
-  ]
+  result: {
+    processed_queues: #<Set: {
+      "rql:lock_queue:some-lock-123",
+      "rql:lock_queue:some-lock-456",
+      "rql:lock_read_queue:some-lock-456",
+      "rql:lock_queue:your-other-lock",
+      ...
+    }>
+  }
 }
 ```
 
 ---
 
+#### #reindex_locks
+
+<sup>\[[back to top](#usage)\]</sup>
+
+- adds the lock keys without the lock index entry (keys of older RQL versions and keys created with the disabled lock index)
+  to the lock index (see [Lock Index](#lock-index));
+- invoke it once after the lock index is enabled (`config['lock_index_enabled'] = true`) on **all** your processes: with the
+  enabled lock index all lock-iterating operations (the swarm, `#locks`, `#queues`, `#keys`, `#clear_locks`, `#clear_locks_of`,
+  `#clear_dead_requests`, ...) find locks via the lock index only;
+- works regardless of `config['lock_index_enabled']` (it is not needed while the lock index is disabled: the lock index is
+  neither used nor maintained then);
+- one `SCAN` pass over the RQL keys (`rql:lock*`) with pipelined batches (two round trips per batch);
+- write locks and read locks registries are indexed with their remaining TTL (+ the grace period), lock queues without TTL
+  (older RQL versions) get the `queue_ttl` TTL first; read lock data is not indexed (it is found via the read locks registry);
+- idempotent: the lock index scores are never decreased (it can be invoked at any time);
+- accepts:
+  - `:scan_size` - (optional) `[Integer]`
+    - the batch of scanned keys for Redis'es SCAN command;
+    - pre-configured in `config['lock_release_batch_size']`;
+  - `:queue_ttl` - (optional) `[Integer]`
+    - TTL of the lock queues without TTL (in seconds);
+    - pre-configured in `config['default_queue_ttl']`;
+  - `:lock_index_grace_period` - (optional) `[Integer]`
+    - the lock index grace period (in milliseconds);
+    - pre-configured in `config['lock_index_grace_period']`;
+  - `:logger` - (optional) `[::Logger,#debug]`
+    - custom logger object;
+    - pre-configured in `config['logger']`;
+  - `: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);
+  - `:log_sampling_enabled` - (optional) `[Boolean]`
+    - enables **log sampling**;
+    - pre-configured in `config['log_sampling_enabled']`;
+  - `:log_sampling_percent` - (optional) `[Integer]`
+    - **log sampling**:the percent of cases that should be logged;
+    - pre-configured in `config['log_sampling_percent']`;
+  - `: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']`;
+  - `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']`;
+  - `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: { idx_key_cnt: Integer } }` (the number of indexed keys);
+
+```ruby
+rql.reindex_locks
+
+# =>
+{ ok: true, result: { idx_key_cnt: 123 } }
+```
+
+---
+
 #### #current_acquirer_id
 
 <sup>\[[back to top](#usage)\]</sup>
@@ -2084,6 +2280,12 @@ rql.possible_host_ids
 
 **This documentation section is in progress!** (see the changelog and the usage preview for details at this moment)
 
+- zombie locks and zombie lock requests are found in one `SCAN` pass over the RQL keys (`rql:lock*`) or, with the enabled
+  [Lock Index](#lock-index) (`config['lock_index_enabled']`), in one `ZSCAN` pass over the lock names: the swarm never scans
+  the whole Redis keyspace then (keys of your other applications are never visited);
+- after enabling the lock index invoke [#reindex_locks](#reindex_locks) once (when all your processes use the lock index):
+  locks created without the lock index are not indexed and are not found by the swarm until then;
+
 [(work and usage preview (temporary example-based docs))](#work-and-usage-preview-temporary-example-based-docs)
 
 - [How to Swarm](#how-to-swarm)
@@ -2115,6 +2317,8 @@ rql.possible_host_ids
     # NOTE: auto-swarm your RQL client after initalization (run swarm elements and their supervisor)
     config['swarm.auto_swarm'] = false
 
+    # NOTE: the periods, the zombie ttl and the scan sizes should be positive Integers
+
     # supervisor configs
     config['swarm.supervisor.liveness_probing_period'] = 2 # NOTE: in seconds
 
@@ -2131,8 +2335,8 @@ rql.possible_host_ids
     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/acquirer 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
+    config['swarm.flush_zombies.zombie_lock_scan_size'] = 500 # NOTE: SCAN count (or ZSCAN count with the enabled lock index) and the batch size of locks during zombie flushing
+    config['swarm.flush_zombies.zombie_queue_scan_size'] = 500 # NOTE: the batch size of lock queues during zombie flushing (one round trip per batch)
     # (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
@@ -2267,6 +2471,120 @@ rql.possible_host_ids
   ```
 </details>
 
+<details>
+  <summary>lock index key in Redis (the enabled lock index only)</summary>
+
+  ```ruby
+  "rql:index:locks"
+  ```
+</details>
+
+---
+
+## Lock Index
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+> Find locks without scanning the whole Redis keyspace (opt-in: `config['lock_index_enabled'] = true`).
+
+> [!IMPORTANT]
+> Your locks should work either **always with** the lock index or **always without** it (the same
+> `config['lock_index_enabled']` value on all your processes that share the Redis database): locks obtained without the lock
+> index are not indexed and are invisible to the lock-iterating operations of the processes with the enabled lock index
+> (the swarm, `#locks`, `#queues`, `#keys`, `#clear_locks`, ...). So every time you enable the lock index after working without it
+> (including the upgrade from older RQL versions) invoke [#reindex_locks](#reindex_locks) once all your processes use the lock index.
+
+- **disabled by default**: lock-iterating operations scan the Redis keyspace (`SCAN MATCH rql:lock*`, the classic way),
+  no lock index commands are sent and lock request queues have no TTL; enable the lock index via config:
+
+  ```ruby
+  RedisQueuedLocks::Client.new(redis_client) do |config|
+    config['lock_index_enabled'] = true
+    # (milliseconds) (default: 60_000)
+    # - the lock name stays in the lock index for this period after the expiration of all its keys;
+    # - why: the lock index scores use the client clock, so this margin protects the index from the clock skew
+    #   between your hosts and from the network latency (otherwise a live lock can drop out of the index and
+    #   the swarm/lock-iterating operations will not see it);
+    # - keep it greater than the maximal clock skew between your hosts plus the network latency;
+    config['lock_index_grace_period'] = 60_000
+  end
+  ```
+- the client-wide mode (not a per-call option): the lock acquirement maintains the lock index and all lock-iterating operations
+  read it only when it is enabled; use the same mode on **all** your processes that share the Redis database (locks of
+  the processes without the lock index are not indexed: lock-iterating operations of the processes with the lock index do not
+  see them); the swarm reads the mode when it is started;
+- the lock index is a sorted set `rql:index:locks`: the member is the lock name, the score is the upper bound of the lifetime
+  of all lock keys (write lock, read locks registry, lock request queues): `client time (epoch, ms) + key ttl + grace period`;
+- all lock-iterating operations iterate over the lock index (`ZSCAN`) and derive lock keys from the lock names instead of
+  the full keyspace `SCAN`: their cost depends on the number of your locks only (not on the size of your Redis database):
+  - the swarm: `#flush_zombies`, the zombie flusher, `#zombie_locks`, `#zombie_acquirers`, `#zombies_info`;
+  - `#locks`/`#locks_info`, `#queues`/`#queues_info`, `#keys`, `#clear_locks`, `#clear_locks_of`/`#clear_current_locks`,
+    `#clear_dead_requests`;
+  - only [#reindex_locks](#reindex_locks) scans the keyspace (it adds the keys without the lock index entries to the lock index);
+- the index is maintained by the lock acquirement itself (no background jobs, no additional Redis round trips):
+  - each lock request adds the lock name to the index (`ZADD GT` with the queue ttl), sets the lock request queue TTL
+    (the queue lives as long as its latest lock request) and drops the expired lock names from the index (`ZREMRANGEBYSCORE`):
+    4 commands in the existing queueing pipeline;
+  - each lock obtaining (write and read) adds the lock name with the lock ttl in the same transaction (1 command);
+  - each lock extension (`#extend_lock_ttl`, `:extendable_work_through` reentrant locks) increases the score by the extension;
+  - the lock name is dropped from the index when all its keys are expired and the grace period is over, by `#unlock` (in the
+    release transaction) and by `#clear_locks` (in the transaction that deletes the keys of the lock);
+- `config['lock_index_grace_period']` (`60_000` milliseconds by default) and `lock_index_grace_period:` option of
+  `#lock`/`#lock!`/`#lock_series`/`#lock_series!`: the lock name stays in the index for this period after the expiration of
+  all its keys; it should be greater than the maximal client clock skew between your hosts plus the duration of one lock
+  acquirement attempt (network latency) (otherwise a lock can be dropped from the index before its expiration and the swarm
+  will not see it);
+- (enabling) locks of older RQL versions and locks created with the disabled lock index have no lock index entries (they are not
+  found by lock-iterating operations till then): enable the lock index on **all** your processes, then invoke
+  [#reindex_locks](#reindex_locks) once;
+- (disabling) lock-iterating operations scan the keyspace again; the lock index key is neither used nor maintained anymore
+  (you can delete it: `DEL rql:index:locks`); invoke [#reindex_locks](#reindex_locks) again after the next enabling;
+- (limitation) the lock index is one Redis key written on each lock request (a "hot" key): fine for a standalone Redis
+  (and Sentinel); Redis Cluster is not supported (RQL transactions use several keys of each lock without hash tags);
+
+#### Lock Index Performance
+
+<sup>\[[back to top](#lock-index)\]</sup>
+
+- measured on a local Redis with 1 million keys of other applications in the same database and ~1 200 locks (+100 lock queues
+  for the lock-iterating operations, a zombie host for `#flush_zombies`): wall time and Redis CPU time of one call with
+  the keyspace `SCAN` (`config['lock_index_enabled'] = false`) and with the lock index (`config['lock_index_enabled'] = true`):
+
+| Operation | Keyspace `SCAN` (wall / Redis CPU) | Lock index (wall / Redis CPU) | Speedup (wall / Redis CPU) |
+|---|---|---|---|
+| `#flush_zombies` (the zombie flusher) | 263 ms / 181 ms | 20 ms / 2.4 ms | **x13** / **x75** |
+| `#locks` | 269 ms / 192 ms | 7.7 ms / 1.4 ms | **x35** / **x137** |
+| `#locks_info` | 288 ms / 194 ms | 23 ms / 2.3 ms | **x12.5** / **x84** |
+| `#queues` / `#queues_info` | 260-280 ms / 190 ms | 8 ms / 1-2 ms | **x32-35** / **x95-190** |
+| `#keys` | 272 ms / 193 ms | 17 ms / 2.6 ms | **x16** / **x74** |
+| `#clear_dead_requests` | 574 ms / 224 ms | 18 ms / 2.2 ms | **x32** / **x102** |
+| `#clear_locks_of` / `#clear_current_locks` | 322 ms / 200 ms | 14 ms / 1.9 ms | **x23** / **x105** |
+| `#clear_locks` | 574 ms / 225 ms | 14 ms / 5.1 ms | **x41** / **x44** |
+
+- the speedup grows with the number of keys in your Redis database: the keyspace `SCAN` visits all keys of the database (keys
+  of your other applications too), the lock index visits the lock names only (the cost depends on the number of your locks and
+  on the lock index size, see [Lock Index Size](#lock-index-size));
+- the zombie flusher runs in every process with the swarm (every `zombie_flush_period`): the saved Redis CPU is multiplied by
+  the number of your processes;
+- the price is paid by the lock acquirement (it maintains the lock index without new round trips: 4 more commands in
+  the queueing pipeline and 1 more command in the obtaining transaction): ~10% fewer locks per second in a single-thread
+  `lock {}` loop on a local Redis, 280 -> 348 allocations per `lock {}`;
+
+#### Lock Index Size
+
+<sup>\[[back to top](#lock-index)\]</sup>
+
+- the lock index size is about `<the number of distinct lock names per second> * (max(queue_ttl, ttl) + grace period)`
+  (`~75` seconds of lock names with the default settings: `config['default_queue_ttl']` (15 seconds) +
+  `config['lock_index_grace_period']` (60 seconds));
+- with very diverse lock names (for example, `order:#{id}`) lock-iterating operations (the swarm, `#locks`, `#queues`, `#keys`,
+  `#clear_locks`, ...) visit the dead lock names of this window too (lock names whose keys are already expired);
+- if it becomes noticeable, there are two levers:
+  - reduce `config['lock_index_grace_period']` (keep it greater than the maximal client clock skew between your hosts plus
+    the network latency);
+  - **TODO**: a cheap existence check of the lock name (`EXISTS` of its keys) before reading the lock details in
+    lock-iterating operations;
+
 ---
 
 ## Lock Access Strategies
@@ -2292,7 +2610,7 @@ rql.possible_host_ids
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - `read_write_mode:` attribute of `#lock` and `#lock!`:
-  - `:write` (default) - exclusive lock (the classic RQL lock): waits for the write lock and for all read locks;
+  - `:write` (**default**) - exclusive lock (the classic RQL lock): waits for the write lock and for all read locks;
   - `:read` - shared lock: waits for the write lock only (read locks of different acquirers work in parallel);
 
 ```ruby
@@ -2301,7 +2619,9 @@ rql.lock('report', read_write_mode: :read) { read_report }
 
 # writer waits for all readers (and readers wait for the writer)
 rql.lock('report', read_write_mode: :write) { rebuild_report }
-rql.lock('report') { rebuild_report } # (write mode is the default mode)
+
+# write mode is default:
+rql.lock('report') { rebuild_report } # read_write_mode: :write by default
 ```
 
 - lock request ordering (`access_strategy`):
@@ -2311,10 +2631,11 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
   - `:random` - lock queues are ignored: any free lock is obtained (a continuous flow of readers can starve writers);
 - read locks:
   - each read lock has its own `ttl` and is released (after the block execution) or expired independently of other read locks;
-  - `ttl` should be a positive `Integer` (`RedisQueuedLocks::ArgumentError`);
+  - `ttl` should be a positive `Integer`;
   - each read lock has its own data with the same structure as the write lock data: acquirer, host, timestamp,
     initial ttl, `:meta` (with the same reserved keys) and reentrant lock data (`spc_cnt`, `spc_ext_ttl`, ...);
-    the read lock data lives as long as the read lock and is returned by `#lock_info`/`#locks_info` for each reader;
+    the read lock data lives as long as the read lock and is returned by `#lock_info`/`#locks_info` for each reader
+    (acquirer and host are not stored: both are derived from the acquirer id);
   - `#unlock` releases the lock entirely: the write lock, all read locks (with their data) and all lock requests;
   - `#unlock_read` (aka `#release_read_lock`) releases the read lock of the current acquirer
     (suitable for read locks obtained without a block), or the read lock of the acquirer passed via `acquirer_id:`;
@@ -2363,7 +2684,7 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
   - `rql:lock_queue:<lock_name>` - write lock requests (`ZSET`, the classic RQL lock queue);
   - `rql:lock_readers:<lock_name>` - read locks (`ZSET`: acquirer id => read lock expiration time in Redis time, milliseconds);
   - `rql:lock_read_queue:<lock_name>` - read lock requests (`ZSET`);
-  - `rql:lock_reader:<lock_name>:<acquirer_id>` - read lock data (`HASH`, the same structure as the write lock, read lock ttl);
+  - `rql:lock_reader:<lock_name>:<acquirer_id>` - read lock data (`HASH`, the same structure as the write lock without acquirer and host ids, read lock ttl);
 - implementation notes:
   - optimistic transactions only (`WATCH`/`MULTI`): readers watch the write lock key, writers watch the write lock key and the read locks key,
     so readers never invalidate transactions of each other;
@@ -2410,6 +2731,7 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 "[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 "[redis_queued_locks.lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+"[redis_queued_locks.lock_obtaining_failed]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time", "result");
 "[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
 "[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
 "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
@@ -2448,6 +2770,19 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 "[redis_queued_locks.expire_lock_series]" # (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 ```
 
+- operation logs (one log line per operation that changes Redis keys, with the time of the whole operation; the same data as
+  the instrumentation event of the operation without `instrument`):
+
+```ruby
+"[redis_queued_locks.explicit_lock_release]" # (logs "lock_key", "lock_key_queue", "rel_time", "at");
+"[redis_queued_locks.explicit_read_lock_release]" # (logs "lock_key", "acq_id", "lock_res", "rel_time", "at");
+"[redis_queued_locks.explicit_all_locks_release]" # (logs "at", "rel_time", "rel_key_cnt");
+"[redis_queued_locks.release_locks_of]" # (logs "at", "hst_id", "acq_id", "rel_time", "rel_key_cnt", "tch_queue_cnt");
+"[redis_queued_locks.extend_lock_ttl]" # (logs "lock_key", "rw_mode", "all_read_locks", "ext_ttl", "extended_locks_count", "ext_time", "at");
+"[redis_queued_locks.clear_dead_requests]" # (logs "dead_ttl", "prc_queue_cnt", "rel_time", "at");
+"[redis_queued_locks.reindex_locks]" # (logs "idx_key_cnt", "idx_time", "at");
+```
+
 - read/write try-lock logs (see [Read/Write Locks](#readwrite-locks)):
   - `single_process_lock_conflict__lock_upgrade` - write lock request of the acquirer that holds the read lock
     (read-to-write lock upgrade is not supported for `:work_through` and `:extendable_work_through` conflict strategies);
@@ -2463,7 +2798,7 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 **NOTICE**: logging can be sampled via:
-- `config['log_samplign_enabled'] = true` (**false** by default);
+- `config['log_sampling_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;
 
@@ -2477,6 +2812,7 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 #   - "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+#   - "[redis_queued_locks.lock_obtaining_failed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time", "result");
 #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
 #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
 #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
@@ -2485,6 +2821,13 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 #   - "[redis_queued_locks.start_lock_series_obtaining]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 #   - "[redis_queued_locks.lock_series_obtained]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
 #   - "[redis_queued_locks.expire_lock_series]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+#   - "[redis_queued_locks.explicit_lock_release]" (logs "lock_key", "lock_key_queue", "rel_time", "at");
+#   - "[redis_queued_locks.explicit_read_lock_release]" (logs "lock_key", "acq_id", "lock_res", "rel_time", "at");
+#   - "[redis_queued_locks.explicit_all_locks_release]" (logs "at", "rel_time", "rel_key_cnt");
+#   - "[redis_queued_locks.release_locks_of]" (logs "at", "hst_id", "acq_id", "rel_time", "rel_key_cnt", "tch_queue_cnt");
+#   - "[redis_queued_locks.extend_lock_ttl]" (logs "lock_key", "rw_mode", "all_read_locks", "ext_ttl", "extended_locks_count", "ext_time", "at");
+#   - "[redis_queued_locks.clear_dead_requests]" (logs "dead_ttl", "prc_queue_cnt", "rel_time", "at");
+#   - "[redis_queued_locks.reindex_locks]" (logs "idx_key_cnt", "idx_time", "at");
 #   - "rw_mode" is the requested lock mode ('write'/'read'), the held lock mode for "expire_lock" and "decrease_lock",
 #     the mode of the series for lock series logs;
 # - by default uses VoidLogger that does nothing;
@@ -2523,7 +2866,7 @@ 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;
+# - take an effect when <config['log_sampling_enabled']> is true;
 # - works in tandem with <config['log_sampling_enabled']> and <config['log_sampler']> configs;
 config['log_sampling_percent'] = 15
 
@@ -2590,7 +2933,7 @@ 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;
+# - take an effect when <config['instr_sampling_enabled']> is true;
 # - works in tandem with <config['instr_sampling_enabled']> and <config['instr_sampler']> configs;
 config['instr_sampling_percent'] = 15
 
@@ -2613,6 +2956,7 @@ config['instr_sampler'] = RedisQueuedLocks::Instrument::Sampler
 List of instrumentation events
 
 - ["redis_queued_locks.lock_obtained"](#redis_queued_lockslock_obtained)
+- ["redis_queued_locks.lock_obtaining_failed"](#redis_queued_lockslock_obtaining_failed)
 - ["redis_queued_locks.extendable_reentrant_lock_obtained"](#redis_queued_locksextendable_reentrant_lock_obtained)
 - ["redis_queued_locks.reentrant_lock_obtained"](#redis_queued_locksreentrant_lock_obtained)
 - ["redis_queued_locks.lock_hold_and_release"](#redis_queued_lockslock_hold_and_release)
@@ -2623,6 +2967,17 @@ List of instrumentation events
 - ["redis_queued_locks.explicit_read_lock_release"](#redis_queued_locksexplicit_read_lock_release)
 - ["redis_queued_locks.explicit_all_locks_release"](#redis_queued_locksexplicit_all_locks_release)
 - ["redis_queued_locks.release_locks_of"](#redis_queued_locksrelease_locks_of)
+- ["redis_queued_locks.extend_lock_ttl"](#redis_queued_locksextend_lock_ttl)
+- ["redis_queued_locks.clear_dead_requests"](#redis_queued_locksclear_dead_requests)
+- ["redis_queued_locks.reindex_locks"](#redis_queued_locksreindex_locks)
+
+What is instrumented (each event has a log line with the same name, see [Logging](#logging)):
+- the lock acquirement (`#lock`/`#lock!`, `#lock_series`/`#lock_series!`): each meaningful outcome (the lock is obtained,
+  not obtained, held and released);
+- each operation that changes Redis keys (`#unlock`, `#unlock_read`, `#clear_locks`, `#clear_locks_of`/`#clear_current_locks`,
+  `#extend_lock_ttl`, `#clear_dead_requests`, `#reindex_locks`): one event with the time of the whole operation;
+- lock information queries (`#lock_info`, `#locks`, `#queues`, `#keys`, ...) are not instrumented;
+- the swarm (`#probe_hosts`, `#flush_zombies` and the swarm elements) is not instrumented yet;
 
 Detalized event semantics and payload structure:
 
@@ -2640,6 +2995,23 @@ Detalized event semantics and payload structure:
   - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
   - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
 
+##### `"redis_queued_locks.lock_obtaining_failed"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- a moment when the lock acquirement is failed (the lock is not obtained);
+- raised from `#lock`/`#lock!` (with `raise_errors: true` - before the error is raised) and from `#lock_series`/`#lock_series!`
+  (for the lock of the series that is not obtained);
+- payload:
+  - `:lock_key` - `string` - lock name;
+  - `:rw_mode` - `symbol` - requested lock mode: `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
+  - `:ttl` - `integer`/`milliseconds` - requested lock ttl;
+  - `:acq_id` - `string` - lock acquirer identifier;
+  - `:hst_id` - `string` - lock's host identifier;
+  - `:ts` - `numeric`/`epoch` - the time when the lock acquirement is failed;
+  - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+  - `:result` - `symbol` - the failure result: `:timeout_reached`, `:retry_limit_reached`, `:fail_fast_no_try`,
+    `:fail_fast_after_try`, `:conflict_dead_lock`, `:conflict_lock_upgrade` (see [lock](#lock---obtain-a-lock));
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
+
 ##### `"redis_queued_locks.extendable_reentrant_lock_obtained"`
 - <sup>\[[back to the list](#instrumentation-events)\]</sup>
 - an event signalizes about the "extendable reentrant lock" obtaining is happened;
@@ -2742,6 +3114,7 @@ Detalized event semantics and payload structure:
   - `:rel_time` - `float`/`milliseconds` - time spent on lock releasing;
   - `:lock_key` - `string` - released lock (lock name);
   - `:lock_key_queue` - `string` - released lock queue (the queue of write lock requests);
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#unlock` method as `:instrument` attribute;
 
 ##### `"redis_queued_locks.explicit_read_lock_release"`
 - <sup>\[[back to the list](#instrumentation-events)\]</sup>
@@ -2764,6 +3137,7 @@ Detalized event semantics and payload structure:
   - `:at` - `float`/`epoch` - the time when the operation has ended;
   - `:rel_key_cnt` - `integer` - released redis keys count (write locks, readers registries, read lock data,
     write and read lock request queues);
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#clear_locks` method as `:instrument` attribute;
 
 ##### `"redis_queued_locks.release_locks_of"`
 - <sup>\[[back to the list](#instrumentation-events)\]</sup>
@@ -2776,6 +3150,42 @@ Detalized event semantics and payload structure:
   - `:hst_id` - `string` - refused host identifier;
   - `:rel_key_cnt` - `integer` - released locks count (write locks and read locks);
   - `:tch_queue_cnt` - `:integer` - the number of queues (write and read lock request queues) from which the concrete host/acquirer was removed;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#clear_locks_of`/`#clear_current_locks` method as `:instrument` attribute;
+
+##### `"redis_queued_locks.extend_lock_ttl"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- an event signalizes about the lock TTL extension (successful or not);
+- raised from `#extend_lock_ttl`;
+- payload:
+  - `:lock_key` - `string` - lock key (`rql:lock:<lock_name>`);
+  - `:rw_mode` - `symbol` - `:write` (the write lock) or `:read` (the read lock of the acquirer or all read locks);
+  - `:all_read_locks` - `boolean` - all read locks of the lock are extended (`:read` mode);
+  - `:ext_ttl` - `integer`/`milliseconds` - the extension (`milliseconds` argument);
+  - `:extended_locks_count` - `integer` - the number of extended locks (`0` when nothing is extended);
+  - `:ext_time` - `float`/`milliseconds` - time spent on the extension;
+  - `:at` - `float`/`epoch` - the time when the operation has ended;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#extend_lock_ttl` method as `:instrument` attribute;
+
+##### `"redis_queued_locks.clear_dead_requests"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- an event signalizes about the dropped dead lock requests;
+- raised from `#clear_dead_requests`;
+- payload:
+  - `:dead_ttl` - `integer`/`milliseconds` - lock requests older than `dead_ttl` are dropped;
+  - `:prc_queue_cnt` - `integer` - the number of processed lock request queues (write and read);
+  - `:rel_time` - `float`/`milliseconds` - time spent on the operation;
+  - `:at` - `float`/`epoch` - the time when the operation has ended;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#clear_dead_requests` method as `:instrument` attribute;
+
+##### `"redis_queued_locks.reindex_locks"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- an event signalizes about the lock keys added to the [Lock Index](#lock-index);
+- raised from `#reindex_locks`;
+- payload:
+  - `:idx_key_cnt` - `integer` - the number of indexed keys;
+  - `:idx_time` - `float`/`milliseconds` - time spent on the operation;
+  - `:at` - `float`/`epoch` - the time when the operation has ended;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#reindex_locks` method as `:instrument` attribute;
 
 ---