lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/logger.rb

@@ -1,87 +1,149 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  # Logger is a thread safe logging object. It has a compatible API with the Ruby
-  # standard library Logger class, the Log4r gem, and ActiveSupport::BufferedLogger.
+  # Lumberjack::Logger is a thread-safe, feature-rich logging implementation that extends Ruby's standard
+  # library Logger class with advanced capabilities for structured logging.
   #
-  # === Example
+  # Key features include:
+  # - Structured logging with attributes (key-value pairs) attached to log entries
+  # - Context isolation for scoping logging behavior to specific code blocks
+  # - Flexible output devices supporting files, streams, and custom destinations
+  # - Customizable formatters for messages and attributes
   #
-  #   logger = Lumberjack::Logger.new
+  # The Logger maintains full API compatibility with Ruby's standard Logger while adding
+  # powerful extensions for modern logging needs.
+  #
+  # @example Basic usage
+  #   logger = Lumberjack::Logger.new(STDOUT)
   #   logger.info("Starting processing")
   #   logger.debug("Processing options #{options.inspect}")
   #   logger.fatal("OMG the application is on fire!")
   #
-  # Log entries are written to a logging Device if their severity meets or exceeds the log level.
+  # @example Structured logging with attributes
+  #   logger = Lumberjack::Logger.new("/var/log/app.log")
+  #   logger.tag(request_id: "abc123") do
+  #     logger.info("User logged in", user_id: 123, ip: "192.168.1.1")
+  #     logger.info("Processing request")  # Will include request_id: "abc123"
+  #   end
+  #
+  # @example Log rotation
+  #   # Keep 10 files, rotate when each reaches 10MB
+  #   logger = Lumberjack::Logger.new("/var/log/app.log", 10, 10 * 1024 * 1024)
+  #
+  # @example Using different devices
+  #   logger = Lumberjack::Logger.new("logs/application.log")  # Log to file
+  #   logger = Lumberjack::Logger.new(STDOUT, template: "{{severity}} - {{message}}")  # Log to a stream with a template
+  #   logger = Lumberjack::Logger.new(:test)  # Log to an in memory buffer for testing
+  #   logger = Lumberjack::Logger.new(another_logger) # Proxy logs to another logger
+  #   logger = Lumberjack::Logger.new(MyDevice.new)  # Log to a custom Lumberjack::Device
   #
-  # Devices may use buffers internally and the log entries are not guaranteed to be written until you call
-  # the +flush+ method. Sometimes this can result in problems when trying to track down extraordinarily
-  # long running sections of code since it is likely that none of the messages logged before the long
-  # running code will appear in the log until the entire process finishes. You can set the +:flush_seconds+
-  # option on the constructor to force the device to be flushed periodically. This will create a new
-  # monitoring thread, but its use is highly recommended.
+  # @example Logging to multiple devices with an array
+  #   logger = Lumberjack::Logger.new(["/var/log/app.log", [:stdout, {template: "{{message}}"}]])
   #
+  # Log entries are written to a logging Device if their severity meets or exceeds the log level.
   # Each log entry records the log message and severity along with the time it was logged, the
-  # program name, process id, and an optional hash of tags. The message will be converted to a string, but
-  # otherwise, it is up to the device how these values are recorded. Messages are converted to strings
+  # program name, process id, and an optional hash of attributes. Messages are converted to strings
   # using a Formatter associated with the logger.
-  class Logger
-    include Severity
+  #
+  # @see Lumberjack::ContextLogger
+  # @see Lumberjack::Device
+  # @see Lumberjack::Template
+  # @see Lumberjack::EntryFormatter
+  class Logger < ::Logger
+    include ContextLogger
 
-    # The time that the device was last flushed.
-    attr_reader :last_flushed_at
+    # Create a new logger to log to a Device.
+    #
+    # The +device+ argument can be in any one of several formats:
+    # - A symbol for a device name (e.g. :null, :test). You can call +Lumberjack::DeviceRegistry.registered_devices+ for a list.
+    # - A stream
+    # - A file path string or +Pathname+
+    # - A +Lumberjack::Device+ object
+    # - An object with a +write+ method will be wrapped in a Device::Writer
+    # - An array of any of the above will open a Multi device that will send output to all devices.
+    #
+    # @param logdev [Lumberjack::Device, IO, Symbol, String, Pathname] The device to log to.
+    #   If this is a symbol, the device will be looked up from the DeviceRegistry. If it is
+    #   a string or a Pathname, the logs will be sent to the corresponding file path.
+    # @param shift_age [Integer, String, Symbol] If this is an integer greater than zero, then
+    #   log files will be rolled when they get to the size specified in shift_size and the number of
+    #   files to keep will be determined by this value. Otherwise it will be interpreted as a date
+    #   rolling value and must be one of "daily", "weekly", or "monthly". This parameter has no
+    #   effect unless the device parameter is a file path or file stream. This can also be
+    #   specified with the :roll keyword argument.
+    # @param shift_size [Integer] The size in bytes of the log files before rolling them. This can
+    #   be passed as a string with a unit suffix of K, M, or G (e.g. "10M" for 10 megabytes).
+    #   This can also be specified with the :max_size keyword argument.
+    # @param level [Integer, Symbol, String] The logging level below which messages will be ignored.
+    # @param progname [String] The name of the program that will be recorded with each log entry.
+    # @param formatter [Lumberjack::EntryFormatter, Lumberjack::Formatter, ::Logger::Formatter, :default, #call]
+    #   The formatter to use for outputting messages to the log. If this is a Lumberjack::EntryFormatter
+    #   or a Lumberjack::Formatter, it will be used to format structured log entries.
+    #   You can also pass the value +:default+ to use the default message formatter which formats
+    #   non-primitive objects with +inspect+ and includes the backtrace in exceptions.
+    #
+    #   For compatibility with the standard library Logger when writing to a stream, you can also
+    #   pass in a +::Logger::Formatter+ object or a callable object that takes exactly 4 arguments
+    #   (severity, time, progname, msg).
+    # @param datetime_format [String] The format to use for log timestamps.
+    # @param binmode [Boolean] Whether to open the log file in binary mode.
+    # @param shift_period_suffix [String] The suffix to use for the shifted log file names.
+    # @param kwargs [Hash] Additional device-specific options. These will be passed through when creating
+    #   a device from the logdev argument.
+    # @return [Lumberjack::Logger] A new logger instance.
+    def initialize(logdev, shift_age = 0, shift_size = 1048576,
+      level: DEBUG, progname: nil, formatter: nil, datetime_format: nil,
+      binmode: false, shift_period_suffix: "%Y%m%d", **kwargs)
+      init_fiber_locals!
+
+      if shift_age.is_a?(Hash)
+        Lumberjack::Utils.deprecated("Logger.new(options)", "Passing a Hash as the second argument to Logger.new is deprecated and will be removed in version 2.1; use keyword arguments instead.")
+        options = shift_age
+        level = options[:level] if options.include?(:level)
+        progname = options[:progname] if options.include?(:progname)
+        formatter = options[:formatter] if options.include?(:formatter)
+        datetime_format = options[:datetime_format] if options.include?(:datetime_format)
+        kwargs = options.merge(kwargs)
+      end
 
-    # Set +silencer+ to false to disable silencing the log.
-    attr_accessor :silencer
+      # Include standard args that affect devices with the optional kwargs which may
+      # contain device specific options.
+      device_options = kwargs.merge(shift_age: shift_age, shift_size: size_with_units(shift_size), binmode: binmode, shift_period_suffix: shift_period_suffix)
+      device_options[:standard_logger_formatter] = formatter if standard_logger_formatter?(formatter)
 
-    # Set the name of the program to attach to log entries.
-    attr_writer :progname
+      if device_options.include?(:roll)
+        Utils.deprecated("Logger.options(:roll)", "Lumberjack::Logger :roll option is deprecated and will be removed in version 2.1; use the shift_age argument instead.")
+        device_options[:shift_age] = device_options.delete(:roll) unless shift_age != 0
+      end
 
-    # The Formatter used only for log entry messages.
-    attr_accessor :message_formatter
+      if device_options.include?(:max_size)
+        Utils.deprecated("Logger.options(:max_size)", "Lumberjack::Logger :max_size option is deprecated and will be removed in version 2.1; use the shift_size argument instead.")
+        device_options[:shift_age] = 10 if shift_age == 0
+        device_options[:shift_size] = device_options.delete(:max_size)
+      end
 
-    # The TagFormatter used for formatting tags for output
-    attr_accessor :tag_formatter
+      message_formatter = nil
+      if device_options.include?(:message_formatter)
+        Utils.deprecated("Logger.options(:message_formatter)", "Lumberjack::Logger :message_formatter option is deprecated and will be removed in version 2.1; use the formatter argument instead to specify an EntryFormatter.")
+        message_formatter = device_options.delete(:message_formatter)
+      end
 
-    # Create a new logger to log to a Device.
-    #
-    # The +device+ argument can be in any one of several formats.
-    #
-    # If it is a Device object, that object will be used.
-    # If it has a +write+ method, it will be wrapped in a Device::Writer class.
-    # If it is :null, it will be a Null device that won't record any output.
-    # Otherwise, it will be assumed to be file path and wrapped in a Device::LogFile class.
-    #
-    # All other options are passed to the device constuctor.
-    #
-    # @param [Lumberjack::Device, Object, Symbol, String] device The device to log to.
-    # @param [Hash] options The options for the logger.
-    # @option options [Integer, Symbol, String] :level The logging level below which messages will be ignored.
-    # @option options [Lumberjack::Formatter] :formatter The formatter to use for outputting messages to the log.
-    # @option options [String] :datetime_format The format to use for log timestamps.
-    # @option options [Lumberjack::Formatter] :message_formatter The MessageFormatter to use for formatting log messages.
-    # @option options [Lumberjack::TagFormatter] :tag_formatter The TagFormatter to use for formatting tags.
-    # @option options [String] :progname The name of the program that will be recorded with each log entry.
-    # @option options [Numeric] :flush_seconds The maximum number of seconds between flush calls.
-    # @option options [Boolean] :roll If the log device is a file path, it will be a Device::DateRollingLogFile if this is set.
-    # @option options [Integer] :max_size If the log device is a file path, it will be a Device::SizeRollingLogFile if this is set.
-    def initialize(device = $stdout, options = {})
-      options = options.dup
-      self.level = options.delete(:level) || INFO
-      self.progname = options.delete(:progname)
-      max_flush_seconds = options.delete(:flush_seconds).to_f
-
-      @logdev = open_device(device, options) if device
-      self.formatter = (options[:formatter] || Formatter.new)
-      @message_formatter = options[:message_formatter] || Formatter.empty
-      @tag_formatter = options[:tag_formatter] || TagFormatter.new
-      time_format = options[:datetime_format] || options[:time_format]
-      self.datetime_format = time_format if time_format
-      @last_flushed_at = Time.now
-      @silencer = true
-      @tags = {}
-      @closed = false
+      attribute_formatter = nil
+      if device_options.include?(:tag_formatter)
+        Utils.deprecated("Logger.options(:tag_formatter)", "Lumberjack::Logger :tag_formatter option is deprecated and will be removed in version 2.1; use the formatter argument instead to specify an EntryFormatter.")
+        attribute_formatter = device_options.delete(:tag_formatter)
+      end
 
-      create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0
+      @logdev = Device.open_device(logdev, device_options)
+
+      @context = Context.new
+      self.level = level || DEBUG
+      self.progname = progname
+
+      self.formatter = build_entry_formatter(formatter, message_formatter, attribute_formatter)
+      self.datetime_format = datetime_format if datetime_format
+
+      @closed = false
     end
 
     # Get the logging device that is used to write log entries.
@@ -93,10 +155,19 @@ module Lumberjack
 
     # Set the logging device to a new device.
     #
-    # @param [Lumberjack::Device] device The new logging device.
+    # @param device [Lumberjack::Device] The new logging device.
     # @return [void]
     def device=(device)
-      @logdev = device.nil? ? nil : open_device(device, {})
+      @logdev = Device.open_device(device, {})
+    end
+
+    # Set the formatter used for log entries. This can be an EntryFormatter, a standard Logger::Formatter,
+    # or any callable object that formats log entries.
+    #
+    # @param value [Lumberjack::EntryFormatter, ::Logger::Formatter, #call] The formatter to use.
+    # @return [void]
+    def formatter=(value)
+      @formatter = build_entry_formatter(value, nil, nil)
     end
 
     # Get the timestamp format on the device if it has one.
@@ -108,7 +179,7 @@ module Lumberjack
 
     # Set the timestamp format on the device if it is supported.
     #
-    # @param [String] format The timestamp format.
+    # @param format [String] The timestamp format.
     # @return [void]
     def datetime_format=(format)
       if device.respond_to?(:datetime_format=)
@@ -116,156 +187,55 @@ module Lumberjack
       end
     end
 
-    # Get the level of severity of entries that are logged. Entries with a lower
-    # severity level will be ignored.
+    # Get the message formatter used to format log messages.
     #
-    # @return [Integer] The severity level.
-    def level
-      thread_local_value(:lumberjack_logger_level) || @level
+    # @return [Lumberjack::Formatter] The message formatter.
+    def message_formatter
+      formatter.message_formatter
     end
 
-    alias_method :sev_threshold, :level
-
-    # Set the log level using either an integer level like Logger::INFO or a label like
-    # :info or "info"
+    # Set the message formatter used to format log messages.
     #
-    # @param [Integer, Symbol, String] value The severity level.
+    # @param value [Lumberjack::Formatter] The message formatter to use.
     # @return [void]
-    def level=(value)
-      @level = Severity.coerce(value)
+    def message_formatter=(value)
+      formatter.message_formatter = value
     end
 
-    alias_method :sev_threshold=, :level=
-
-    # Adjust the log level during the block execution for the current Fiber only.
+    # Get the attribute formatter used to format log entry attributes.
     #
-    # @param [Integer, Symbol, String] severity The severity level.
-    # @return [Object] The result of the block.
-    def with_level(severity, &block)
-      push_thread_local_value(:lumberjack_logger_level, Severity.coerce(severity), &block)
+    # @return [Lumberjack::AttributeFormatter] The attribute formatter.
+    def attribute_formatter
+      formatter.attribute_formatter
     end
 
-    # Set the Lumberjack::Formatter used to format objects for logging as messages.
+    # Set the attribute formatter used to format log entry attributes.
     #
-    # @param [Lumberjack::Formatter, Object] value The formatter to use.
+    # @param value [Lumberjack::AttributeFormatter] The attribute formatter to use.
     # @return [void]
-    def formatter=(value)
-      @_formatter = (value.is_a?(TaggedLoggerSupport::Formatter) ? value.__formatter : value)
-    end
-
-    # Get the Lumberjack::Formatter used to format objects for logging as messages.
-    #
-    # @return [Lumberjack::Formatter] The formatter.
-    def formatter
-      if respond_to?(:tagged)
-        # Wrap in an object that supports ActiveSupport::TaggedLogger API
-        TaggedLoggerSupport::Formatter.new(logger: self, formatter: @_formatter)
-      else
-        @_formatter
-      end
-    end
-
-    # Enable this logger to function like an ActiveSupport::TaggedLogger. This will make the logger
-    # API compatible with ActiveSupport::TaggedLogger and is provided as a means of compatibility
-    # with other libraries that assume they can call the `tagged` method on a logger to add tags.
-    #
-    # The tags added with this method are just strings so they are stored in the logger tags
-    # in an array under the "tagged" tag. So calling `logger.tagged("foo", "bar")` will result
-    # in tags `{"tagged" => ["foo", "bar"]}`.
-    #
-    # @return [Lumberjack::Logger] self.
-    def tagged_logger!
-      extend(TaggedLoggerSupport)
-      self
+    def attribute_formatter=(value)
+      formatter.attribute_formatter = value
     end
 
-    # Add a message to the log with a given severity. The message can be either
-    # passed in the +message+ argument or supplied with a block. This method
-    # is not normally called. Instead call one of the helper functions
-    # +fatal+, +error+, +warn+, +info+, or +debug+.
-    #
-    # The severity can be passed in either as one of the Severity constants,
-    # or as a Severity label.
-    #
-    # @param [Integer, Symbol, String] severity The severity of the message.
-    # @param [Object] message The message to log.
-    # @param [String] progname The name of the program that is logging the message.
-    # @param [Hash] tags The tags to add to the log entry.
-    # @return [void]
-    #
-    # @example
-    #
-    #   logger.add_entry(Logger::ERROR, exception)
-    #   logger.add_entry(Logger::INFO, "Request completed")
-    #   logger.add_entry(:warn, "Request took a long time")
-    #   logger.add_entry(Logger::DEBUG){"Start processing with options #{options.inspect}"}
-    def add_entry(severity, message, progname = nil, tags = nil)
-      severity = Severity.label_to_level(severity) unless severity.is_a?(Integer)
-      return true unless device && severity && severity >= level
-      return true if Thread.current[:lumberjack_logging]
-
-      begin
-        Thread.current[:lumberjack_logging] = true # Prevent circular calls to add_entry
-
-        time = Time.now
-
-        message = message.call if message.is_a?(Proc)
-        msg_class_formatter = message_formatter&.formatter_for(message.class)
-        if msg_class_formatter
-          message = msg_class_formatter.call(message)
-        elsif formatter
-          message = formatter.format(message)
-        end
-        message_tags = nil
-        if message.is_a?(Formatter::TaggedMessage)
-          message_tags = message.tags
-          message = message.message
-        end
-
-        progname ||= self.progname
-        message_tags = Utils.flatten_tags(message_tags) if message_tags
-
-        current_tags = self.tags
-        tags = nil unless tags.is_a?(Hash)
-        tags = merge_tags(current_tags, tags)
-        tags = merge_tags(tags, message_tags) if message_tags
-        tags = Tags.expand_runtime_values(tags)
-        tags = tag_formatter.format(tags) if tag_formatter
-
-        entry = LogEntry.new(time, severity, message, progname, Process.pid, tags)
-        write_to_device(entry)
-      ensure
-        Thread.current[:lumberjack_logging] = nil
+    # @deprecated Use {#attribute_formatter} instead.
+    def tag_formatter
+      Utils.deprecated("Logger#tag_formatter", "Lumberjack::Logger#tag_formatter is deprecated and will be removed in version 2.1; use attribute_formatter instead.") do
+        formatter.attributes.attribute_formatter
       end
-      true
     end
 
-    # ::Logger compatible method to add a log entry.
-    #
-    # @param [Integer, Symbol, String] severity The severity of the message.
-    # @param [Object] message The message to log.
-    # @param [String] progname The name of the program that is logging the message.
-    # @return [void]
-    def add(severity, message = nil, progname = nil, &block)
-      if message.nil?
-        if block
-          message = block
-        else
-          message = progname
-          progname = nil
-        end
+    # @deprecated Use {#attribute_formatter=} instead.
+    def tag_formatter=(value)
+      Utils.deprecated("Logger#tag_formatter=", "Lumberjack::Logger#tag_formatter= is deprecated and will be removed in version 2.1; use attribute_formatter= instead.") do
+        formatter.attributes.attribute_formatter = value
       end
-      add_entry(severity, message, progname)
     end
 
-    alias_method :log, :add
-
     # Flush the logging device. Messages are not guaranteed to be written until this method is called.
     #
     # @return [void]
     def flush
       device.flush
-      @last_flushed_at = Time.now
       nil
     end
 
@@ -282,454 +252,256 @@ module Lumberjack
     #
     # @return [Boolean] +true+ if the logging device is closed.
     def closed?
-      @closed
+      return true if @closed
+
+      device.respond_to?(:closed?) && device.closed?
     end
 
     # Reopen the logging device.
     #
-    # @param [Object] logdev passed through to the logging device.
+    # @param logdev [Object] passed through to the logging device.
+    # @return [Lumberjack::Logger] self
     def reopen(logdev = nil)
       @closed = false
       device.reopen(logdev) if device.respond_to?(:reopen)
+      self
     end
 
-    # Log a +FATAL+ message. The message can be passed in either the +message+ argument or in a block.
+    # Set the program name that is associated with log messages. If a block
+    # is given, the program name will be valid only within the block.
     #
-    # @param [Object] message_or_progname_or_tags The message to log or progname
-    #   if the message is passed in a block.
-    # @param [String, Hash] progname_or_tags The name of the program that is logging the message or tags
-    #   if the message is passed in a block.
+    # @param value [String] The program name to use.
     # @return [void]
-    def fatal(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
-      call_add_entry(FATAL, message_or_progname_or_tags, progname_or_tags, &block)
+    # @deprecated Use with_progname or progname= instead.
+    def set_progname(value, &block)
+      Utils.deprecated("Logger#set_progname", "Lumberjack::Logger#set_progname is deprecated and will be removed in version 2.1; use with_progname or progname= instead.") do
+        if block
+          with_progname(value, &block)
+        else
+          self.progname = value
+        end
+      end
     end
 
-    # Return +true+ if +FATAL+ messages are being logged.
+    # Alias method for #attributes to provide backward compatibility with version 1.x API. This
+    # method will eventually be removed.
     #
-    # @return [Boolean]
-    def fatal?
-      level <= FATAL
+    # @return [Hash]
+    # @deprecated Use {#attributes} instead
+    def tags
+      Utils.deprecated("Logger#tags", "Lumberjack::Logger#tags is deprecated and will be removed in version 2.1; use attributes instead.") do
+        attributes
+      end
     end
 
-    # Set the log level to fatal.
+    # Alias method for #attribute_value to provide backward compatibility with version 1.x API. This
+    # method will eventually be removed.
     #
-    # @return [void]
-    def fatal!
-      self.level = FATAL
+    # @return [Hash]
+    # @deprecated Use {#attribute_value} instead
+    def tag_value(name)
+      Utils.deprecated("Logger#tag_value", "Lumberjack::Logger#tag_value is deprecated and will be removed in version 2.1; use attribute_value instead.") do
+        attribute_value(name)
+      end
     end
 
-    # Log an +ERROR+ message. The message can be passed in either the +message+ argument or in a block.
+    # Use tag! instead
     #
-    # @param [Object] message_or_progname_or_tags The message to log or progname
-    #   if the message is passed in a block.
-    # @param [String, Hash] progname_or_tags The name of the program that is logging the message or tags
-    #   if the message is passed in a block.
     # @return [void]
-    def error(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
-      call_add_entry(ERROR, message_or_progname_or_tags, progname_or_tags, &block)
+    # @deprecated Use {#tag!} instead.
+    def tag_globally(tags)
+      Utils.deprecated("Logger#tag_globally", "Lumberjack::Logger#tag_globally is deprecated and will be removed in version 2.1; use tag! instead.") do
+        tag!(tags)
+      end
     end
 
-    # Return +true+ if +ERROR+ messages are being logged.
+    # Use context? instead
     #
     # @return [Boolean]
-    def error?
-      level <= ERROR
-    end
-
-    # Set the log level to error.
-    #
-    # @return [void]
-    def error!
-      self.level = ERROR
+    # @deprecated Use {#in_context?} instead.
+    def in_tag_context?
+      Utils.deprecated("Logger#in_tag_context?", "Lumberjack::Logger#in_tag_context? is deprecated and will be removed in version 2.1; use in_context? instead.") do
+        context?
+      end
     end
 
-    # Log a +WARN+ message. The message can be passed in either the +message+ argument or in a block.
+    # Remove a tag from the current context block. If this is called inside a context block,
+    # the attributes will only be removed for the duration of that block. Otherwise they will be removed
+    # from the global attributes.
     #
-    # @param [Object] message_or_progname_or_tags The message to log or progname
-    #   if the message is passed in a block.
-    # @param [String, Hash] progname_or_tags The name of the program that is logging the message or tags
-    #   if the message is passed in a block.
+    # @param tag_names [Array<String, Symbol>] The attributes to remove.
     # @return [void]
-    def warn(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
-      call_add_entry(WARN, message_or_progname_or_tags, progname_or_tags, &block)
-    end
-
-    # Return +true+ if +WARN+ messages are being logged.
-    #
-    # @return [Boolean]
-    def warn?
-      level <= WARN
+    # @deprecated Use untag or untag! instead.
+    def remove_tag(*tag_names)
+      Utils.deprecated("Logger#remove_tag", "Lumberjack::Logger#remove_tag is deprecated and will be removed in version 2.1; use untag or untag! instead.") do
+        attributes = current_context&.attributes
+        AttributesHelper.new(attributes).delete(*tag_names) if attributes
+      end
     end
 
-    # Set the log level to warn.
+    # Alias for append_to(:tagged) for compatibility with ActiveSupport support in Lumberjack 1.x.
+    # This functionality has been moved to the lumberjack_rails gem. Note that in that gem the
+    # tags are added to the :tags attribute instead of the :tagged attribute.
     #
-    # @return [void]
-    def warn!
-      self.level = WARN
+    # @see append_to
+    # @deprecated This implementation is deprecated. Install the lumberjack_rails gem for full support.
+    def tagged(*tags, &block)
+      deprecation_message = "Install the lumberjack_rails gem for full support of the tagged method."
+      Utils.deprecated("Logger#tagged", deprecation_message) do
+        append_to(:tagged, *tags, &block)
+      end
     end
 
-    # Log an +INFO+ message. The message can be passed in either the +message+ argument or in a block.
+    # Alias for clear_attributes.
     #
-    # @param [Object] message_or_progname_or_tags The message to log or progname
-    #   if the message is passed in a block.
-    # @param [String] progname_or_tags The name of the program that is logging the message or tags
-    #   if the message is passed in a block.
-    # @return [void]
-    def info(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
-      call_add_entry(INFO, message_or_progname_or_tags, progname_or_tags, &block)
+    # @see clear_attributes
+    # @deprecated Use clear_attributes instead.
+    def untagged(&block)
+      Utils.deprecated("Logger#untagged", "Lumberjack::Logger#untagged is deprecated and will be removed in version 2.1; use clear_attributes instead.") do
+        clear_attributes(&block)
+      end
     end
 
-    # Return +true+ if +INFO+ messages are being logged.
+    # Alias for with_level for compatibility with ActiveSupport loggers. This functionality
+    # has been moved to the lumberjack_rails gem.
     #
-    # @return [Boolean]
-    def info?
-      level <= INFO
+    # @see with_level
+    # @deprecated This implementation is deprecated. Install the lumberjack_rails gem for full support.
+    def log_at(level, &block)
+      deprecation_message = "Install the lumberjack_rails gem for full support of the log_at method."
+      Utils.deprecated("Logger#log_at", deprecation_message) do
+        with_level(level, &block)
+      end
     end
 
-    # Set the log level to info.
+    # Alias for with_level for compatibilty with ActiveSupport loggers. This functionality
+    # has been moved to the lumberjack_rails gem.
     #
-    # @return [void]
-    def info!
-      self.level = INFO
+    # @see with_level
+    # @deprecated This implementation is deprecated. Install the lumberjack_rails gem for full support.
+    def silence(level = Logger::ERROR, &block)
+      deprecation_message = "Install the lumberjack_rails gem for full support of the silence method."
+      Utils.deprecated("Logger#silence", deprecation_message) do
+        with_level(level, &block)
+      end
     end
 
-    # Log a +DEBUG+ message. The message can be passed in either the +message+ argument or in a block.
+    # Add an entry to the log.
     #
-    # @param [Object] message_or_progname_or_tags The message to log or progname
-    #   if the message is passed in a block.
-    # @param [String, Hash] progname_or_tags The name of the program that is logging the message or tags
-    #   if the message is passed in a block.
+    # @param severity [Integer, Symbol, String] The severity of the message.
+    # @param message [Object] The message to log.
+    # @param progname [String] The name of the program that is logging the message.
+    # @param attributes [Hash] The attributes to add to the log entry.
     # @return [void]
-    def debug(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
-      call_add_entry(DEBUG, message_or_progname_or_tags, progname_or_tags, &block)
-    end
+    # @api private
+    def add_entry(severity, message, progname = nil, attributes = nil)
+      return false unless device
+      return false if fiber_local&.logging
 
-    # Return +true+ if +DEBUG+ messages are being logged.
-    #
-    # @return [Boolean]
-    def debug?
-      level <= DEBUG
-    end
+      severity = Severity.label_to_level(severity) unless severity.is_a?(Integer)
 
-    # Set the log level to debug.
-    #
-    # @return [void]
-    def debug!
-      self.level = DEBUG
-    end
+      fiber_locals do |locals|
+        locals.logging = true # protection from infinite loops
 
-    # Log a message when the severity is not known. Unknown messages will always appear in the log.
-    # The message can be passed in either the +message+ argument or in a block.
-    #
-    # @param [Object] message_or_progname_or_tags The message to log or progname
-    #   if the message is passed in a block.
-    # @param [String, Hash] progname_or_tags The name of the program that is logging the message or tags
-    #   if the message is passed in a block.
-    # @return [void]
-    def unknown(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
-      call_add_entry(UNKNOWN, message_or_progname_or_tags, progname_or_tags, &block)
-    end
+        time = Time.now
+        progname ||= self.progname
+        attributes = nil unless attributes.is_a?(Hash)
+        attributes = merge_attributes(merge_all_attributes, attributes)
+        message, attributes = formatter.format(message, attributes) if formatter
 
-    # Add a message when the severity is not known.
-    #
-    # @param [Object] msg The message to log.
-    # @return [void]
-    def <<(msg)
-      add_entry(UNKNOWN, msg)
-    end
+        entry = Lumberjack::LogEntry.new(time, severity, message, progname, Process.pid, attributes)
 
-    # Silence the logger by setting a new log level inside a block. By default, only +ERROR+ or +FATAL+
-    # messages will be logged.
-    #
-    # @param [Integer, String, Symbol] temporary_level The log level to use inside the block.
-    # @return [Object] The result of the block.
-    #
-    # @example
-    #
-    #   logger.level = Logger::INFO
-    #   logger.silence do
-    #     do_something   # Log level inside the block is +ERROR+
-    #   end
-    def silence(temporary_level = ERROR, &block)
-      if silencer
-        unless temporary_level.is_a?(Integer)
-          temporary_level = Severity.label_to_level(temporary_level)
-        end
-        push_thread_local_value(:lumberjack_logger_level, temporary_level, &block)
-      else
-        yield
+        write_to_device(entry)
       end
-    end
 
-    # Provided for compatibility with ActiveSupport::LoggerThreadSafeLevel to temporarily set the log level.
-    #
-    # @param [Integer, String, Symbol] level The log level to use inside the block.
-    # @return [Object] The result of the block.
-    def log_at(level, &block)
-      with_level(level, &block)
+      true
     end
 
-    # Set the program name that is associated with log messages. If a block
-    # is given, the program name will be valid only within the block.
+    # Return a human-readable representation of the logger showing its key configuration.
     #
-    # @param [String] value The program name to use.
-    # @return [void]
-    def set_progname(value, &block)
-      if block
-        push_thread_local_value(:lumberjack_logger_progname, value, &block)
-      else
-        self.progname = value
-      end
+    # @return [String] A string representation of the logger.
+    def inspect
+      formatted_object_id = object_id.to_s(16).rjust(16, "0")
+      "#<Lumberjack::Logger:0x#{formatted_object_id} level:#{Severity.level_to_label(level)} device:#{device.class.name} progname:#{progname.inspect} attributes:#{attributes.inspect}>"
     end
 
-    # Set the logger progname for the duration of the block.
-    #
-    # @yield [Object] The block to execute with the program name set.
-    # @param [String] value The program name to use.
-    # @return [Object] The result of the block.
-    def with_progname(value, &block)
-      set_progname(value, &block)
-    end
+    private
 
-    # Get the program name associated with log messages.
-    #
-    # @return [String]
-    def progname
-      thread_local_value(:lumberjack_logger_progname) || @progname
+    def default_context
+      @context
     end
 
-    # Set a hash of tags on logger. If a block is given, the tags will only be set
-    # for the duration of the block. Otherwise the tags will be applied on the current
-    # logger context for the duration of that context.
-    #
-    # If there is no block or context, the tags will be applied to the global context.
-    # This behavior is deprecated. Use the `tag_globally` method to set global tags instead.
-    #
-    # @param [Hash] tags The tags to set.
-    # @return [void]
-    def tag(tags, &block)
-      thread_tags = thread_local_value(:lumberjack_logger_tags)
-      if block
-        merged_tags = (thread_tags ? thread_tags.dup : {})
-        TagContext.new(merged_tags).tag(tags)
-        push_thread_local_value(:lumberjack_logger_tags, merged_tags, &block)
-      elsif thread_tags
-        TagContext.new(thread_tags).tag(tags)
-        nil
-      else
-        Utils.deprecated("Lumberjack::Logger#tag", "Lumberjack::Logger#tag must be called with a block or inside a context block. In version 2.0 it will no longer be used for setting global tags. Use Lumberjack::Logger#tag_globally instead.") do
-          tag_globally(tags)
-        end
-      end
+    def write_to_device(entry) # :nodoc:
+      device.write(entry)
+    rescue => e
+      err = e.class.name.dup
+      err << ": #{e.message}" unless e.message.to_s.empty?
+      err << " at #{e.backtrace.first}" if e.backtrace
+      $stderr.write("#{err}#{Lumberjack::LINE_SEPARATOR}#{entry}#{Lumberjack::LINE_SEPARATOR}") # rubocop:disable Style/StderrPuts
+
+      raise e if Lumberjack.raise_logger_errors?
     end
 
-    # Set up a context block for the logger. All tags added within the block will be cleared when
-    # the block exits.
-    #
-    # @param [Proc] block The block to execute with the tag context.
-    # @return [TagContext] If no block is passed, then a Lumberjack::TagContext is returned that can be used
-    #   to interact with the tags (add, remove, etc.).
-    # @yield [TagContext] If a block is passed, it will be yielded a TagContext object that can be used to
-    #   add or remove tags within the context.
-    def context(&block)
-      if block
-        thread_tags = thread_local_value(:lumberjack_logger_tags)&.dup
-        thread_tags ||= {}
-        push_thread_local_value(:lumberjack_logger_tags, thread_tags) do
-          block.call(TagContext.new(thread_tags))
-        end
-      else
-        TagContext.new(thread_local_value(:lumberjack_logger_tags) || {})
+    def build_entry_formatter(formatter, message_formatter, attribute_formatter) # :nodoc:
+      entry_formatter = formatter if formatter.is_a?(Lumberjack::EntryFormatter)
+
+      unless entry_formatter
+        message_formatter ||= formatter if formatter.is_a?(Lumberjack::Formatter) || formatter == :default
+        entry_formatter = Lumberjack::EntryFormatter.new
       end
-    end
 
-    # Add global tags to the logger that will appear on all log entries.
-    #
-    # @param [Hash] tags The tags to set.
-    # @return [void]
-    def tag_globally(tags)
-      TagContext.new(@tags).tag(tags)
-      nil
-    end
+      message_formatter = Lumberjack::Formatter.default if message_formatter == :default
 
-    # Remove a tag from the current tag context. If this is called inside a tag context,
-    # the tags will only be removed for the duration of that block. Otherwise they will be removed
-    # from the global tags.
-    #
-    # @param [Array<String, Symbol>] tag_names The tags to remove.
-    # @return [void]
-    def remove_tag(*tag_names)
-      tags = thread_local_value(:lumberjack_logger_tags) || @tags
-      TagContext.new(tags).delete(*tag_names)
-    end
+      entry_formatter.message_formatter = message_formatter if message_formatter
+      entry_formatter.attribute_formatter = attribute_formatter if attribute_formatter
 
-    # Return all tags in scope on the logger including global tags set on the Lumberjack
-    # context, tags set on the logger, and tags set on the current block for the logger.
-    #
-    # @return [Hash]
-    def tags
-      tags = {}
-      context_tags = Lumberjack.context_tags
-      tags.merge!(context_tags) if context_tags && !context_tags.empty?
-      tags.merge!(@tags) if !@tags.empty? && !thread_local_value(:lumberjack_logger_untagged)
-      scope_tags = thread_local_value(:lumberjack_logger_tags)
-      tags.merge!(scope_tags) if scope_tags && !scope_tags.empty?
-      tags
+      entry_formatter
     end
 
-    # Get the value of a tag by name from the current tag context.
-    #
-    # @param [String, Symbol] name The name of the tag to get.
-    # @return [Object, nil] The value of the tag or nil if the tag does not exist.
-    def tag_value(name)
-      name = name.join(".") if name.is_a?(Array)
-      TagContext.new(tags)[name]
-    end
+    def standard_logger_formatter?(formatter)
+      return false if formatter.is_a?(Lumberjack::EntryFormatter)
+      return false if formatter.is_a?(Lumberjack::Formatter)
+      return true if formatter.is_a?(::Logger::Formatter)
 
-    # Remove all tags on the current logger and logging context within a block.
-    # You can still set new block scoped tags within theuntagged block and provide
-    # tags on individual log methods.
-    #
-    # @return [void]
-    def untagged(&block)
-      Lumberjack.use_context(nil) do
-        scope_tags = thread_local_value(:lumberjack_logger_tags)
-        untagged = thread_local_value(:lumberjack_logger_untagged)
-        begin
-          set_thread_local_value(:lumberjack_logger_untagged, true)
-          set_thread_local_value(:lumberjack_logger_tags, nil)
-          tag({}, &block)
-        ensure
-          set_thread_local_value(:lumberjack_logger_untagged, untagged)
-          set_thread_local_value(:lumberjack_logger_tags, scope_tags)
-        end
-      end
+      takes_exactly_n_call_args?(formatter, 4)
     end
 
-    # Return true if the thread is currently in a Lumberjack::Context block.
-    # When the logger is in a context block, tagging will only apply to that block.
+    # Convert a size string with optional unit suffix to an integer size in bytes.
+    # Allowed suffixes are K, M, and G (case insensitive) for kilobytes, megabytes, and gigabytes.
     #
-    # @return [Boolean]
-    def in_tag_context?
-      !!thread_local_value(:lumberjack_logger_tags)
-    end
-
-    private
+    # @param size [String, Integer] The size string to convert.
+    # @return [Integer] The size in bytes.
+    def size_with_units(size)
+      return size unless size.is_a?(String) && size.match?(/\A\d+(\.\d+)?[KMG]?\z/i)
 
-    # Dereference arguments to log calls so we can have methods with compatibility with ::Logger
-    def call_add_entry(severity, message_or_progname_or_tags, progname_or_tags, &block) # :nodoc:
-      message = nil
-      progname = nil
-      tags = nil
-      if block
-        message = block
-        if message_or_progname_or_tags.is_a?(Hash)
-          tags = message_or_progname_or_tags
-          progname = progname_or_tags
-        else
-          progname = message_or_progname_or_tags
-          tags = progname_or_tags if progname_or_tags.is_a?(Hash)
-        end
-      else
-        message = message_or_progname_or_tags
-        if progname_or_tags.is_a?(Hash)
-          tags = progname_or_tags
-        else
-          progname = progname_or_tags
-        end
+      multiplier = case size[-1].upcase
+      when "K" then 1024
+      when "M" then 1024 * 1024
+      when "G" then 1024 * 1024 * 1024
+      else 1
       end
-      add_entry(severity, message, progname, tags)
-    end
 
-    # Merge a tags hash into an existing tags hash.
-    def merge_tags(current_tags, tags)
-      if current_tags.nil? || current_tags.empty?
-        tags
-      elsif tags.nil?
-        current_tags
-      else
-        current_tags.merge(tags)
-      end
+      (size.to_f * multiplier).round
     end
 
-    # Set a local value for a thread tied to this object.
-    def set_thread_local_value(name, value) # :nodoc:
-      values = Thread.current[name]
-      unless values
-        values = {}
-        Thread.current[name] = values
+    def takes_exactly_n_call_args?(callable, count)
+      params = if callable.is_a?(Proc)
+        callable.parameters
+      elsif callable.respond_to?(:call)
+        callable.method(:call).parameters
       end
-      if value.nil?
-        values.delete(self)
-        Thread.current[name] = nil if values.empty?
-      else
-        values[self] = value
-      end
-    end
 
-    # Get a local value for a thread tied to this object.
-    def thread_local_value(name) # :nodoc:
-      values = Thread.current[name]
-      values[self] if values
-    end
+      return false unless params
 
-    # Set a local value for a thread tied to this object within a block.
-    def push_thread_local_value(name, value) # :nodoc:
-      save_val = thread_local_value(name)
-      set_thread_local_value(name, value)
-      begin
-        yield
-      ensure
-        set_thread_local_value(name, save_val)
+      positional_arg_count = params.count do |type, _name|
+        type == :req || type == :opt
       end
-    end
 
-    # Open a logging device.
-    def open_device(device, options) # :nodoc:
-      if device.nil?
-        nil
-      elsif device.is_a?(Device)
-        device
-      elsif device.respond_to?(:write) && device.respond_to?(:flush)
-        Device::Writer.new(device, options)
-      elsif device == :null
-        Device::Null.new
-      else
-        device = device.to_s
-        if options[:roll]
-          Device::DateRollingLogFile.new(device, options)
-        elsif options[:max_size]
-          Device::SizeRollingLogFile.new(device, options)
-        else
-          Device::LogFile.new(device, options)
-        end
+      has_forbidden_args = params.any? do |type, _name|
+        [:rest, :keyreq, :key, :keyrest].include?(type)
       end
-    end
 
-    def write_to_device(entry) # :nodoc:
-      device.write(entry)
-    rescue => e
-      # rubocop:disable Style/StderrPuts
-      $stderr.puts("#{e.class.name}: #{e.message}#{" at " + e.backtrace.first if e.backtrace}")
-      $stderr.puts(entry.to_s)
-      # rubocop:enable Style/StderrPuts
-    end
-
-    # Create a thread that will periodically call flush.
-    def create_flusher_thread(flush_seconds) # :nodoc:
-      if flush_seconds > 0
-        logger = self
-        Thread.new do
-          until closed?
-            begin
-              sleep(flush_seconds)
-              logger.flush if Time.now - logger.last_flushed_at >= flush_seconds
-            rescue => e
-              warn("Error flushing log: #{e.inspect}")
-            end
-          end
-        end
-      end
+      positional_arg_count == 4 && !has_forbidden_args
     end
   end
 end