lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/device/buffer.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # A buffered logging device that wraps another logging device. Entries are buffered in memory
+  # until the buffer size is reached or the device is flushed.
+  #
+  # @example Create a buffered device that flushes every 5 entries
+  #   device = Lumberjack::Device::Buffer.new(Lumberjack::Device::LogFile.new("logfile.log"), buffer_size: 5)
+  #
+  # @example Create a buffered device that automatically flushes every 10 seconds
+  #   device = Lumberjack::Device::Buffer.new("/var/log/app.log", buffer_size: 10, flush_seconds: 10)
+  #
+  # @example Create a buffered device with a before_flush callback
+  #   before_flush = -> { puts "Flushing log buffer" }
+  #   device = Lumberjack::Device::Buffer.new(device, buffer_size: 10, before_flush: before_flush)
+  class Device::Buffer < Device
+    # Internal class that manages the entry buffer and flushing logic.
+    class EntryBuffer
+      attr_accessor :size
+
+      attr_reader :device, :last_flushed_at
+
+      def initialize(device, size, before_flush)
+        @device = device
+        @size = size
+        @before_flush = before_flush if before_flush.respond_to?(:call)
+        @lock = Mutex.new
+        @entries = []
+        @last_flushed_at = Time.now
+        @closed = false
+      end
+
+      def <<(entry)
+        return if closed?
+
+        @lock.synchronize do
+          @entries << entry
+        end
+
+        flush if @entries.size >= @size
+      end
+
+      def flush
+        entries = nil
+
+        if closed?
+          @before_flush&.call
+          entries = @entries
+          @entries = []
+        else
+          @lock.synchronize do
+            @before_flush&.call
+            entries = @entries
+            @entries = []
+          end
+        end
+
+        @last_flushed_at = Time.now
+
+        return if entries.nil?
+
+        entries.each do |entry|
+          @device.write(entry)
+        rescue => e
+          warn("Error writing log entry from buffer: #{e.inspect}")
+        end
+      end
+
+      def close
+        @closed = true
+        flush
+      end
+
+      def closed?
+        @closed
+      end
+
+      def reopen
+        @closed = false
+      end
+
+      def empty?
+        @entries.empty?
+      end
+    end
+
+    class << self
+      private
+
+      def create_finalizer(buffer) # :nodoc:
+        lambda { |object_id| buffer.close }
+      end
+
+      def create_flusher_thread(flush_seconds, buffer) # :nodoc:
+        Thread.new do
+          until buffer.closed?
+            sleep(flush_seconds)
+            buffer.flush if Time.now - buffer.last_flushed_at >= flush_seconds
+          end
+        end
+      end
+    end
+
+    # Initialize a new buffered logging device that wraps another device.
+    #
+    # @param wrapped_device [Lumberjack::Device, String, Symbol, IO] The underlying device to wrap.
+    #   This can be any valid device specification that +Lumberjack::Device.open_device+ accepts.
+    #   Options not related to buffering will be passed to the underlying device constructor.
+    # @param options [Hash] Options for the buffer and the underlying device.
+    # @option options [Integer] :buffer_size The number of entries to buffer before flushing. Default is 0 (no buffering).
+    # @option options [Integer] :flush_seconds If specified, a background thread will flush the buffer every N seconds.
+    # @option options [Proc] :before_flush A callback that will be called before each flush. The callback should
+    #  respond to +call+ and take no arguments.
+    def initialize(wrapped_device, options = {})
+      buffer_options = [:buffer_size, :flush_seconds, :before_flush]
+      device_options = options.reject { |k, _| buffer_options.include?(k) }
+      device = Device.open_device(wrapped_device, device_options)
+
+      @buffer = EntryBuffer.new(device, options[:buffer_size] || 0, options[:before_flush])
+
+      flush_seconds = options[:flush_seconds]
+      self.class.send(:create_flusher_thread, flush_seconds, @buffer) if flush_seconds.is_a?(Numeric) && flush_seconds > 0
+
+      # Add a finalizer to ensure flush is called before the object is destroyed
+      ObjectSpace.define_finalizer(self, self.class.send(:create_finalizer, @buffer))
+    end
+
+    def buffer_size
+      @buffer.size
+    end
+
+    # Set the buffer size. The underlying device will only be written to when the buffer size
+    # is exceeded.
+    #
+    # @param [Integer] value The size of the buffer in bytes.
+    # @return [void]
+    def buffer_size=(value)
+      @buffer.size = value
+      @buffer.flush
+    end
+
+    # Write an entry to the underlying device.
+    #
+    # @param [LogEntry, String] entry The entry to write.
+    # @return [void]
+    def write(entry)
+      @buffer << entry
+    end
+
+    # Close the device.
+    #
+    # @return [void]
+    def close
+      @buffer.close
+      @buffer.device.close
+
+      # Remove the finalizer since we've already flushed
+      ObjectSpace.undefine_finalizer(self)
+    end
+
+    # Return true if the buffer has been closed.
+    def closed?
+      @buffer.closed?
+    end
+
+    # Flush the buffer to the underlying device.
+    #
+    # @return [void]
+    def flush
+      @buffer.flush
+    end
+
+    # Reopen the underlying device, optionally with a new log destination.
+    def reopen(logdev = nil)
+      flush
+      @buffer.device.reopen(logdev)
+      @buffer.reopen
+      ObjectSpace.define_finalizer(self, self.class.send(:create_finalizer, @buffer))
+    end
+
+    # Return the underlying stream. Provided for API compatibility with Logger devices.
+    #
+    # @return [IO] The underlying stream.
+    def dev
+      @buffer.device.dev
+    end
+
+    # @api private
+    def last_flushed_at
+      @buffer.last_flushed_at
+    end
+
+    # @api private
+    def empty?
+      @buffer.empty?
+    end
+
+    private
+
+    def create_flusher_thread(flush_seconds, buffer) # :nodoc:
+      Thread.new do
+        until buffer.closed?
+          sleep(flush_seconds)
+          buffer.flush if Time.now - buffer.last_flushed_at >= flush_seconds
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/device/date_rolling_log_file.rb

@@ -3,72 +3,20 @@
 require "date"
 
 module Lumberjack
-  class Device
-    # This log device will append entries to a file and roll the file periodically by date. Files
-    # are rolled at midnight and can be rolled daily, weekly, or monthly. Archive file names will
-    # have the date appended to them in the format ".YYYY-MM-DD" for daily, ".week-of-YYYY-MM-DD" for weekly
-    # and ".YYYY-MM" for monthly. It is not guaranteed that log messages will break exactly on the
-    # roll period as buffered entries will always be written to the same file.
-    class DateRollingLogFile < RollingLogFile
-      # Create a new logging device to the specified file. The period to roll the file is specified
-      # with the :roll option which may contain a value of :daily, :weekly,
-      # or :monthly.
-      #
-      # @param [String, Pathname] path The path to the log file.
-      # @param [Hash] options The options for the device.
-      def initialize(path, options = {})
-        @manual = options[:manual]
-        @file_date = Date.today
-        if options[:roll]&.to_s&.match(/(daily)|(weekly)|(monthly)/i)
-          @roll_period = $~[0].downcase.to_sym
-          options.delete(:roll)
-        else
-          raise ArgumentError.new("illegal value for :roll (#{options[:roll].inspect})")
-        end
-        super
-      end
-
-      # The date based suffix for file.
-      #
-      # @return [String]
-      def archive_file_suffix
-        case @roll_period
-        when :weekly
-          @file_date.strftime("week-of-%Y-%m-%d").to_s
-        when :monthly
-          @file_date.strftime("%Y-%m").to_s
-        else
-          @file_date.strftime("%Y-%m-%d").to_s
-        end
-      end
+  # Deprecated device. Use LogFile instead.
+  #
+  # @deprecated Use Lumberjack::Device::LogFile
+  class Device::DateRollingLogFile < Device::LogFile
+    def initialize(path, options = {})
+      Utils.deprecated("Lumberjack::Device::DateRollingLogFile", "Lumberjack::Device::DateRollingLogFile is deprecated and will be removed in version 2.1; use Lumberjack::Device::LogFile instead.")
 
-      # Check if the file should be rolled.
-      #
-      # @return [Boolean]
-      def roll_file?
-        if @manual
-          true
-        else
-          date = Date.today
-          if date.year > @file_date.year
-            true
-          elsif @roll_period == :daily && date.yday > @file_date.yday
-            true
-          elsif @roll_period == :weekly && date.cweek != @file_date.cweek
-            true
-          elsif @roll_period == :monthly && date.month > @file_date.month
-            true
-          else
-            false
-          end
-        end
+      unless options[:roll]&.to_s&.match(/(daily)|(weekly)|(monthly)/i)
+        raise ArgumentError.new("illegal value for :roll (#{options[:roll].inspect})")
       end
 
-      protected
+      new_options = options.reject { |k, _| k == :roll }.merge(shift_age: options[:roll].to_s.downcase)
 
-      def after_roll
-        @file_date = Date.today
-      end
+      super(path, new_options)
     end
   end
 end

data/lib/lumberjack/device/log_file.rb

@@ -1,40 +1,87 @@
 # frozen_string_literal: true
 
-require "fileutils"
-
 module Lumberjack
-  class Device
-    # This is a logging device that appends log entries to a file.
-    class LogFile < Writer
-      EXTERNAL_ENCODING = "ascii-8bit"
+  # A file-based logging device that extends the Writer device with automatic
+  # log rotation capabilities. This device wraps Ruby's standard Logger::LogDevice
+  # to provide file size-based and time-based log rotation while maintaining
+  # compatibility with the Lumberjack device interface.
+  #
+  # The device supports all the rotation features available in Ruby's Logger,
+  # including maximum file size limits, automatic rotation based on age, and
+  # automatic cleanup of old log files. This makes it suitable for production
+  # environments where log management is crucial.
+  #
+  # @example Basic file logging
+  #   device = Lumberjack::Device::LogFile.new("/var/log/app.log")
+  #
+  # @example With size-based rotation (10MB files, keep 5 old files)
+  #   device = Lumberjack::Device::LogFile.new(
+  #     "/var/log/app.log",
+  #     shift_size: 10 * 1024 * 1024,  # 10MB
+  #     shift_age: 5                    # Keep 5 old files
+  #   )
+  #
+  # @example With daily rotation
+  #   device = Lumberjack::Device::LogFile.new(
+  #     "/var/log/app.log",
+  #     shift_age: "daily"
+  #   )
+  #
+  # @example With weekly rotation
+  #   device = Lumberjack::Device::LogFile.new(
+  #     "/var/log/app.log",
+  #     shift_age: "weekly"
+  #   )
+  #
+  # @see Device::Writer
+  # @see Logger::LogDevice
+  class Device::LogFile < Device::Writer
+    # Initialize a new LogFile device with automatic log rotation capabilities.
+    # This constructor wraps Ruby's Logger::LogDevice while filtering options to
+    # only pass supported parameters, ensuring compatibility across Ruby versions.
+    #
+    # @param stream [String, IO] The log destination. Can be a file path string
+    #   or an IO object. When a string path is provided, the file will be created
+    #   if it doesn't exist, and parent directories will be created as needed.
+    # @param options [Hash] Configuration options for the log device. All options
+    #   supported by Logger::LogDevice are accepted, including:
+    #   - +:shift_age+ - Number of old files to keep, or rotation frequency
+    #     ("daily", "weekly", "monthly")
+    #   - +:shift_size+ - Maximum file size in bytes before rotation
+    #   - +:shift_period_suffix+ - Suffix to add to rotated log files
+    #   - +:binmode+ - Whether to open the log file in binary mode
+    def initialize(stream, options = {})
+      # Filter options to only include keyword arguments supported by Logger::LogDevice#initialize
+      supported_kwargs = ::Logger::LogDevice.instance_method(:initialize).parameters
+        .select { |type, _| type == :key || type == :keyreq }
+        .map { |_, name| name }
 
-      # The absolute path of the file being logged to.
-      attr_reader :path
+      filtered_options = options.slice(*supported_kwargs)
 
-      # Create a logger to the file at +path+. Options are passed through to the Writer constructor.
-      #
-      # @param [String, Pathname] path The path to the log file.
-      # @param [Hash] options The options for the device.
-      def initialize(path, options = {})
-        @path = File.expand_path(path)
-        FileUtils.mkdir_p(File.dirname(@path))
-        super(file_stream, options)
-      end
+      logdev = ::Logger::LogDevice.new(stream, **filtered_options)
 
-      # Reopen the log file.
-      #
-      # @param [Object] logdev not used
-      # @return [void]
-      def reopen(logdev = nil)
-        close
-        @stream = file_stream
-      end
+      super(logdev, options)
+    end
 
-      private
+    # Get the file system path of the current log file. This method provides
+    # access to the actual file path being written to, which is useful for
+    # monitoring, log analysis tools, or other file-based operations.
+    #
+    # @return [String] The absolute file system path of the current log file
+    def path
+      stream.filename
+    end
+
+    # Expose the underlying stream.
+    #
+    # @return [IO]
+    # @api private
+    def dev
+      stream.dev
+    end
 
-      def file_stream
-        File.new(@path, "a", encoding: EXTERNAL_ENCODING)
-      end
+    def reopen(logdev = nil)
+      stream.reopen(logdev)
     end
   end
 end

data/lib/lumberjack/device/logger_wrapper.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # A logging device that forwards log entries to another logger instance.
+  # This device enables hierarchical logging architectures and broadcasting scenarios
+  # where log entries need to be distributed to multiple loggers or processed through
+  # different logging pipelines.
+  #
+  # The device is particularly useful when combined with Device::Multi to create
+  # master loggers that can simultaneously write to multiple destinations (files,
+  # databases, external services) while maintaining consistent formatting and
+  # attribute handling across all targets.
+  #
+  # Unlike other devices that write directly to output streams, this device delegates
+  # to another logger's processing pipeline, allowing for complex logging topologies
+  # and reuse of existing logger configurations.
+  #
+  # @example Basic logger forwarding
+  #   file_logger = Lumberjack::Logger.new("/var/log/app.log")
+  #   logger_device = Lumberjack::Device::LoggerWrapper.new(file_logger)
+  #
+  # @example Broadcasting with Multi device
+  #   main_logger = Lumberjack::Logger.new("/var/log/main.log")
+  #   error_logger = Lumberjack::Logger.new("/var/log/errors.log")
+  #
+  #   broadcast_device = Lumberjack::Device::Multi.new([
+  #     Lumberjack::Device::LoggerWrapper.new(main_logger),
+  #     Lumberjack::Device::LoggerWrapper.new(error_logger)
+  #   ])
+  #
+  #   master_logger = Lumberjack::Logger.new(broadcast_device)
+  #
+  # @example Hierarchical logging with filtering
+  #   # Main application logger
+  #   app_logger = Lumberjack::Logger.new("/var/log/app.log")
+  #
+  #   # Focused error logs
+  #   error_logger = Lumberjack::Logger.new("/var/log/error.log")
+  #   error_logger.level = Logger::WARN
+  #
+  #   # Route all logs to app, error logs to error logger
+  #   multi_device = Lumberjack::Device::Multi.new([
+  #     Lumberjack::Device::LoggerWrapper.new(app_logger),
+  #     Lumberjack::Device::LoggerWrapper.new(error_logger)
+  #   ])
+  #
+  # @see Device::Multi
+  # @see Lumberjack::Logger
+  # @see Lumberjack::ContextLogger
+  class Device::LoggerWrapper < Device
+    # @!attribute [r] logger
+    #   @return [Lumberjack::ContextLogger] The target logger that will receive forwarded log entries
+    attr_reader :logger
+
+    # Initialize a new Logger device that forwards entries to the specified logger.
+    # The target logger must be a Lumberjack logger that supports the ContextLogger
+    # interface to ensure proper entry handling and attribute processing.
+    #
+    # @param logger [Lumberjack::ContextLogger, ::Logger] The target logger to receive forwarded entries.
+    #   Must be a Lumberjack logger instance (Logger, ForkedLogger, etc.) that includes
+    #   the ContextLogger mixin for proper entry processing.
+    #
+    # @raise [ArgumentError] If the provided logger is not a Lumberjack::ContextLogger
+    def initialize(logger)
+      unless logger.is_a?(Lumberjack::ContextLogger) || logger.is_a?(::Logger)
+        raise ArgumentError.new("Logger must be a Lumberjack logger")
+      end
+
+      @logger = logger
+    end
+
+    # Forward a log entry to the target logger for processing. This method extracts
+    # the entry components and delegates to the target logger's add_entry method,
+    # ensuring that all attributes, formatting, and processing logic of the target
+    # logger are properly applied.
+    #
+    # The forwarded entry maintains all original metadata including severity,
+    # timestamp, program name, and custom attributes, allowing the target logger
+    # to process it as if it were generated directly.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to forward to the target logger
+    # @return [void]
+    def write(entry)
+      if @logger.is_a?(Lumberjack::ContextLogger)
+        @logger.add_entry(entry.severity, entry.message, entry.progname, entry.attributes)
+      else
+        message = entry.message
+        if entry.attributes && !entry.attributes.empty?
+          message_attributes = []
+          entry.attributes.each do |key, value|
+            next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+            value = value.join(",") if value.is_a?(Enumerable)
+            message_attributes << "[#{key}=#{value}]"
+          end
+          message = "#{message} #{message_attributes.join(" ")}" unless message_attributes.empty?
+        end
+        @logger.add(entry.severity, message, entry.progname)
+      end
+    end
+
+    # Closes the target logger to release any resources or finalize log output.
+    # This method delegates to the target logger's +close+ method.
+    #
+    # @return [void]
+    def close
+      @logger.close
+    end
+
+    # Reopen the underlying logger device. This is typically used to reopen log files
+    # after log rotation or to refresh the logger's output stream.
+    #
+    # Delegates to the target logger's +reopen+ method.
+    #
+    # @return [void]
+    def reopen
+      @logger.reopen
+    end
+
+    # Flushes the target logger, ensuring that any buffered log entries are written out.
+    # This delegates to the target logger's flush method, which may flush buffers to disk,
+    # external services, or other destinations depending on the logger's configuration.
+    #
+    # @return [void]
+    def flush
+      @logger.flush
+    end
+
+    # Expose the underlying stream if any.
+    #
+    # @return [IO, Lumberjack::Device, nil]
+    # @api private
+    def dev
+      @logger.device&.dev
+    end
+  end
+end

data/lib/lumberjack/device/multi.rb

@@ -1,46 +1,108 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  class Device
-    # This is a logging device that forward log entries to multiple other devices.
-    class Multi < Device
-      # @param [Array<Lumberjack::Device>] devices The devices to write to.
-      def initialize(*devices)
-        @devices = devices.flatten
-      end
+  # A multiplexing logging device that broadcasts log entries to multiple target
+  # devices simultaneously. This device enables sophisticated logging architectures
+  # where a single log entry needs to be processed by multiple output destinations,
+  # each potentially with different formatting, filtering, or storage mechanisms.
+  #
+  # The Multi device acts as a fan-out mechanism, ensuring that all configured
+  # devices receive every log entry while maintaining independent processing
+  # pipelines. This is particularly useful for creating redundant logging systems,
+  # separating log streams by concern, or implementing complex routing logic.
+  #
+  # All device lifecycle methods (flush, close, reopen) are propagated to all
+  # child devices, ensuring consistent state management across the entire
+  # logging topology.
+  #
+  # @example Basic multi-device setup
+  #   file_device = Lumberjack::Device::Writer.new("/var/log/app.log")
+  #   console_device = Lumberjack::Device::Writer.new(STDOUT, template: "{{message}}")
+  #   multi_device = Lumberjack::Device::Multi.new(file_device, console_device)
+  class Device::Multi < Device
+    attr_reader :devices
 
-      def write(entry)
-        @devices.each do |device|
-          device.write(entry)
-        end
-      end
+    # Initialize a new Multi device with the specified target devices. The device
+    # accepts multiple devices either as individual arguments or as arrays,
+    # automatically flattening nested arrays for convenient configuration.
+    #
+    # @param devices [Array<Lumberjack::Device>] The target devices to receive
+    #   log entries. Can be passed as individual arguments or arrays. All devices
+    #   must implement the standard Lumberjack::Device interface.
+    #
+    # @example Individual device arguments
+    #   multi = Multi.new(file_device, console_device, database_device)
+    def initialize(*devices)
+      @devices = devices.flatten
+    end
 
-      def flush
-        @devices.each do |device|
-          device.flush
-        end
+    # Broadcast a log entry to all configured devices. Each device receives the
+    # same LogEntry object and processes it according to its own configuration,
+    # formatting, and output logic. Devices are processed sequentially in the
+    # order they were configured.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to broadcast to all devices
+    # @return [void]
+    def write(entry)
+      devices.each do |device|
+        device.write(entry)
       end
+    end
 
-      def close
-        @devices.each do |device|
-          device.close
-        end
+    # Flush all configured devices to ensure buffered data is written to their
+    # respective destinations. This method calls flush on each device in sequence,
+    # ensuring consistent state across all output destinations.
+    #
+    # @return [void]
+    def flush
+      devices.each do |device|
+        device.flush
       end
+    end
 
-      def reopen(logdev = nil)
-        @devices.each do |device|
-          device.reopen(logdev = nil)
-        end
+    # Close all configured devices and release their resources. This method calls
+    # close on each device in sequence, ensuring proper cleanup of file handles,
+    # network connections, and other resources across all output destinations.
+    #
+    # @return [void]
+    def close
+      devices.each do |device|
+        device.close
       end
+    end
 
-      def datetime_format
-        @devices.detect(&:datetime_format).datetime_format
+    # Reopen all configured devices, optionally with a new log destination.
+    # This method calls reopen on each device in sequence, which is typically
+    # used for log rotation scenarios or when changing output destinations.
+    #
+    # @param logdev [Object, nil] Optional new log device or destination to pass
+    #   to each device's reopen method
+    # @return [void]
+    def reopen(logdev = nil)
+      devices.each do |device|
+        device.reopen(logdev = nil)
       end
+    end
+
+    # Get the datetime format from the first device that has one configured.
+    # This method searches through the configured devices and returns the
+    # datetime format from the first device that provides one.
+    #
+    # @return [String, nil] The datetime format string from the first device
+    #   that has one configured, or nil if no devices have a format set
+    def datetime_format
+      devices.detect(&:datetime_format).datetime_format
+    end
 
-      def datetime_format=(format)
-        @devices.each do |device|
-          device.datetime_format = format
-        end
+    # Set the datetime format on all configured devices that support it.
+    # This method propagates the format setting to each device, allowing
+    # coordinated timestamp formatting across all output destinations.
+    #
+    # @param format [String] The datetime format string to apply to all devices
+    # @return [void]
+    def datetime_format=(format)
+      devices.each do |device|
+        device.datetime_format = format
       end
     end
   end