lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/io_compatibility.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # IOCompatibility provides methods that allow a logger to be used as an IO-like stream.
+  # This enables loggers to be used anywhere an IO object is expected, such as for
+  # redirecting standard output/error or integrating with libraries that expect stream objects.
+  #
+  # When used as a stream, all written values are logged with UNKNOWN severity and include
+  # timestamps and other standard log entry metadata. This is particularly useful for:
+  # - Capturing output from external libraries or subprocesses
+  # - Redirecting STDOUT/STDERR to logs
+  # - Providing a logging destination that conforms to IO interface expectations
+  #
+  # The module implements the essential IO methods like write, puts, print, printf, flush,
+  # and close to provide broad compatibility with Ruby's IO ecosystem.
+  #
+  # @example Basic stream usage
+  #   logger = Lumberjack::Logger.new(STDOUT)
+  #   logger.puts("Hello, world!")  # Logs with UNKNOWN severity
+  #   logger.write("Direct write")  # Also logs with UNKNOWN severity
+  #
+  # @example Setting the log entry severity
+  #   logger = Lumberjack::Logger.new(STDOUT)
+  #   logger.default_severity = :info
+  #   logger.puts("This is an info message") # Logs with INFO severity
+  #
+  # @example Using as STDOUT replacement
+  #   logger = Lumberjack::Logger.new("/var/log/app.log")
+  #   $stdout = logger  # Redirect all puts/print calls to the logger
+  #   puts "This goes to the log file"
+  module IOCompatibility
+    # Write a value to the log as a log entry. The value will be recorded with UNKNOWN severity,
+    # ensuring it always appears in the log regardless of the current log level.
+    #
+    # @param value [Object] The message to write. Will be converted to a string for logging.
+    # @return [Integer] Returns 1 if a log entry was written, or 0 if the value was nil or empty.
+    def write(value)
+      return 0 if value.nil? || value == ""
+
+      self << value
+      1
+    end
+
+    # Write multiple values to the log, each as a separate log entry with UNKNOWN severity.
+    # This method mimics the behavior of IO#puts by writing each argument on a separate line.
+    #
+    # @param args [Array<Object>] The messages to write. Each will be converted to a string.
+    # @return [nil]
+    def puts(*args)
+      args.each do |arg|
+        write(arg)
+      end
+      nil
+    end
+
+    # Concatentate strings into a single log entry. This mimics IO#print behavior
+    # by writing arguments without separators. If no arguments are given, writes the
+    # value of the global $_ variable.
+    #
+    # @param args [Array<Object>] The messages to write. If empty, uses $_ (last input record).
+    # @return [nil]
+    #
+    # @example
+    #   logger.print("Hello", " ", "World")  # Single log entry: "Hello World"
+    def print(*args)
+      if args.empty?
+        write($_)
+      else
+        write(args.join(""))
+      end
+      nil
+    end
+
+    # Write a formatted string to the log using sprintf-style formatting. The formatted
+    # result is logged as a single entry with UNKNOWN severity.
+    #
+    # @param format [String] The format string (printf-style format specifiers).
+    # @param args [Array<Object>] The values to substitute into the format string.
+    # @return [nil]
+    #
+    # @example
+    #   logger.printf("User %s logged in at %s", "alice", Time.now)
+    #   # Logs: "User alice logged in at 2025-08-21 10:30:00 UTC"
+    def printf(format, *args)
+      write(format % args)
+      nil
+    end
+
+    # Flush any buffered output. This method is provided for IO compatibility but
+    # is a no-op since log entries are typically written immediately to the underlying device.
+    # The actual flushing behavior depends on the logging device being used.
+    #
+    # @return [nil]
+    def flush
+    end
+
+    # Close the stream. This method is provided for IO compatibility but is a no-op.
+    # To actually close a logger, call close on the logger object itself, which will
+    # close the underlying logging device.
+    #
+    # @return [nil]
+    def close
+    end
+
+    # Check if the stream is closed. Always returns false since loggers using this
+    # module don't maintain a closed state through this interface.
+    #
+    # @return [Boolean] Always returns false.
+    def closed?
+      false
+    end
+
+    # Check if the stream is connected to a terminal (TTY). Always returns false
+    # since loggers are not terminal devices, even when they write to STDOUT/STDERR.
+    # This method is required for complete IO compatibility.
+    #
+    # @return [Boolean] Always returns false.
+    # @api private
+    def tty?
+      false
+    end
+
+    # Set the encoding for the stream. This method is provided for IO compatibility
+    # but is a no-op since loggers handle encoding internally through their devices
+    # and formatters.
+    #
+    # @param _encoding [String, Encoding] The encoding to set (ignored).
+    # @return [nil]
+    # @api private
+    def set_encoding(_encoding)
+    end
+  end
+end

data/lib/lumberjack/local_log_template.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # This is a log template designed for local environments. It provides a simple,
+  # human-readable format that includes key information about log entries while
+  # omitting extraneous details. The template can be configured to include or
+  # exclude certain components such as the times, process ID, program name,
+  # and attributes.
+  #
+  # It is registered with the TemplateRegistry as :local.
+  #
+  # @see Template
+  class LocalLogTemplate
+    TemplateRegistry.add(:local, self)
+
+    # Create a new LocalLogTemplate instance.
+    #
+    # @param options [Hash] Options for configuring the template.
+    # @option options [Boolean, Array<String>, nil] :exclude_attributes If true, all attributes are excluded.
+    #   If an array of strings is provided, those attributes (and their sub-attributes) are excluded.
+    #   Defaults to nil (include all attributes).
+    # @option options [Boolean] :exclude_progname If true, the progname is excluded. Defaults to false.
+    # @option options [Boolean] :exclude_pid If true, the process ID is excluded. Defaults to true.
+    # @option options [Boolean] :exclude_time If true, the time is excluded. Defaults to true.
+    # @option options [Boolean] :colorize If true, colorize the output based on severity. Defaults to false.
+    # @option options [Symbol, Formatter, #call] :exception_formatter The formatter to use for exceptions in messages.
+    #   Can be a symbol registered in the FormatterRegistry, a Formatter instance, or any object that responds to #call.
+    #   Defaults to nil (use default exception formatting). If the logger does not have an exception formatter
+    #   configured, then the device will use this to format exceptions.
+    # @option options [String, Symbol] :severity_format The optional format for severity labels (padded, char, emoji).
+    def initialize(options = {})
+      self.exclude_progname = options.fetch(:exclude_progname, false)
+      self.exclude_pid = options.fetch(:exclude_pid, true)
+      self.exclude_time = options.fetch(:exclude_time, true)
+      self.exclude_attributes = options.fetch(:exclude_attributes, nil)
+      self.colorize = options.fetch(:colorize, false)
+      self.severity_format = options.fetch(:severity_format, nil)
+      self.exception_formatter = options.fetch(:exception_formatter, :exception)
+    end
+
+    # Format a log entry according to the template.
+    #
+    # @param entry [LogEntry] The log entry to format.
+    # @return [String] The formatted log entry.
+    def call(entry)
+      message = entry.message
+      if message.is_a?(Exception) && exception_formatter
+        message = exception_formatter.call(message)
+      end
+
+      formatted = +""
+      formatted << entry.time.strftime("%Y-%m-%d %H:%M:%S.%6N ") unless exclude_time?
+      formatted << "#{severity_label(entry)} #{message}"
+      formatted << "#{Lumberjack::LINE_SEPARATOR}    progname: #{entry.progname}" if entry.progname.to_s != "" && !exclude_progname?
+      formatted << "#{Lumberjack::LINE_SEPARATOR}    pid: #{entry.pid}" unless exclude_pid?
+
+      if entry.attributes && !entry.attributes.empty? && !exclude_attributes?
+        Lumberjack::Utils.flatten_attributes(entry.attributes).to_a.sort_by(&:first).each do |name, value|
+          next if @attribute_filter.any? do |filter_name|
+            if name.start_with?(filter_name)
+              next_char = name[filter_name.length]
+              next_char.nil? || next_char == "."
+            end
+          end
+
+          formatted << "#{Lumberjack::LINE_SEPARATOR}    #{name}: #{value}"
+        end
+      end
+
+      formatted = Template.colorize_entry(formatted, entry) if colorize?
+      formatted << Lumberjack::LINE_SEPARATOR
+    end
+
+    # Return true if all attributes are excluded, false otherwise.
+    #
+    # @return [Boolean]
+    def exclude_attributes?
+      @exclude_attributes
+    end
+
+    # Return the list of excluded attribute names.
+    #
+    # @return [Array<String>]
+    def excluded_attributes
+      @attribute_filter.dup
+    end
+
+    # Set the attributes to exclude. If set to true, all attributes are excluded.
+    # If set to an array of strings, those attributes (and their sub-attributes)
+    # are excluded. If set to false or nil, no attributes are excluded.
+    #
+    # @param value [Boolean, Array<String>, nil]
+    # @return [void]
+    def exclude_attributes=(value)
+      @exclude_attributes = false
+      @attribute_filter = []
+      if value == true
+        @exclude_attributes = true
+      elsif value
+        @attribute_filter = Array(value).map(&:to_s)
+      end
+    end
+
+    # Return true if the progname is excluded, false otherwise.
+    #
+    # @return [Boolean]
+    def exclude_progname?
+      @exclude_progname
+    end
+
+    # Set whether to exclude the progname.
+    #
+    # @param value [Boolean]
+    # @return [void]
+    def exclude_progname=(value)
+      @exclude_progname = !!value
+    end
+
+    # Return true if the pid is excluded, false otherwise.
+    #
+    # @return [Boolean]
+    def exclude_pid?
+      @exclude_pid
+    end
+
+    # Set whether to exclude the pid.
+    #
+    # @param value [Boolean]
+    # @return [void]
+    def exclude_pid=(value)
+      @exclude_pid = !!value
+    end
+
+    # Return true if the time is excluded, false otherwise.
+    #
+    # @return [Boolean]
+    def exclude_time?
+      @exclude_time
+    end
+
+    # Set whether to exclude the time.
+    #
+    # @param value [Boolean]
+    # @return [void]
+    def exclude_time=(value)
+      @exclude_time = !!value
+    end
+
+    # Return true if colorization is enabled, false otherwise.
+    #
+    # @return [Boolean]
+    def colorize?
+      @colorize
+    end
+
+    # Set whether to enable colorization.
+    #
+    # @param value [Boolean]
+    # @return [void]
+    def colorize=(value)
+      @colorize = !!value
+    end
+
+    # Set the severity format.
+    #
+    # @param value [String, Symbol] The severity format (:padded, :char, :emoji, :level, nil).
+    # @return [void]
+    def severity_format=(value)
+      @severity_format = value.to_s
+    end
+
+    # Return the current severity format.
+    #
+    # @return [String]
+    attr_reader :severity_format
+
+    # Set the exception formatter. Can be a symbol registered in the FormatterRegistry,
+    # a Formatter instance, or any object that responds to #call.
+    #
+    # @param value [Symbol, Formatter, #call] The exception formatter to use.
+    # @return [void]
+    def exception_formatter=(value)
+      @exception_formatter = value.is_a?(Symbol) ? FormatterRegistry.formatter(value) : value
+    end
+
+    # Return the exception formatter.
+    #
+    # @return [#call, nil]
+    attr_reader :exception_formatter
+
+    private
+
+    def severity_label(entry)
+      severity = entry.severity_data
+      case severity_format
+      when "padded"
+        severity.padded_label
+      when "char"
+        severity.char
+      when "emoji"
+        severity.emoji
+      when "level"
+        severity.level.to_s
+      else
+        severity.label
+      end
+    end
+  end
+end

data/lib/lumberjack/log_entry.rb

@@ -1,139 +1,214 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  # An entry in a log is a data structure that captures the log message as well as
-  # information about the system that logged the message.
+  # A structured representation of a single log entry containing the message,
+  # metadata, and contextual information. LogEntry objects are immutable data
+  # structures that capture all relevant information about a logging event,
+  # including timing, severity, source identification, and custom attributes.
+  #
+  # This class serves as the fundamental data structure passed between loggers,
+  # formatters, and output devices throughout the Lumberjack logging pipeline.
+  # Each entry maintains consistent structure while supporting flexible attribute
+  # attachment for contextual logging scenarios.
   class LogEntry
-    attr_accessor :time, :message, :severity, :progname, :pid, :tags
-
-    TIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
-
-    # @deprecated Will be removed in version 2.0.
-    UNIT_OF_WORK_ID = "unit_of_work_id"
-
-    # Create a new log entry.
+    # @!attribute [rw] time
+    #   @return [Time] The timestamp when the log entry was created
+    # @!attribute [rw] message
+    #   @return [String] The primary log message content
+    # @!attribute [rw] severity
+    #   @return [Integer] The numeric severity level of the log entry
+    # @!attribute [rw] progname
+    #   @return [String] The name of the program or component that generated the entry
+    # @!attribute [rw] pid
+    #   @return [Integer] The process ID of the logging process
+    # @!attribute [rw] attributes
+    #   @return [Hash<String, Object>] Custom attributes associated with the log entry
+    attr_accessor :time, :message, :severity, :progname, :pid, :attributes
+
+    TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%3N"
+
+    # Create a new log entry with the specified components. The entry captures
+    # all relevant information about a logging event in a structured format.
     #
-    # @param time [Time] The time the log entry was created.
-    # @param severity [Integer, String] The severity of the log entry.
-    # @param message [String] The message to log.
-    # @param progname [String] The name of the program that created the log entry.
-    # @param pid [Integer] The process id of the program that created the log entry.
-    # @param tags [Hash<String, Object>] A hash of tags to associate with the log entry.
-    def initialize(time, severity, message, progname, pid, tags)
+    # @param time [Time] The timestamp when the log entry was created
+    # @param severity [Integer, String, Symbol] The severity level, accepts numeric levels or labels
+    # @param message [String] The primary log message content
+    # @param progname [String, nil] The name of the program or component generating the entry
+    # @param pid [Integer] The process ID of the logging process
+    # @param attributes [Hash<String, Object>, nil] Custom attributes to associate with the entry
+    def initialize(time, severity, message, progname, pid, attributes)
       @time = time
       @severity = (severity.is_a?(Integer) ? severity : Severity.label_to_level(severity))
       @message = message
       @progname = progname
       @pid = pid
-      # backward compatibility with 1.0 API where the last argument was the unit of work id
-      @tags = if tags.is_a?(Hash)
-        compact_tags(tags)
-      elsif !tags.nil?
-        {UNIT_OF_WORK_ID => tags}
-      end
+      @attributes = flatten_attributes(attributes) if attributes.is_a?(Hash)
     end
 
+    # Get the human-readable severity label corresponding to the numeric severity level.
+    #
+    # @return [String] The severity label (DEBUG, INFO, WARN, ERROR, FATAL, or UNKNOWN)
     def severity_label
-      Severity.level_to_label(severity)
+      severity_data.label
+    end
+
+    # Get the data corresponding to the severity. This include variations on the severity label.
+    def severity_data
+      Severity.data(severity)
     end
 
+    # Generate a formatted string representation of the log entry suitable for
+    # human consumption. Includes timestamp, severity, program name, process ID,
+    # attributes, and the main message.
+    #
+    # @return [String] A formatted string representation of the complete log entry
     def to_s
-      "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, "0")} #{severity_label} #{progname}(#{pid})#{tags_to_s}] #{message}"
+      msg = +"[#{time.strftime(TIME_FORMAT)} #{severity_label} #{progname}(#{pid})] #{message}"
+      attributes&.each do |key, value|
+        msg << " [#{key}:#{value}]"
+      end
+      msg
     end
 
+    # Return a string representation suitable for debugging and inspection.
+    #
+    # @return [String] The same as {#to_s}
     def inspect
       to_s
     end
 
-    # @deprecated - backward compatibility with 1.0 API. Will be removed in version 2.0.
-    def unit_of_work_id
-      Lumberjack::Utils.deprecated("Lumberjack::LogEntry#unit_of_work_id", "Lumberjack::LogEntry#unit_of_work_id will be removed in version 2.0") do
-        tags[UNIT_OF_WORK_ID] if tags
-      end
+    # Compare this log entry with another for equality. Two log entries are
+    # considered equal if all their components match exactly.
+    #
+    # @param other [Object] The object to compare against
+    # @return [Boolean] True if the entries are identical, false otherwise
+    def ==(other)
+      return true if equal?(other)
+      return false unless other.is_a?(LogEntry)
+
+      time == other.time &&
+        severity == other.severity &&
+        message == other.message &&
+        progname == other.progname &&
+        pid == other.pid &&
+        attributes == other.attributes
     end
 
-    # @deprecated - backward compatibility with 1.0 API. Will be removed in version 2.0.
-    def unit_of_work_id=(value)
-      Lumberjack::Utils.deprecated("Lumberjack::LogEntry#unit_of_work_id=", "Lumberjack::LogEntry#unit_of_work_id= will be removed in version 2.0") do
-        if tags
-          tags[UNIT_OF_WORK_ID] = value
-        else
-          @tags = {UNIT_OF_WORK_ID => value}
-        end
+    # Alias for tags to provide backward compatibility with version 1.x API. This method
+    # will eventually be removed.
+    #
+    # @return [Hash, nil] The attributes of the log entry.
+    # @deprecated Use {#attributes} instead.
+    def tags
+      Utils.deprecated("LogEntry#tags", "Lumberjack::LogEntry#tags is deprecated and will be removed in version 2.1; use attributes instead.") do
+        attributes
       end
     end
 
-    # Return the tag with the specified name.
+    # Access an attribute value by name. Supports both simple and nested attribute
+    # access using dot notation for hierarchical data structures.
     #
-    # @param name [String, Symbol] The tag name.
-    # @return [Object, nil] The tag value or nil if the tag does not exist.
-    def tag(name)
-      return nil if tags.nil?
+    # @param name [String, Symbol] The attribute name, supports dot notation for nested access
+    # @return [Object, nil] The attribute value or nil if the attribute does not exist
+    def [](name)
+      return nil if attributes.nil?
 
-      TagContext.new(tags)[name]
+      AttributesHelper.new(attributes)[name]
     end
 
-    # Helper method to expand the tags into a nested structure. Tags with dots in the name
-    # will be expanded into nested hashes.
+    # Alias method for #[] to provide backward compatibility with version 1.x API. This
+    # method will eventually be removed.
     #
-    # @return [Hash] The tags expanded into a nested structure.
+    # @return [Hash]
+    # @deprecated Use {#[]} instead.
+    def tag(name)
+      Utils.deprecated("LogEntry#tag", "Lumberjack::LogEntry#tag is deprecated and will be removed in version 2.1; use [] instead.") do
+        self[name]
+      end
+    end
+
+    # Expand flat attributes with dot notation into a nested hash structure.
+    # Attributes containing dots in their names are converted into hierarchical
+    # nested hashes for structured data representation.
     #
-    # @example
-    #   entry = Lumberjack::LogEntry.new(Time.now, Logger::INFO, "test", "app", 1500, "a.b.c" => 1, "a.b.d" => 2)
-    #   entry.nested_tags # => {"a" => {"b" => {"c" => 1, "d" => 2}}}
+    # @return [Hash] The attributes expanded into a nested structure
+    def nested_attributes
+      Utils.expand_attributes(attributes)
+    end
+
+    # Alias for nested_attributes to provide API compatibility with version 1.x.
+    # This method will eventually be removed.
+    #
+    # @return [Hash]
+    # @deprecated Use {#nested_attributes} instead.
     def nested_tags
-      Utils.expand_tags(tags)
+      Utils.deprecated("LogEntry#nested_tags", "Lumberjack::LogEntry#nested_tags is deprecated and will be removed in version 2.1; use nested_attributes instead.") do
+        nested_attributes
+      end
     end
 
-    # Return true if the log entry has no message and no tags.
+    # Determine if the log entry contains no meaningful content. An entry is
+    # considered empty if it has no message content and no attributes.
     #
-    # @return [Boolean] True if the log entry is empty, false otherwise.
+    # @return [Boolean] True if the entry is empty, false otherwise
     def empty?
-      (message.nil? || message == "") && (tags.nil? || tags.empty?)
+      (message.nil? || message == "") && (attributes.nil? || attributes.empty?)
+    end
+
+    # Convert the log entry into a hash suitable for JSON serialization. Attributes will be expanded
+    # into a nested structure (i.e. { "user.id" => 123 } becomes `{ "user" => { "id" => 123 } }).
+    # Severities will be converted to their string labels.
+    #
+    # @return [Hash] The JSON representation of the log entry
+    def as_json
+      {
+        "time" => time,
+        "severity" => severity_label,
+        "message" => message,
+        "progname" => progname,
+        "pid" => pid,
+        "attributes" => Utils.expand_attributes(attributes)
+      }
     end
 
     private
 
-    def tags_to_s
-      tags_string = +""
-      tags&.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
-      tags_string
+    # Generate a string representation of all attributes for inclusion in the
+    # formatted output. Each attribute is formatted as key:value pairs.
+    #
+    # @return [String] A formatted string of all attributes
+    def attributes_to_s
+      attributes_string = +""
+      attributes&.each { |name, value| attributes_string << " #{name}:#{value.inspect}" }
+      attributes_string
     end
 
-    def compact_tags(tags, seen = nil)
-      return {} if seen&.include?(tags.object_id)
+    # Flatten nested attributes and remove empty values.
+    #
+    # @param attributes [Hash] The attributes hash to compact
+    # @return [Hash] The flattened attributes with empty values removed
+    def flatten_attributes(attributes)
+      unless attributes.all? { |key, value| key.is_a?(String) && !value.is_a?(Hash) }
+        attributes = Utils.flatten_attributes(attributes)
+      end
 
       delete_keys = nil
-      compacted_keys = nil
-
-      tags.each do |key, value|
+      attributes.each do |key, value|
         if value.nil? || value == ""
           delete_keys ||= []
           delete_keys << key
-        elsif value.is_a?(Hash)
-          seen ||= Set.new
-          seen << tags.object_id
-          compacted_value = compact_tags(value, seen)
-          if compacted_value.empty?
-            delete_keys ||= []
-            delete_keys << key
-          elsif !value.equal?(compacted_value)
-            compacted_keys ||= []
-            compacted_keys << [key, compacted_value]
-          end
         elsif value.is_a?(Array) && value.empty?
           delete_keys ||= []
           delete_keys << key
         end
       end
 
-      return tags if delete_keys.nil? && compacted_keys.nil?
+      return attributes if delete_keys.nil?
 
-      tags = tags.dup
-      delete_keys&.each { |key| tags.delete(key) }
-      compacted_keys&.each { |key, value| tags[key] = value }
+      attributes = attributes.dup
+      delete_keys&.each { |key| attributes.delete(key) }
 
-      tags
+      attributes
     end
   end
 end