semantic_logger 4.17.0 → 5.0.0

data/lib/semantic_logger/queue_processor.rb

@@ -0,0 +1,369 @@
+module SemanticLogger
+  # Internal class that processes log messages from a queue on a separate thread.
+  #
+  # Internal use only: it owns the worker thread and the in-memory queue that back the
+  # asynchronous appender proxy (SemanticLogger::Appender::Async). It is never returned to
+  # application code.
+  #
+  # Supports two processing modes, selected by the `batch:` option:
+  #   * Streaming (batch: false): each log message is written to the appender as it is dequeued.
+  #   * Batching  (batch: true):  log messages are grouped and written via the appender's #batch
+  #                               method, either once batch_size messages have accumulated, or
+  #                               batch_seconds have elapsed since the previous batch.
+  class QueueProcessor
+    attr_accessor :lag_check_interval, :lag_threshold_s, :dropped_message_report_seconds,
+                  :batch_size, :batch_seconds
+    attr_reader :appender, :queue, :max_queue_size, :non_blocking, :signal,
+                :processed_count, :dropped_count, :async_max_retries, :retry_count
+
+    # Create a new processor and start its worker thread.
+    def self.start(**args)
+      processor = new(**args)
+      processor.thread
+      processor
+    end
+
+    # Parameters:
+    #   appender: [SemanticLogger::Subscriber]
+    #     The appender to forward log messages to from the worker thread.
+    #
+    #   max_queue_size: [Integer]
+    #     The maximum number of log messages to hold on the queue before blocking attempts to add to the queue.
+    #     -1: The queue size is uncapped and will never block no matter how long the queue is.
+    #     Default: 10,000
+    #
+    #   lag_threshold_s: [Float]
+    #     Log a warning when a log message has been on the queue for longer than this period in seconds.
+    #     Default: 30
+    #
+    #   lag_check_interval: [Integer]
+    #     Number of messages to process before checking for slow logging.
+    #     Default: 1,000
+    #     Note: Not applicable when batch: true.
+    #
+    #   batch: [true|false]
+    #     Process log messages in batches via the appender's #batch method.
+    #     Default: false
+    #     Note: The appender must implement #batch.
+    #
+    #   batch_size: [Integer]
+    #     Maximum number of messages to batch up before sending.
+    #     Default: 300
+    #     Note: Only applicable when batch: true.
+    #
+    #   batch_seconds: [Integer]
+    #     Maximum number of seconds between sending batches.
+    #     Default: 5
+    #     Note: Only applicable when batch: true.
+    #
+    #   non_blocking: [true|false]
+    #     Whether to drop log messages instead of blocking the calling thread when the queue is full.
+    #     Only applies to a capped queue.
+    #     Default: false
+    #
+    #   dropped_message_report_seconds: [Integer]
+    #     When non_blocking is enabled, log the count of dropped messages to the internal logger
+    #     at most once every this number of seconds.
+    #     Default: 30
+    #
+    #   async_max_retries: [Integer]
+    #     Maximum number of consecutive times to restart the worker thread after it raises an
+    #     exception while processing messages. Each restart first sleeps for `retry_count` seconds
+    #     (1s, then 2s, ...) as a back-off. Once this many consecutive retries are exhausted the
+    #     thread stops instead of restarting. The counter resets to zero whenever a message is
+    #     processed successfully.
+    #     -1: Retry indefinitely and never stop the thread (the pre-v5 behaviour). The back-off
+    #         still applies, and still resets after any successful message.
+    #     Default: 100
+    def initialize(appender:,
+                   max_queue_size: 10_000,
+                   lag_check_interval: 1_000,
+                   lag_threshold_s: 30,
+                   batch: false,
+                   batch_size: 300,
+                   batch_seconds: 5,
+                   non_blocking: false,
+                   dropped_message_report_seconds: 30,
+                   async_max_retries: 100)
+      @appender                       = appender
+      @max_queue_size                 = max_queue_size
+      @lag_check_interval             = lag_check_interval
+      @lag_threshold_s                = lag_threshold_s
+      @batch                          = batch
+      @batch_size                     = batch_size
+      @batch_seconds                  = batch_seconds
+      @non_blocking                   = non_blocking
+      @dropped_message_report_seconds = dropped_message_report_seconds
+      @async_max_retries              = async_max_retries
+      @retry_count                    = 0
+      @thread                         = nil
+      # Only batch mode parks the worker on the signal; streaming mode never touches it.
+      @signal                         = Concurrent::Event.new if batch
+      @dropped_message_count          = 0
+      @dropped_message_reported_at    = Time.now
+      @dropped_message_mutex          = Mutex.new
+      @processed_count                = 0
+      @dropped_count                  = 0
+      create_queue
+
+      return unless batch? && !appender.respond_to?(:batch)
+
+      raise(ArgumentError, "#{appender.class.name} does not support batching. It must implement #batch")
+    end
+
+    # Internal logger used to report problems encountered while processing log messages.
+    def logger
+      appender.logger
+    end
+
+    # Returns [Thread] the worker thread.
+    #
+    # Starts the worker thread if it is not currently running.
+    def thread
+      return @thread if @thread&.alive?
+
+      @thread = spawn_worker
+    end
+
+    # Returns [true|false] whether the worker thread is running.
+    def active?
+      @thread&.alive?
+    end
+
+    # Returns [true|false] whether the queue has a capped size.
+    def capped?
+      @capped
+    end
+
+    # Returns [true|false] whether messages are dropped instead of blocking when the queue is full.
+    # Only a capped queue can drop messages.
+    def non_blocking?
+      @non_blocking && capped?
+    end
+
+    # Returns [true|false] whether messages are processed in batches.
+    def batch?
+      @batch
+    end
+
+    # Add a log message to the queue for processing.
+    #
+    # When non-blocking and the queue is full, the message is dropped instead of blocking the
+    # calling thread, and the count of dropped messages is reported periodically.
+    def log(log)
+      enqueued = true
+      if non_blocking?
+        begin
+          queue.push(log, true)
+        rescue ThreadError
+          message_dropped
+          enqueued = false
+        end
+      else
+        queue << log
+      end
+
+      # For batches wake up the processing thread once the number of queued messages has been
+      # exceeded. Also wake it on a drop so it drains the full queue rather than waiting out the
+      # batch interval.
+      signal.set if batch? && (queue.size >= batch_size)
+
+      enqueued
+    end
+
+    # Flush all queued log entries to the appender.
+    #  All queued log messages are written and then the appender is flushed.
+    def flush
+      submit_request(:flush)
+    end
+
+    # Flush any outstanding messages and close the appender.
+    def close
+      submit_request(:close)
+    end
+
+    # Re-open the queue and worker thread after a fork.
+    def reopen
+      # Workaround CRuby crash on fork by recreating queue on reopen
+      #   https://github.com/reidmorrison/semantic_logger/issues/103
+      @queue&.close
+      create_queue
+
+      @thread&.kill if @thread&.alive?
+      @thread = spawn_worker
+    end
+
+    private
+
+    # Start the worker thread, naming it after the internal logger.
+    def spawn_worker
+      Thread.new do
+        Thread.current.name = logger.name
+        process
+      end
+    end
+
+    def create_queue
+      if max_queue_size == -1
+        @queue  = Queue.new
+        @capped = false
+      else
+        @queue  = SizedQueue.new(max_queue_size)
+        @capped = true
+      end
+    end
+
+    # Separate thread for processing log messages.
+    def process
+      # This thread is designed to never go down unless the main thread terminates
+      # or the appender is closed.
+      logger.trace "Async: Appender thread active"
+      begin
+        batch? ? process_messages_in_batches : process_messages
+      rescue StandardError => e
+        if async_max_retries == -1 || retry_count < async_max_retries
+          @retry_count += 1
+          limit = async_max_retries == -1 ? "unlimited" : async_max_retries
+          safe_log(:warn, "Async: Restarting due to exception, retry #{retry_count} of #{limit}, sleeping #{retry_count}s", e)
+          sleep(retry_count)
+          retry
+        else
+          safe_log(:error, "Async: Stopping after #{retry_count} failed retries", e)
+        end
+      rescue Exception => e
+        safe_log(:error, "Async: Stopping due to fatal exception", e)
+      ensure
+        @thread = nil
+        safe_log(:trace, "Async: Thread has stopped")
+      end
+    end
+
+    # Log to the internal logger, ignoring any error.
+    # These calls may run after Ruby has released file handles during shutdown.
+    def safe_log(level, message, exception = nil)
+      logger.public_send(level, message, exception)
+    rescue StandardError
+      nil
+    end
+
+    # Streaming: write each log message to the appender as it is dequeued.
+    def process_messages
+      count = 0
+      while (message = queue.pop)
+        if message.is_a?(Log)
+          appender.log(message)
+          @processed_count += 1
+          @retry_count = 0 unless retry_count.zero?
+          count += 1
+          # Check every few log messages whether this appender thread is falling behind
+          if count > lag_check_interval
+            check_lag(message)
+            count = 0
+          end
+        else
+          break unless process_message(message)
+        end
+      end
+      logger.trace "Async: Queue Closed"
+    end
+
+    # Batching: group up log messages before writing them via the appender's #batch method.
+    def process_messages_in_batches
+      loop do
+        # Wait for batch interval or number of messages to be exceeded.
+        signal.wait(batch_seconds)
+
+        logs          = []
+        messages      = []
+        first         = true
+        message_count = queue.length
+        message_count.times do
+          # Queue#pop(true) raises an exception when there are no more messages, which is considered expensive.
+          message = queue.pop
+          if message.is_a?(Log)
+            logs << message
+            if first
+              check_lag(message)
+              first = false
+            end
+          else
+            messages << message
+          end
+        end
+        if logs.size.positive?
+          appender.batch(logs)
+          @processed_count += logs.size
+          @retry_count = 0 unless retry_count.zero?
+        end
+        # Stop processing once a command (e.g. :close) signals the thread to terminate.
+        break if messages.any? { |message| !process_message(message) }
+
+        signal.reset unless queue.size >= batch_size
+      end
+    end
+
+    # Returns false when message processing should be stopped.
+    def process_message(message)
+      case message[:command]
+      when :flush
+        appender.flush
+        message[:reply_queue] << true if message[:reply_queue]
+      when :close
+        appender.close
+        message[:reply_queue] << true if message[:reply_queue]
+        return false
+      else
+        logger.warn "Async: Appender thread: Ignoring unknown command: #{message[:command]}"
+      end
+      true
+    end
+
+    # Record a dropped message, reporting the running count to the internal logger at most
+    # once every dropped_message_report_seconds.
+    def message_dropped
+      @dropped_message_mutex.synchronize do
+        @dropped_message_count += 1
+        @dropped_count         += 1
+        diff = Time.now - @dropped_message_reported_at
+        return if diff < dropped_message_report_seconds
+
+        logger.warn(
+          "Async: Dropped #{@dropped_message_count} log messages in the last #{diff.round} seconds. " \
+          "The queue is full (max_queue_size: #{max_queue_size}). " \
+          "Consider reducing the log level, increasing max_queue_size, or changing the appenders"
+        )
+        @dropped_message_count       = 0
+        @dropped_message_reported_at = Time.now
+      end
+    end
+
+    def check_lag(log)
+      diff = Time.now - log.time
+      return unless diff > lag_threshold_s
+
+      logger.warn "Async: Appender thread has fallen behind by #{diff} seconds with #{queue.size} messages queued up. Consider reducing the log level or changing the appenders"
+    end
+
+    # Submit a command to the worker thread and wait for the reply.
+    def submit_request(command)
+      return false unless active?
+
+      queue_size = queue.size
+      msg        = "Async: Queued log messages: #{queue_size}, running command: #{command}"
+      if queue_size > 1_000
+        logger.warn msg
+      elsif queue_size > 100
+        logger.info msg
+      elsif queue_size.positive?
+        logger.trace msg
+      end
+
+      # Wake up the processing thread to process this command immediately.
+      signal.set if batch?
+
+      reply_queue = Queue.new
+      queue << {command: command, reply_queue: reply_queue}
+      reply_queue.pop
+    end
+  end
+end

data/lib/semantic_logger/reporters/minitest.rb

@@ -28,18 +28,18 @@ module SemanticLogger
       attr_accessor :io
 
       def before_test(test)
-        logger.info("START #{test.class_name} #{test.name}")
+        logger.info("START #{test.class.name} #{test.name}")
       end
 
       def after_test(test)
         if test.error?
-          logger.benchmark_error("FAIL #{test.class_name} #{test.name}", duration: test.time * 1_000,
+          logger.benchmark_error("FAIL #{test.class.name} #{test.name}", duration: test.time * 1_000,
                                                                          metric:   "minitest/fail")
         elsif test.skipped?
-          logger.benchmark_warn("SKIP #{test.class_name} #{test.name}", duration: test.time * 1_000,
+          logger.benchmark_warn("SKIP #{test.class.name} #{test.name}", duration: test.time * 1_000,
                                                                         metric:   "minitest/skip")
         else
-          logger.benchmark_info("PASS #{test.class_name} #{test.name}", duration: test.time * 1_000,
+          logger.benchmark_info("PASS #{test.class.name} #{test.name}", duration: test.time * 1_000,
                                                                         metric:   "minitest/pass")
         end
       end

data/lib/semantic_logger/semantic_logger.rb

@@ -4,9 +4,42 @@ module SemanticLogger
   # Logging levels in order of most detailed to most severe
   LEVELS = Levels::LEVELS
 
-  # Return a logger for the supplied class or class_name
+  # Return a logger for the supplied class or class_name.
+  #
+  # When `SemanticLogger.cache_loggers` is enabled (opt-in, default off) and a
+  # Class or Module is supplied, the same Logger instance is returned for every
+  # call with that class. This makes it possible to obtain a logger once and
+  # later change its level (or filter) and have every holder of that logger see
+  # the change.
+  #
+  # A String is always given its own new Logger instance, even when caching is
+  # enabled: callers that pass a string typically want an independent logger
+  # (for example to set a different level per call site). Anonymous classes
+  # (those with no `name`) are never cached, to avoid pinning short-lived
+  # dynamically created classes in memory.
   def self.[](klass)
-    Logger.new(klass)
+    return Logger.new(klass) if !@cache_loggers || klass.is_a?(String) || klass.name.nil?
+
+    logger_cache.compute_if_absent(klass) { Logger.new(klass) }
+  end
+
+  # Whether `SemanticLogger[Class]` returns a shared, cached Logger instance per
+  # class. Disabled by default. Strings are never cached (see #[]).
+  def self.cache_loggers=(cache_loggers)
+    @cache_loggers = cache_loggers
+    clear_logger_cache unless cache_loggers
+  end
+
+  # Returns whether logger caching is enabled.
+  def self.cache_loggers?
+    @cache_loggers
+  end
+
+  # Discard all cached loggers so that subsequent `SemanticLogger[Class]` calls
+  # build fresh instances. Primarily useful in tests, or after redefining a
+  # class that was previously cached.
+  def self.clear_logger_cache
+    @logger_cache&.clear
   end
 
   # Sets the global default log level
@@ -162,8 +195,8 @@ module SemanticLogger
   #   logger = SemanticLogger['Example']
   #   logger.info "Hello World"
   #   logger.debug("Login time", user: 'Joe', duration: 100, ip_address: '127.0.0.1')
-  def self.add_appender(**args, &block)
-    appender = appenders.add(**args, &block)
+  def self.add_appender(**args, &)
+    appender = appenders.add(**args, &)
     # Start appender thread if it is not already running
     Logger.processor.start
     appender
@@ -202,14 +235,43 @@ module SemanticLogger
     Logger.processor.close
   end
 
-  # After forking an active process call SemanticLogger.reopen to re-open
-  # any open file handles etc to resources.
+  # Re-open any open file handles etc. to resources.
+  #
+  # Called automatically in the child process after a fork (see reopen_on_fork?),
+  # and may also be called manually.
+  #
+  # To avoid reopening twice after a single fork (for example when the automatic
+  # fork hook and a framework's `after_fork` callback both fire), reopen is a no-op
+  # if it has already run in the current process. Pass `force: true` to override
+  # this guard and reopen unconditionally, for example when re-opening file handles
+  # in the same process after an external log rotation.
   #
   # Note:
   #   Not all appender's implement reopen.
   #   Check the code for each appender you are using before relying on this behavior.
-  def self.reopen
+  def self.reopen(force: false)
+    return if !force && @reopened_pid == ::Process.pid
+
     Logger.processor.reopen
+    @reopened_pid = ::Process.pid
+  end
+
+  # Whether appenders are automatically reopened in the child process after a fork.
+  #
+  # Enabled by default. A `Process._fork` hook (Ruby 3.1+) calls SemanticLogger.reopen
+  # in the child after `fork`, `Process.daemon`, `IO.popen`, `Kernel#system`, and
+  # backticks, so framework specific `after_fork` hooks (Puma, Unicorn, Resque,
+  # Spring, etc.) are no longer required.
+  def self.reopen_on_fork?
+    @reopen_on_fork != false
+  end
+
+  # Enable or disable automatic reopening of appenders after a fork.
+  #
+  #   # Opt out of the automatic behavior and manage reopen manually:
+  #   SemanticLogger.reopen_on_fork = false
+  def self.reopen_on_fork=(reopen_on_fork)
+    @reopen_on_fork = reopen_on_fork
   end
 
   # Supply a callback to be called whenever a log entry is created.
@@ -236,8 +298,8 @@ module SemanticLogger
   # Note:
   # * This callback is called within the thread of the application making the logging call.
   # * If these callbacks are slow they will slow down the application.
-  def self.on_log(object = nil, &block)
-    Logger.subscribe(object, &block)
+  def self.on_log(object = nil, &)
+    Logger.subscribe(object, &)
   end
 
   # Add signal handlers for Semantic Logger
@@ -342,13 +404,13 @@ module SemanticLogger
   #     `logger.tagged([['first', nil], nil, ['more'], 'other'])`
   #   to the equivalent of:
   #     `logger.tagged('first', 'more', 'other')`
-  def self.tagged(*tags, &block)
+  def self.tagged(*tags, &)
     return yield if tags.empty?
 
     # Allow named tags to be passed into the logger
     if tags.size == 1
       tag = tags[0]
-      return tag.is_a?(Hash) ? named_tagged(tag, &block) : fast_tag(tag, &block)
+      return tag.is_a?(Hash) ? named_tagged(tag, &) : fast_tag(tag, &)
     end
 
     begin
@@ -475,6 +537,27 @@ module SemanticLogger
     Logger.processor.queue.size
   end
 
+  # Returns [Hash] operational statistics for the logging pipeline.
+  #
+  # Useful for exporting Semantic Logger's own health to a monitoring system such as
+  # Prometheus, statsd, etc. The returned Hash contains:
+  #
+  #   queue_size:     [Integer] Number of log messages waiting on the main pipeline queue.
+  #   capped:         [Boolean] Whether the main queue has a maximum size.
+  #   max_queue_size: [Integer] Maximum queue size, or nil when uncapped.
+  #   thread_active:  [Boolean] Whether the main pipeline thread is running.
+  #   processed:      [Integer] Cumulative number of log messages processed since startup.
+  #   dropped:        [Integer] Cumulative number of log messages dropped at the main queue.
+  #   appenders:      [Array<Hash>] Per-appender statistics. Appenders that run their own
+  #                                 async thread report their queue_size and processed/dropped
+  #                                 counts; appenders that log inline report `async: false`.
+  #
+  # All counters are cumulative since process startup. They are thread-safe to read and
+  # are maintained without adding any locking to the logging hot path.
+  def self.stats
+    Logger.processor.stats
+  end
+
   # Returns the check_interval which is the number of messages between checks
   # to determine if the appender thread is falling behind.
   def self.lag_check_interval
@@ -516,6 +599,14 @@ module SemanticLogger
   @backtrace_level       = :error
   @backtrace_level_index = Levels.index(@backtrace_level)
   @sync                  = false
+  @cache_loggers         = false
+  @logger_cache          = nil
+
+  # Lazily initialized thread-safe cache of one Logger per Class/Module.
+  def self.logger_cache
+    @logger_cache ||= Concurrent::Map.new
+  end
+  private_class_method :logger_cache
 
   # @formatter:off
   module Metric
@@ -531,6 +622,7 @@ module SemanticLogger
   module Test
     autoload :CaptureLogEvents,  "semantic_logger/test/capture_log_events"
     autoload :Minitest,          "semantic_logger/test/minitest"
+    autoload :RSpec,             "semantic_logger/test/rspec"
   end
 
   if defined?(JRuby)

data/lib/semantic_logger/subscriber.rb

@@ -73,9 +73,22 @@ module SemanticLogger
       super && (log.metric_only? ? metrics? : true)
     end
 
-    # Whether this appender is logging to stdout or stderror
+    # The console stream this appender writes to, if any.
+    # Returns one of :stdout, :stderr, or nil when not writing to a console stream.
+    def console_stream
+      nil
+    end
+
+    # Whether this appender is logging to stdout or stderr.
     def console_output?
-      false
+      !console_stream.nil?
+    end
+
+    # Whether an appender that implements #batch should be wrapped in a batch
+    # proxy automatically. Appenders that support batching but should only batch
+    # when explicitly requested (via `batch: true`) override this to return false.
+    def batch_by_default?
+      true
     end
 
     private

data/lib/semantic_logger/sync_processor.rb

@@ -9,7 +9,28 @@ module SemanticLogger
     end
 
     def log(...)
-      @monitor.synchronize { @appenders.log(...) }
+      @monitor.synchronize do
+        @processed_count += 1
+        @appenders.log(...)
+      end
+    end
+
+    # Returns [Hash] operational statistics for the logging pipeline.
+    #
+    # In synchronous mode there is no queue: messages are written inline on the calling
+    # thread, so queue_size is always 0 and no messages can be dropped.
+    def stats
+      @monitor.synchronize do
+        {
+          queue_size:     0,
+          capped:         false,
+          max_queue_size: nil,
+          thread_active:  false,
+          processed:      @processed_count,
+          dropped:        0,
+          appenders:      @appenders.stats
+        }
+      end
     end
 
     def flush
@@ -47,8 +68,9 @@ module SemanticLogger
     attr_reader :appenders
 
     def initialize(appenders = nil)
-      @monitor   = Monitor.new
-      @appenders = appenders || Appenders.new(self.class.logger.dup)
+      @monitor         = Monitor.new
+      @appenders       = appenders || Appenders.new(self.class.logger.dup)
+      @processed_count = 0
     end
 
     def start

data/lib/semantic_logger/test/capture_log_events.rb

@@ -34,8 +34,8 @@ module SemanticLogger
       end
 
       # Supports batching of log events
-      def batch(_logs)
-        @events += log
+      def batch(logs)
+        logs.each { |log| self.log(log) }
       end
 
       def clear

data/lib/semantic_logger/test/minitest.rb

@@ -57,15 +57,17 @@ module SemanticLogger
         if payload_includes
           payload_includes.each_pair do |key, expected|
             actual = event.payload[key]
-            assert_semantic_logger_entry(event, "payload #{name}", expected, actual)
+
+            assert_semantic_logger_entry(event, "payload #{key}", expected, actual)
           end
         end
 
         return unless exception_includes
 
-        payload_includes.each_pair do |key, expected|
+        exception_includes.each_pair do |key, expected|
           actual = event.exception.send(key)
-          assert_semantic_logger_entry(event, "Exception #{name}", expected, actual)
+
+          assert_semantic_logger_entry(event, "exception #{key}", expected, actual)
         end
       end
 
@@ -76,9 +78,11 @@ module SemanticLogger
 
         case expected
         when :nil
+
           assert_nil actual, "Expected nil #{name} for log event: #{event.to_h.inspect}"
         when Class
-          assert actual.is_a?(expected), lambda {
+
+          assert_kind_of expected, actual, lambda {
             "Type #{expected} expected for #{name} in log event: #{event.to_h.inspect}"
           }
         else