redis_queued_locks 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 448f8b89e4a34bb2543b55d46877d80f76cf8e4b5d07735486f53eb1edb37432
-  data.tar.gz: 4fbefadd9a162ab298b100bca38387045c65c89918ffd70c3f4aa418aa72d22a
+  metadata.gz: 5be49c89b572553d2de7af37b8bbc38439bcefc5b2b33cd4d8e542fb3c9dd3e3
+  data.tar.gz: 8a3a5509e82bd45ff9576677e2c2017c670fdd6a825da8ad0281f0fc1b6e7e69
 SHA512:
-  metadata.gz: 738c503d6189ca4673d1bc5af829066378654a070b78691ae7d1001e832795dbb91f1cde3e89252ff6b9831a659daf517eea1ea2ab721101c9140afe16b44974
-  data.tar.gz: cb2b4893238e55688b01c56f5f0004217d206122d5ae5ef3a0ea8f2d206323442e4c10bf78f3d504f947795864decc712f5385448b205151ccfe7ca39ab9ea0a
+  metadata.gz: 8f151272fadc4be25fd1344f9b29a5b263bc8ab63d17e8d09c55178232e4e57acac456c5987c0040172643e0a479976f9c12d0ff81549ba223ed742adb0dfcd1
+  data.tar.gz: c862d4040d1dbe421a7a8e2a10c8e24c8e22cd74c65d64746cb74ad96c2d31b3c1ec7a55f22cc0149ea0a65014f4d891d8a13f4336b07d6f56130673203ff384

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [1.5.0] - 2024-05-23
+### Added
+- New Feature: **Log sampling** - configurable log sampling based on `weight` algorithm (where the weight is a percentage);
+
 ## [1.4.0] - 2024-05-13
 ### Added
 - `#lock`/`#lock!`: reduced memory allocaiton during `:meta` attribute type checking;

data/README.md

@@ -4,7 +4,7 @@
 
 Each lock request is put into the request queue (each lock is hosted by it's own queue separately from other queues) and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) (with requeue capabilities) which guarantees the request queue will never be stacked.
 
-Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttls, queue ttls, lock attempts limit, fast failing, etc), logging and instrumentation.
+Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), logging and instrumentation.
 
 ---
 
@@ -182,10 +182,10 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
 
   # (default: RedisQueuedLocks::Instrument::VoidNotifier)
   # - instrumentation layer;
-  # - you can provde your own instrumenter with `#notify(event, payload = {})`
+  # - you can provide your own instrumenter that should realize `#notify(event, payload = {})` interface:
   #   - event: <string> requried;
   #   - payload: <hash> requried;
-  # - disabled by default via VoidNotifier;
+  # - disabled by default via `VoidNotifier`;
   config.instrumenter = RedisQueuedLocks::Instrument::ActiveSupport
 
   # (default: -> { RedisQueuedLocks::Resource.calc_uniq_identity })
@@ -232,6 +232,27 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
   #   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id");
   config.log_lock_try = false
+
+  # (default: false)
+  # - enables <log sampling>: only the configured percent of RQL cases will be logged;
+  # - disabled by default;
+  # - works in tandem with <config.log_sampling_percent> and <log.sampler> configs;
+  config.log_sampling_enabled = false
+
+  # (default: 15)
+  # - the percent of cases that should be logged;
+  # - take an effect when <config.log_sampling_enalbed> is true;
+  # - works in tandem with <config.log_sampling_enabled> and <config.log_sampler> configs;
+  config.log_sampling_percent = 15
+
+  # (default: RedisQueuedLocks::Logging::Sampler)
+  # - percent-based log sampler that decides should be RQL case logged or not;
+  # - works in tandem with <config.log_sampling_enabled> and <config.log_sampling_percent> configs;
+  # - based on the ultra simple percent-based (weight-based) algorithm that uses SecureRandom.rand
+  #   method so the algorithm error is ~(0%..13%);
+  # - you can provide your own log sampler with bettter algorithm that should realize
+  #   `sampling_happened?(percent) => boolean` interface (see `RedisQueuedLocks::Logging::Sampler` for example);
+  config.log_sampler = RedisQueuedLocks::Logging::Sampler
 end
 ```
 
@@ -290,6 +311,9 @@ def lock(
   instrument: nil,
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
+  log_sampling_enabled: config[:log_sampling_enabled],
+  log_sampling_percent: config[:log_sampling_percent],
+  log_sampler: config[:log_sampler],
   &block
 )
 ```
@@ -363,6 +387,24 @@ def lock(
   - should be logged the each try of lock acquiring (a lot of logs can be generated depending on your retry configurations);
   - pre-configured in `config[:log_lock_try]`;
   - `false` by default;
+- `log_sampling_enabled` - (optional) `[Boolean]`
+  - enables **log sampling**: only the configured percent of RQL cases will be logged;
+  - disabled by default;
+  - works in tandem with `log_sampling_percent` and `log_sampler` options;
+  - 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;
+  - 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>]`
+  - percent-based log sampler that decides should be RQL case logged or not;
+  - works in tandem with `log_sampling_enabled` and `log_sampling_percent` options;
+  - based on the ultra simple percent-based (weight-based) algorithm that uses SecureRandom.rand
+    method so the algorithm error is ~(0%..13%);
+  - you can provide your own log sampler with bettter algorithm that should realize
+    `sampling_happened?(percent) => boolean` interface (see `RedisQueuedLocks::Logging::Sampler` for example);
+  - pre-configured in `config[:log_sampler]`;
 - `block` - (optional) `[Block]`
   - A block of code that should be executed after the successfully acquired lock.
   - If block is **passed** the obtained lock will be released after the block execution or it's ttl (what will happen first);
@@ -572,6 +614,9 @@ def lock!(
   log_lock_try: config[:log_lock_try],
   instrument: nil,
   conflict_strategy: config[:default_conflict_strategy],
+  log_sampling_enabled: config[:log_sampling_enabled],
+  log_sampling_percent: config[:log_sampling_percent],
+  log_sampler: config[:log_sampler],
   &block
 )
 ```
@@ -743,6 +788,15 @@ rql.queued?("your_lock_name") # => true/false
   - `: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]`;
 - if you try to unlock non-existent lock you will receive `ok: true` result with operation timings
   and `:nothing_to_release` result factor inside;
 
@@ -793,6 +847,15 @@ rql.unlock("your_lock_name")
     - pre-configured value in `config[:isntrumenter]`;
   - `:instrument` - (optional) `[NilClass,Any]`
     - custom instrumentation data wich will be passed to the instrumenter's payload with `:instrument` key;
+  - `: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]`;
 - returns:
   - `[Hash<Symbol,Numeric>]` - Format: `{ ok: true, result: Hash<Symbol,Numeric> }`;
   - result data:
@@ -828,6 +891,15 @@ rql.clear_locks
   - `:logger` - (optional) `[::Logger,#debug]`
     - custom logger object;
     - pre-configured in `config[:logger]`;
+  - `: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]`;
 - returns `{ ok: true, result: :ttl_extended }` when ttl is extended;
 - returns `{ ok: false, result: :async_expire_or_no_lock }` when a lock not found or a lock is already expired during
   some steps of invocation (see **Important** section below);
@@ -1056,6 +1128,15 @@ Accepts:
 - `: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]`;
 
 Returns: `{ ok: true, processed_queues: Set<String> }` returns the list of processed lock queues;
 
@@ -1087,7 +1168,7 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
   - by default behavior (`:wait_for_lock`) your lock obtaining process will work in a classic way (limits, retries, etc);
   - `:work_through`, `:extendable_work_through` works with limits too (timeouts, delays, etc), but the decision of
     "is your lock are obtained or not" is made as you work with **reentrant locks** (your process continues to use the lock without/with
-    lock's TTL accordingly);
+    lock's TTL extension accordingly);
   - for current implementation details check:
     - [Configuration](#configuration) documentation: see `config.default_conflict_strategy` config docs;
     - [#lock](#lock---obtain-a-lock) method documentation: see `conflict_strategy` attribute docs and the method result data;
@@ -1254,6 +1335,7 @@ Detalized event semantics and payload structure:
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - **Major**:
+  - precent-based instrumentation sampling (instrument the concrete % of cases via "sampling" strategy);
   - support for Random Access strategy (non-queued behavior);
   - lock request prioritization;
   - **strict redlock algorithm support** (support for many `RedisClient` instances);
@@ -1264,8 +1346,6 @@ Detalized event semantics and payload structure:
   - support for `Dragonfly` database backend (https://github.com/dragonflydb/dragonfly) (https://www.dragonflydb.io/);
 - **Minor**:
   - Semantic error objects for unexpected Redis errors;
-  - change all `::Process.clock_gettime(::Process::CLOCK_MONOTONIC)` milliseconds-related invocations to
-    `::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)` in order to reduce time-related math operations count;
   - **Experimental feature**: (non-`timed` locks): per-ruby-block-holding-the-lock sidecar `Ractor` and `in progress queue` in RedisDB that will extend
     the acquired lock for long-running blocks of code (that invoked "under" the lock
     whose ttl may expire before the block execution completes). It makes sense for non-`timed` locks *only*;

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

@@ -28,11 +28,12 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @param fail_fast [Boolean]
   # @param conflict_strategy [Symbol]
   # @param meta [NilClass,Hash<String|Symbol,Any>]
+  # @param log_sampled [Boolean]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol|Hash<Symbol,Any> }
   #
   # @api private
   # @since 1.0.0
-  # @version 1.3.0
+  # @version 1.5.0
   # rubocop:disable Metrics/MethodLength
   def try_to_lock(
     redis,
@@ -46,14 +47,15 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     queue_ttl,
     fail_fast,
     conflict_strategy,
-    meta
+    meta,
+    log_sampled
   )
     # Step X: intermediate invocation results
     inter_result = nil
     timestamp = nil
     spc_processed_timestamp = nil
 
-    if log_lock_try
+    if log_sampled && log_lock_try
       run_non_critical do
         logger.debug do
           "[redis_queued_locks.try_lock.start] " \
@@ -66,7 +68,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
 
     # Step X: start to work with lock acquiring
     result = redis.with do |rconn|
-      if log_lock_try
+      if log_sampled && log_lock_try
         run_non_critical do
           logger.debug do
             "[redis_queued_locks.try_lock.rconn_fetched] " \
@@ -88,7 +90,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
 
         # SP-Conflict Step X1: calculate the current deadlock status
         if current_lock_obtainer != nil && acquier_id == current_lock_obtainer
-          if log_lock_try
+          if log_sampled && log_lock_try
             run_non_critical do
               logger.debug do
                 "[redis_queued_locks.try_lock.same_process_conflict_detected] " \
@@ -124,7 +126,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           end
           # rubocop:enable Lint/DuplicateBranch
 
-          if log_lock_try
+          if log_sampled && log_lock_try
             run_non_critical do
               logger.debug do
                 "[redis_queued_locks.try_lock.same_process_conflict_analyzed] " \
@@ -172,7 +174,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           )
           inter_result = :extendable_conflict_work_through
 
-          if log_lock_try
+          if log_sampled && log_lock_try
             run_non_critical do
               logger.debug do
                 "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through] " \
@@ -205,7 +207,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
             'l_spc_ts', (spc_processed_timestamp = Time.now.to_f)
           )
 
-          if log_lock_try
+          if log_sampled && log_lock_try
             run_non_critical do
               logger.debug do
                 "[redis_queued_locks.try_lock.reentrant_lock__work_through] " \
@@ -222,7 +224,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           inter_result = :conflict_dead_lock
           spc_processed_timestamp = Time.now.to_f
 
-          if log_lock_try
+          if log_sampled && log_lock_try
             logger.debug do
               "[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock] " \
               "lock_key => '#{lock_key}' " \
@@ -242,7 +244,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           # Step 1: add an acquier to the lock acquirement queue
           rconn.call('ZADD', lock_key_queue, 'NX', acquier_position, acquier_id)
 
-          if log_lock_try
+          if log_sampled && log_lock_try
             run_non_critical do
               logger.debug do
                 "[redis_queued_locks.try_lock.acq_added_to_queue] " \
@@ -261,7 +263,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
             RedisQueuedLocks::Resource.acquier_dead_score(queue_ttl)
           )
 
-          if log_lock_try
+          if log_sampled && log_lock_try
             run_non_critical do
               logger.debug do
                 "[redis_queued_locks.try_lock.remove_expired_acqs] " \
@@ -275,7 +277,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           # Step 3: get the actual acquier waiting in the queue
           waiting_acquier = Array(rconn.call('ZRANGE', lock_key_queue, '0', '0')).first
 
-          if log_lock_try
+          if log_sampled && log_lock_try
             run_non_critical do
               logger.debug do
                 "[redis_queued_locks.try_lock.get_first_from_queue] " \
@@ -290,7 +292,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           # Step PRE-4.x: check if the request time limit is reached
           #   (when the current try self-removes itself from queue (queue ttl has come))
           if waiting_acquier == nil
-            if log_lock_try
+            if log_sampled && log_lock_try
               run_non_critical do
                 logger.debug do
                   "[redis_queued_locks.try_lock.exit__queue_ttl_reached] " \
@@ -306,7 +308,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
           elsif waiting_acquier != acquier_id
             # Step ROLLBACK 1.1: our time hasn't come yet. retry!
 
-            if log_lock_try
+            if log_sampled && log_lock_try
               run_non_critical do
                 logger.debug do
                   "[redis_queued_locks.try_lock.exit__no_first] " \
@@ -329,7 +331,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
             if locked_by_acquier
               # Step ROLLBACK 2: required lock is stil acquired. retry!
 
-              if log_lock_try
+              if log_sampled && log_lock_try
                 run_non_critical do
                   logger.debug do
                     "[redis_queued_locks.try_lock.exit__lock_still_obtained] " \
@@ -363,7 +365,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
               # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
               transact.call('PEXPIRE', lock_key, ttl) # NOTE: in milliseconds
 
-              if log_lock_try
+              if log_sampled && log_lock_try
                 run_non_critical do
                   logger.debug do
                     "[redis_queued_locks.try_lock.obtain__free_to_acquire] " \
@@ -482,12 +484,21 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @param lock_key_queue [String]
   # @param queue_ttl [Integer]
   # @param acquier_id [String]
+  # @param log_sampled [Boolean]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 1.0.0
-  # @version 1.3.0
-  def dequeue_from_lock_queue(redis, logger, lock_key, lock_key_queue, queue_ttl, acquier_id)
+  # @version 1.5.0
+  def dequeue_from_lock_queue(
+    redis,
+    logger,
+    lock_key,
+    lock_key_queue,
+    queue_ttl,
+    acquier_id,
+    log_sampled
+  )
     result = redis.call('ZREM', lock_key_queue, acquier_id)
 
     run_non_critical do
@@ -497,7 +508,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
         "queue_ttl => '#{queue_ttl}' " \
         "acq_id => '#{acquier_id}'"
       end
-    end
+    end if log_sampled
 
     RedisQueuedLocks::Data[ok: true, result: result]
   end

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

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

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -86,6 +86,20 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #     - `:extendable_work_through`;
     #     - `:wait_for_lock`;
     #     - `:dead_locking`;
+    # @option log_sampling_enabled [Boolean]
+    #   - The percent of cases that should be logged;
+    #   - Sampling algorithm is super simple and works via SecureRandom.rand method
+    #     on the base of "weight" algorithm;
+    #   - You can provide your own sampler via config[:log_sampler] config and :sampler option
+    #     (see `RedisQueuedLocks::Logging::Sampler` for examples);
+    #   - The spread of guaranteed percent is approximately +13% (rand method spread);
+    #   - Take an effect when <log_sampling_enabled> parameter has <true> value
+    #     (when log sampling is enabled);
+    # @option log_sampling_percent [Integer]
+    #   - The percent of cases that should be logged;
+    #   - Take an effect when <log_sampling_enabled> parameter has <true> value
+    #     (when log sampling is enabled);
+    # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -118,6 +132,9 @@ module RedisQueuedLocks::Acquier::AcquireLock
       logger:,
       log_lock_try:,
       conflict_strategy:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
       &block
     )
       # Step 0: Prevent argument type incompatabilities
@@ -165,6 +182,12 @@ module RedisQueuedLocks::Acquier::AcquireLock
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
       acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
 
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sampling_percent,
+        log_sampler
+      )
+
       # Step X: intermediate result observer
       acq_process = {
         lock_info: {},
@@ -183,7 +206,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
           lock_key,
           lock_key_queue,
           queue_ttl,
-          acquier_id
+          acquier_id,
+          log_sampled
         )
       end
 
@@ -194,7 +218,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
           "queue_ttl => #{queue_ttl} " \
           "acq_id => '#{acquier_id}'"
         end
-      end
+      end if log_sampled
 
       # Step 2: try to lock with timeout
       with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
@@ -209,7 +233,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               "queue_ttl => #{queue_ttl} " \
               "acq_id => '{#{acquier_id}'"
             end
-          end
+          end if log_sampled
 
           # Step 2.X: check the actual score: is it in queue ttl limit or not?
           if RedisQueuedLocks::Resource.dead_score_reached?(acquier_position, queue_ttl)
@@ -223,7 +247,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                 "queue_ttl => #{queue_ttl} " \
                 "acq_id => '#{acquier_id}'"
               end
-            end
+            end if log_sampled
           end
 
           try_to_lock(
@@ -238,7 +262,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
             queue_ttl,
             fail_fast,
             conflict_strategy,
-            meta
+            meta,
+            log_sampled
           ) => { ok:, result: }
 
           acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
@@ -261,7 +286,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   "acq_id => '#{acquier_id}' " \
                   "acq_time => #{acq_time} (ms)"
                 end
-              end
+              end if log_sampled
 
               run_non_critical do
                 instrumenter.notify('redis_queued_locks.extendable_reentrant_lock_obtained', {
@@ -283,7 +308,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   "acq_id => '#{acquier_id}' " \
                   "acq_time => #{acq_time} (ms)"
                 end
-              end
+              end if log_sampled
 
               run_non_critical do
                 instrumenter.notify('redis_queued_locks.reentrant_lock_obtained', {
@@ -306,7 +331,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
                   "acq_id => '#{acquier_id}' " \
                   "acq_time => #{acq_time} (ms)"
                 end
-              end
+              end if log_sampled
 
               # Step X (instrumentation): lock obtained
               run_non_critical do
@@ -426,6 +451,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               ttl_shift,
               ttl,
               queue_ttl,
+              log_sampled,
               should_expire, # NOTE: should expire the lock after the block execution
               should_decrease, # NOTE: should decrease the lock ttl in reentrant locks?
               &block

data/lib/redis_queued_locks/acquier/clear_dead_requests.rb

@@ -10,11 +10,24 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
     # @param logger [::Logger,#debug]
     # @param instrumenter [#notify]
     # @param instrument [NilClass,Any]
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
     #
     # @api private
     # @since 1.0.0
-    def clear_dead_requests(redis_client, scan_size, dead_ttl, logger, instrumenter, instrument)
+    def clear_dead_requests(
+      redis_client,
+      scan_size,
+      dead_ttl,
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
+    )
       dead_score = RedisQueuedLocks::Resource.acquier_dead_score(dead_ttl / 1_000.0)
 
       result = Set.new.tap do |processed_queues|

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -17,11 +17,23 @@ module RedisQueuedLocks::Acquier::ExtendLockTTL
     # @param lock_name [String]
     # @param milliseconds [Integer]
     # @param logger [::Logger,#debug]
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     # @return [Hash<Symbol,Boolean|Symbol>]
     #
     # @api private
     # @since 1.0.0
-    def extend_lock_ttl(redis_client, lock_name, milliseconds, logger)
+    # @version 1.5.0
+    def extend_lock_ttl(
+      redis_client,
+      lock_name,
+      milliseconds,
+      logger,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
+    )
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 
       # NOTE: EVAL signature -> <lua script>, (number of keys), *(keys), *(arguments)

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -20,16 +20,33 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
     # @param isntrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @option instrument [NilClass,Any]
+    # @param instrument [NilClass,Any]
     #    - Custom instrumentation data wich will be passed to the instrumenter's payload
     #      with :instrument key;
+    # @param log_sampling_enabled [Boolean]
+    #   - Enables <log sampling>: only the configured percent of cases will be logged;
+    #   - Works in tandem with <log_samplng_percent> option;
+    # @param log_sampling_percent [Integer]
+    #   - The percent of cases that should be logged;
+    #   - Take an effect when <log_sampling_enabled> parameter has <true> value
+    #     (when log sampling is enabled);
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
     #   Format: { ok: true, result: Hash<Symbol,Numeric> }
     #
     # @api private
     # @since 1.0.0
-    # @version 1.4.0
-    def release_all_locks(redis, batch_size, logger, instrumenter, instrument)
+    # @version 1.5.0
+    def release_all_locks(
+      redis,
+      batch_size,
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
+    )
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
       fully_release_all_locks(redis, batch_size) => { ok:, result: }
       time_at = Time.now.to_f

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -23,13 +23,35 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
+    # @param log_sampling_enabled [Boolean]
+    #   - The percent of cases that should be logged;
+    #   - Sampling algorithm is super simple and works via SecureRandom.rand method
+    #     on the base of "weight" algorithm;
+    #   - You can provide your own sampler via config[:log_sampler] config and :sampler option
+    #     (see `RedisQueuedLocks::Logging::Sampler` for examples);
+    #   - The spread of guaranteed percent is approximately +13% (rand method spread);
+    #   - Take an effect when <log_sampling_enabled> parameter has <true> value
+    #     (when log sampling is enabled);
+    # @param log_sampling_percent [Integer]
+    #   - The percent of cases that should be logged;
+    #   - Take an effect when <log_sampling_enabled> parameter has <true> value
+    #     (when log sampling is enabled);
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean<Hash<Symbol,Numeric|String|Symbol>>]
     #   Format: { ok: true/false, result: Hash<Symbol,Numeric|String|Symbol> }
     #
     # @api private
     # @since 1.0.0
-    # @version 1.4.0
-    def release_lock(redis, lock_name, instrumenter, logger)
+    # @version 1.5.0
+    def release_lock(
+      redis,
+      lock_name,
+      instrumenter,
+      logger,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
+    )
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
 

data/lib/redis_queued_locks/client.rb

@@ -23,6 +23,9 @@ class RedisQueuedLocks::Client
     setting :dead_request_ttl, (1 * 24 * 60 * 60 * 1000) # NOTE: 1 day in milliseconds
     setting :is_timed_by_default, false
     setting :default_conflict_strategy, :wait_for_lock
+    setting :log_sampling_enabled, false
+    setting :log_sampling_percent, 15
+    setting :log_sampler, RedisQueuedLocks::Logging::Sampler
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
@@ -37,6 +40,9 @@ class RedisQueuedLocks::Client
     validate('log_lock_try', :boolean)
     validate('dead_request_ttl') { |val| val.is_a?(::Integer) && val > 0 }
     validate('is_timed_by_default', :boolean)
+    validate('log_sampler') { |val| RedisQueuedLocks::Logging.valid_sampler?(val) }
+    validate('log_sampling_enabled', :boolean)
+    validate('log_sampling_percent') { |val| val.is_a?(::Integer) && val >= 0 && val <= 100 }
     validate('default_conflict_strategy') do |val|
       # rubocop:disable Layout/MultilineOperationIndentation
       val == :work_through ||
@@ -130,6 +136,23 @@ class RedisQueuedLocks::Client
   # @option instrument [NilClass,Any]
   #   - Custom instrumentation data wich will be passed to the instrumenter's payload
   #     with :instrument key;
+  # @option log_sampling_enabled [Boolean]
+  #   - enables <log sampling>: only the configured percent of RQL cases will be logged;
+  #   - disabled by default;
+  #   - works in tandem with <config.log_sampling_percent and <log.sampler>;
+  # @option log_sampling_percent [Integer]
+  #   - the percent of cases that should be logged;
+  #   - take an effect when <config.log_sampling_enalbed> is true;
+  #   - works in tandem with <config.log_sampling_enabled> and <config.log_sampler> configs;
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+  #   - percent-based log sampler that decides should be RQL case logged or not;
+  #   - works in tandem with <config.log_sampling_enabled> and
+  #     <config.log_sampling_percent> configs;
+  #   - based on the ultra simple percent-based (weight-based) algorithm that uses SecureRandom.rand
+  #     method so the algorithm error is ~(0%..13%);
+  #   - you can provide your own log sampler with bettter algorithm that should realize
+  #     `sampling_happened?(percent) => boolean` interface
+  #     (see `RedisQueuedLocks::Logging::Sampler` for example);
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -138,7 +161,8 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.3.0
+  # @version 1.5.0
+  # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -156,6 +180,9 @@ class RedisQueuedLocks::Client
     logger: config[:logger],
     log_lock_try: config[:log_lock_try],
     instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
     &block
   )
     RedisQueuedLocks::Acquier::AcquireLock.acquire_lock(
@@ -178,18 +205,22 @@ class RedisQueuedLocks::Client
       fail_fast:,
       conflict_strategy:,
       meta:,
-      logger: config[:logger],
-      log_lock_try: config[:log_lock_try],
+      logger:,
+      log_lock_try:,
       instrument:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
       &block
     )
   end
+  # rubocop:enable Metrics/MethodLength
 
   # @note See #lock method signature.
   #
   # @api public
   # @since 1.0.0
-  # @version 1.3.0
+  # @version 1.5.0
   def lock!(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -206,6 +237,9 @@ class RedisQueuedLocks::Client
     logger: config[:logger],
     log_lock_try: config[:log_lock_try],
     instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler],
     &block
   )
     lock(
@@ -225,6 +259,9 @@ class RedisQueuedLocks::Client
       meta:,
       instrument:,
       conflict_strategy:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
       &block
     )
   end
@@ -233,6 +270,9 @@ class RedisQueuedLocks::Client
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
   # @return [RedisQueuedLocks::Data, Hash<Symbol,Any>]
   #   Format: {
   #     ok: true/false,
@@ -247,17 +287,24 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
+  # @version 1.5.0
   def unlock(
     lock_name,
     logger: config[:logger],
     instrumenter: config[:instrumenter],
-    instrument: nil
+    instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler]
   )
     RedisQueuedLocks::Acquier::ReleaseLock.release_lock(
       redis_client,
       lock_name,
       config[:instrumenter],
-      config[:logger]
+      config[:logger],
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
     )
   end
 
@@ -310,18 +357,44 @@ class RedisQueuedLocks::Client
   #
   # @param lock_name [String]
   # @param milliseconds [Integer] How many milliseconds should be added.
+  # @option logger [::Logger,#debug]
+  # @option log_sampling_enabled [Boolean]
+  #   - The percent of cases that should be logged;
+  #   - Sampling algorithm is super simple and works via SecureRandom.rand method
+  #     on the base of "weight" algorithm;
+  #   - You can provide your own sampler via config[:log_sampler] config and :sampler option
+  #     (see `RedisQueuedLocks::Logging::Sampler` for examples);
+  #   - The spread of guaranteed percent is approximately +13% (rand method spread);
+  #   - Take an effect when <log_sampling_enabled> parameter has <true> value
+  #     (when log sampling is enabled);
+  # @option log_sampling_percent [Integer]
+  #   - The percent of cases that should be logged;
+  #   - Take an effect when <log_sampling_enabled> parameter has <true> value
+  #     (when log sampling is enabled);
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
   # @return [Hash<Symbol,Boolean|Symbol>]
   #   - { ok: true, result: :ttl_extended }
   #   - { ok: false, result: :async_expire_or_no_lock }
   #
   # @api public
   # @since 1.0.0
-  def extend_lock_ttl(lock_name, milliseconds, logger: config[:logger])
+  # @version 1.5.0
+  def extend_lock_ttl(
+    lock_name,
+    milliseconds,
+    logger: config[:logger],
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler]
+  )
     RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
       redis_client,
       lock_name,
       milliseconds,
-      logger
+      logger,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
     )
   end
 
@@ -334,23 +407,33 @@ class RedisQueuedLocks::Client
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean|Hash<Symbol,Numeric>>]
   #   Example: { ok: true, result { rel_key_cnt: 100, rel_time: 0.01 } }
   #
   # @api public
   # @since 1.0.0
+  # @version 1.5.0
   def clear_locks(
     batch_size: config[:lock_release_batch_size],
     logger: config[:logger],
     instrumenter: config[:instrumenter],
-    instrument: nil
+    instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler]
   )
     RedisQueuedLocks::Acquier::ReleaseAllLocks.release_all_locks(
       redis_client,
       batch_size,
       logger,
       instrumenter,
-      instrument
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
     )
   end
 
@@ -438,18 +521,24 @@ class RedisQueuedLocks::Client
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
   # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
   #   Format: { ok: true, result: { processed_queus: Set<String> } }
   #
   # @api public
   # @since 1.0.0
-  # @version 1.1.0
+  # @version 1.5.0
   def clear_dead_requests(
     dead_ttl: config[:dead_request_ttl],
     scan_size: config[:lock_release_batch_size],
     logger: config[:logger],
     instrumenter: config[:instrumenter],
-    instrument: nil
+    instrument: nil,
+    log_sampling_enabled: config[:log_sampling_enabled],
+    log_sampling_percent: config[:log_sampling_percent],
+    log_sampler: config[:log_sampler]
   )
     RedisQueuedLocks::Acquier::ClearDeadRequests.clear_dead_requests(
       redis_client,
@@ -457,7 +546,10 @@ class RedisQueuedLocks::Client
       dead_ttl,
       logger,
       instrumenter,
-      instrument
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler
     )
   end
 end

data/lib/redis_queued_locks/logging/sampler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.5.0
+module RedisQueuedLocks::Logging::Sampler
+  class << self
+    # Super simple probalistic function based on the `weight` of <true>/<false> values.
+    # Requires the <percent> parameter as the required percent of <true> values sampled.
+    #
+    # @param sampling_percent [Integer]
+    #   - percent of <true> values in range of 0..100;
+    # @return [Boolean]
+    #   - <true> for <sampling_percent>% of invocations (and <false> for the rest invocations)
+    #
+    # @api private
+    # @since 1.5.0
+    def sampling_happened?(sampling_percent)
+      sampling_percent >= SecureRandom.rand(0..100)
+    end
+  end
+end

data/lib/redis_queued_locks/logging.rb

@@ -4,8 +4,54 @@
 # @since 1.0.0
 module RedisQueuedLocks::Logging
   require_relative 'logging/void_logger'
+  require_relative 'logging/sampler'
 
   class << self
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 1.5.0
+    def should_log?(log_sampling_enabled, log_sampling_percent, log_sampler)
+      return true unless log_sampling_enabled
+      log_sampler.sampling_happened?(log_sampling_percent)
+    end
+
+    # @param sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 1.5.0
+    def valid_sampler?(sampler)
+      return false unless sampler.respond_to?(:sampling_happened?)
+
+      m_obj = sampler.method(:sampling_happened?)
+      m_sig = m_obj.parameters
+
+      # NOTE:
+      #   Required method signature (sampling_percent)
+      #     => [[:req, :sampling_percent]]
+      #     => [[:opt, :sampling_percent]]
+      #     => [[:req, :sampling_percent], [:block, :block]]
+      #     => [[:opt, :sampling_percent], [:block, :block]]
+      if m_sig.size == 1
+        prm = m_sig[0][0]
+        prm == :req || prm == :opt
+      elsif m_sig.size == 2
+        f_prm = m_sig[0][0]
+        s_prm = m_sign[1][0]
+
+        # rubocop:disable Layout/MultilineOperationIndentation
+        f_prm == :req && s_prm == :block ||
+        f_prm == :opt && s_prm == :block
+        # rubocop:enable Layout/MultilineOperationIndentation
+      else
+        false
+      end
+    end
+
     # @param logger [::Logger,#debug,::SemanticLogger::Logger]
     # @return [Boolean]
     #

data/lib/redis_queued_locks/utilities.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.0.0
+# @version 1.5.0
 module RedisQueuedLocks::Utilities
   module_function
 

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 1.4.0
-  VERSION = '1.4.0'
+  # @version 1.5.0
+  VERSION = '1.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-13 00:00:00.000000000 Z
+date: 2024-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -81,6 +81,7 @@ files:
 - lib/redis_queued_locks/instrument/active_support.rb
 - lib/redis_queued_locks/instrument/void_notifier.rb
 - lib/redis_queued_locks/logging.rb
+- lib/redis_queued_locks/logging/sampler.rb
 - lib/redis_queued_locks/logging/void_logger.rb
 - lib/redis_queued_locks/resource.rb
 - lib/redis_queued_locks/utilities.rb