redis_queued_locks 1.20.0 → 1.21.0

data/README.md

@@ -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)
@@ -78,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)
@@ -88,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)
@@ -191,16 +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)
@@ -260,6 +268,7 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - (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)
@@ -268,12 +277,14 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   (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 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)
@@ -282,6 +293,7 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - (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)
@@ -327,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
 
@@ -343,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)
@@ -366,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
 
@@ -383,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
 
@@ -409,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)
@@ -430,6 +464,10 @@ end
 - [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
@@ -488,6 +526,7 @@ 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.
@@ -502,9 +541,14 @@ def lock(
   - 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]`
@@ -603,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>]`
@@ -625,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>]`
@@ -663,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
@@ -676,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
@@ -688,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)
       }
     }
     ```
@@ -700,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:
@@ -775,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,
@@ -1060,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;
@@ -1082,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
@@ -1099,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,
@@ -1122,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
@@ -1319,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);
@@ -1334,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
@@ -1684,6 +1731,7 @@ rql.release_locks_of(host_id: rql.current_host_id, acquirer_id: rql.current_acqu
     - 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)):
@@ -1743,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
@@ -1909,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,
@@ -2017,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
@@ -2025,12 +2069,15 @@ 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",
+      ...
+    }>
+  }
 }
 ```
 
@@ -2061,6 +2108,41 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
   - `: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
@@ -2235,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
 
@@ -2526,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
@@ -2535,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`):
@@ -2545,7 +2631,7 @@ 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
@@ -2645,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");
@@ -2683,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);
@@ -2698,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;
 
@@ -2712,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");
@@ -2720,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;
@@ -2758,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
 
@@ -2825,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
 
@@ -2848,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)
@@ -2858,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:
 
@@ -2875,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;
@@ -2977,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>
@@ -2999,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>
@@ -3011,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;
 
 ---